12.7 How to propose a change
A contributor path from design gap to spec PR, implementation, and trudoc verify.
How to propose a change
You found a bug or a missing feature. Excellent. Here is how to avoid becoming another “we’ll document it later” statistic.
1. Classify ownership
Section titled “1. Classify ownership”Use language law vs implementation:
- User-visible semantics → extend language-meta first.
- CLI/manifest/LSP → tooling with links back.
- Runtime/GC/fibers → execution + language-meta cross-links.
corelibAPI → core-library.
2. Write or update spec
Section titled “2. Write or update spec”- Pick the correct feature hub under
/platform-spec/. - Add normative prose, diagnostics codes, and
relatedTopicsdeferrals—not duplicated tables. - For closed choices, add an
adr/file or hub Decisions row. - Run
cd site/website && bun run verify:trudoc -- --preset ciafter edits.
Templates: Feature hub + article bundle, Frontmatter template.
3. Implement with anchors
Section titled “3. Implement with anchors”Update compiler/ (or corelib/tooling) and refresh crate-to-spec anchors when crate boundaries move.
4. Verify
Section titled “4. Verify”| Check | Command / location |
|---|---|
| Spec layout + frontmatter | bun run verify:trudoc -- --preset ci |
| Compiler behavior | cargo test in compiler/, beskid_tests fixtures |
| Strict spec content (optional) | verify:platform-spec-content --strict |
5. Informative follow-up
Section titled “5. Informative follow-up”Update book chapters or reference when tutorials should reflect the new world—after normative text lands.