Skip to content
Typhon

Contributing

Typhon is open to contributions. The project is small enough that you can read the whole thing in a weekend; the scope is well-defined; the test suite is fast.

Before you start

  1. Check the roadmap. If your feature isn’t there, file an issue first to confirm it fits.
  2. Check the risks. Some additions are intentionally deferred.
  3. Read the design decisions. The constitution of the language.

Setting up

  1. Fork and clone:

    Terminal window
    git clone https://github.com/CodeHalwell/Typhon.git
    cd Typhon

  2. Build:

    Terminal window
    cd tyc && cargo build --release

  3. Run the tests:

    Terminal window
    cargo test --workspace

  4. Verify the docs site builds (if you’re changing docs):

    Terminal window
    cd ../docs-site && npm install && npm run build

Patch hygiene

  • One concern per PR. Mixing a bug fix with a feature makes reviews painful.
  • Add a test for every behaviour change. The test corpus is fast; there’s no reason not to.
  • Run cargo fmt --workspace and cargo clippy --workspace --all-targets --all-features -- -D warnings before pushing. CI treats every warning as an error.
  • Run cargo deny check for dependency audits. (Not always required for docs-only PRs.)
  • Know the nine CI jobs that run on every push to main, dev/**, and claude/**: test (cargo fmt --check → clippy → cargo test --workspace), test-macos (the test suite on macOS), fmt-guard (no out-of-scope cargo fmt reformats), security (cargo-deny — advisories, licences, source/registry bans per tyc/deny.toml), perf-gate (scripts/perf-gate.sh — the full tyc build pipeline over a fixed corpus must not regress >20% past perf-baseline.json), differential (the VM ↔ CPython differential gate over the whole examples/ + stress/ corpus; its baseline may only shrink), knob-matrix (the opt-in-knob codegen matrix), valid-corpus (tyc check plus the VM ↔ CPython differential over the corpus/valid/ valid-programs corpus; its baseline may only shrink), and fmt-corpus (scripts/emitted-ast.py fmt-gate — tyc fmt over a de-formatted copy of the corpus must leave every unit’s emitted Python AST unchanged). A compiler change should keep all nine green; a docs-only change only exercises test.

Where to make changes

ChangeCrate
Parse / lextyc-syntax (plus the vendored Ruff fork)
Scope / binding rulestyc-resolve
Type systemtyc-types
Purity / async / comptimetyc-analyse
Loweringtyc-desugar
Python outputtyc-emit
Source mapstyc-emit
Diagnosticstyc-diagnostics (plus the emission site)
LSPtyc-lsp
CLItyc/crates/tyc

Adding a feature

The high-level pattern:

  1. Design. Open an issue. Get feedback. The design is what’s hard; the implementation usually follows.
  2. Tests first. Write a .ty file in the integration test corpus that exercises the feature. Watch the test fail.
  3. Implement. Modify the relevant crate(s).
  4. Make the test pass.
  5. Document. Add or update pages under docs-site/src/content/docs/.

Style

  • Rust: standard rustfmt style. cargo fmt --workspace is the source of truth.
  • Comments: explain why, not what. The code already says what.
  • Public APIs: doc-comment them.

PR description

  • What changes and why.
  • Which issue (if any) it closes.
  • Migration notes if behaviour changes.
  • Test plan: which tests cover the change.

Code of conduct

Be kind, be clear, be brief. We do not have a long CoC; common decency is the rule.

Where next