12.7 How to propose a change
A contributor path from design gap to OpenSpec change, implementation, and validation.
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”- Find the capability in
openspec/catalog.jsonand edit it through anopenspec/changes/<change>/delta. - Put normative behavior in
### Requirement:sections with at least one#### Scenario:. - Keep tutorials and rationale in the Book; link them with typed
specandbookembeds. - Run
openspec validate --all --strictfrom the repository root after 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 |
|---|---|
| OpenSpec structure and deltas | openspec validate --all --strict |
| Compiler behavior | cargo test in compiler/, beskid_tests fixtures |
| Repository conformance gate | bash scripts/ci/openspec-gate.sh |
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.