Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
117 lines (87 loc) · 4.1 KB

CONTRIBUTING.md

File metadata and controls

117 lines (87 loc) · 4.1 KB
Raw

Contributing to C-Two

Thanks for your interest in contributing! C-Two is a resource-oriented RPC framework with a Python front-end and Rust native layer. This guide covers everything you need to get started.

Dev Setup

Prerequisites: Python ≥ 3.10, Rust toolchain, uv package manager.

git clone https://github.com/world-in-progress/c-two.git
cd c-two
uv sync  # installs dependencies and builds the Python SDK native extension

Relay tests and examples use the standalone Rust c3 relay runtime. From a source checkout, build and link the local c3 binary before running relay flows:

python tools/dev/c3_tool.py --build --link
c3 relay --bind 127.0.0.1:8080

To force-rebuild after Rust source changes:

uv sync --reinstall-package c-two

Running Tests

# Full Python test suite (set C2_RELAY_ANCHOR_ADDRESS= to avoid env interference)
C2_RELAY_ANCHOR_ADDRESS= uv run pytest sdk/python/tests/ -q --timeout=30

# Single file / single test
uv run pytest sdk/python/tests/unit/test_wire.py -q
uv run pytest sdk/python/tests/unit/test_transferable.py::TestTransferableDecorator::test_hello_data_round_trip -q

# Rust core tests
cargo test --manifest-path core/Cargo.toml --workspace

# Python SDK native extension and tests
uv sync --reinstall-package c-two
C2_RELAY_ANCHOR_ADDRESS= uv run pytest sdk/python/tests -q --timeout=30

All new code must include tests. Ensure the full suite passes before opening a PR.

Submitting Changes

  1. Fork the repository and clone your fork.
  2. Create a branch from main with a descriptive name (e.g., feat/grid-pagination, fix/shm-leak).
  3. Make your changes in small, focused commits.
  4. Push to your fork and open a Pull Request against main.
  5. Describe what and why in the PR body. Link related issues if applicable.

Commit Messages

We encourage Conventional Commits:

feat: add chunked transfer support for large payloads
fix: prevent double-free in buddy allocator
docs: update CRM contract examples
test: add integration test for relay mesh
refactor: simplify MethodTable index lookup

Code Style

Python

  • Import alias: always import c_two as cc.
  • Type hints required — use modern syntax (list[int], str | None). No from __future__ needed (Python ≥ 3.10).
  • CRM contracts: plain class names, no I prefix (Grid, not IGrid). Method bodies are ... (ellipsis).
  • Resource classes: named by domain semantics (NestedGrid), not by the contract.
  • Transferable types: do not add @staticmethod to serialize/deserialize/from_buffer — the metaclass handles it.
  • Follow existing formatting conventions in the file you're editing.

Rust

  • Code lives in core/ (a Cargo workspace of 7 crates).
  • Run cargo test --manifest-path core/Cargo.toml --workspace before submitting core changes.
  • The Python SDK native extension lives in sdk/python/native/; rebuild it with uv sync --reinstall-package c-two before submitting Python SDK native changes.
  • Prefer zero-copy and single-allocation patterns in wire/transport code.

Project Structure

core/
├── foundation/
├── protocol/
└── transport/
cli/
└── src/          # Native c3 CLI
sdk/python/src/c_two/
├── crm/          # CRM contracts, @transferable, decorators
├── transport/    # Registry, proxy, server bridge, scheduler
├── config/       # Python override facades backed by Rust config resolution
└── mem/          # Python wrappers for Rust memory subsystem
sdk/python/native/
└── src/          # PyO3 extension crate for c_two._native
sdk/python/tests/
├── unit/
├── integration/
└── fixtures/     # Shared test CRM contracts and resources
examples/python/

Environment Variables

Tests may be affected by C2_* environment variables. Always prefix test runs with C2_RELAY_ANCHOR_ADDRESS= to isolate from your local environment. See .env.example for the full reference.

Questions?

Open an issue or start a discussion on the repository. We're happy to help!