Contributing
Design notes
Use the design notes alongside the language standard.
The files in docs/design explain reasoning, investigations, and plans. Use them to understand a decision or find implementation context, then check the standard for the rule that applies today. A design note can describe historical code or proposed work; it does not replace docs/spec.md.
The generated design note index lists every note. Its generator labels syntax-3.md as in force and files ending in -report as historical; other notes need a status review. Check a note’s own status and the current tree before relying on its implementation claims.
- Syntax and compiler trees: syntax-3.md explains the controlling syntax design. ast-hir-merge.md evaluates the syntax and checked trees.
- Types: principality.md presents the inference argument and its unproven parts. known-types-are-facts.md discusses known types.
- Runtime and host: runtime.md discusses tasks and IO; native.md covers native execution. These are design documents, so compare their proposals to the current code and standard.
- Macros and tests: meta.md explains the metaprogramming design; testing-macro.md describes the test macros.
- Conformance: spec-known-gaps.md tracks specified rules the compiler does not yet implement, including a known unsound case.