Skip to content

Contributing

House rules

  • Safe Rust in the front-end: the parser, resolver, type checker, MIR, LLVM codegen, lints, and scheduler crates forbid unsafe_code. The runtime, the Cranelift JIT, the stackful-coroutine layer, and the FFI binding surface contain contained, reviewed unsafe (C ABIs, executing generated code, context switching) - keep it in the smallest possible scope.
  • cargo clippy --workspace --all-targets -- -D warnings is the gate.
  • cargo fmt --all --check must pass.
  • One focused change per PR. No drive-by refactors.

The full style guide is in GUIDELINES.md.

Getting oriented

  • Start with the language spec for grammar and semantics.
  • Each crate under crates/ has a module-level //! doc describing the compiler phase it belongs to.
  • Design notes live under docs/ (diagnostics style guide, runtime internals, self-hosting study).

Picking an issue

Streams ordered by impact, smallest to biggest:

  1. Landing a new lint in gossamer-lint (the framework is in place; each lint is ~20 lines).
  2. Wiring a new native stdlib module (see the std::regex wrapper for the pattern).
  3. Extending the diagnostics style guide with acceptance fixtures.
  4. Closing a security item in the roadmap.
  5. Implementing a major language feature (Cranelift codegen, scheduler, LSP capabilities beyond the shipped slice).

Running the tests

cargo test --workspace

Per-crate:

cargo test -p gossamer-mir
cargo test -p gossamer-std --lib

Release benches:

cargo bench -p gossamer-interp

Docs

pip install mkdocs
mkdocs serve

Opens at http://localhost:8000/. Edit docs_src/*.md and save; the site reloads.

Every ```gossamer fence under docs_src is checked by crates/gossamer-cli/tests/docs_fences.rs and must be a program gos check accepts. A fence that is a piece of a larger program the prose describes is preceded by <!-- fragment -->; one that shows a rejected program is preceded by <!-- compile_fail CODE --> and must fail with that diagnostic. Both markers are HTML comments, so they do not render.

Stdlib pages are generated by gos doc --emit-stdlib docs_src/stdlib, which also writes each module's item table from the manifest and the checker's signatures; --check fails when a page drifts or a description names a library path no module declares.