Contributing

Read docs/development/onboarding.md first.

Branches and pull requests

• Never commit on main. Every change starts on a branch named <area>/<topic>, where area is the part of the compiler the change belongs to: frontend, semantic, validation, library, targets, driver, docs, or tools.
• One branch is one coherent change, including its tests and the documents it affects. Do not mix unrelated fixes on one branch.
• Rebase on main before opening the pull request; history stays linear.
• The pull request description says what changed, why, and which commands you ran. A change that alters public behavior, syntax, diagnostics, or emitted files says so explicitly.

Work procedure

Before editing, read the relevant documents in docs/, look at the affected code and its tests, and identify which compiler phase owns the behavior.

While editing:

• Make the smallest coherent change that satisfies the task.
• Keep source spans and deterministic output.
• Do not add abstractions or compatibility layers the current design does not need.
• Do not weaken diagnostics to make invalid input pass.
• Do not hand-edit generated files; run the generator.

After editing, add or update the tests that cover the change, run them, and update any document whose description of public behavior changed. The pages under docs/, this file and the CHANGELOG are published on the project's public site, where this repository cannot be opened: they say what a change is, not which issue or pull request of this repository it came from. Commit messages and source comments may name them, but not the comments of a file the documentation includes, such as the demo programs under examples/ that the getting-started guide shows.