CONTRIBUTING.md (2353B)
1 # Contributing 2 3 Radroots core-library changes are contract-driven and independently 4 reviewable. Before editing, read these files in order: 5 6 1. `AGENTS.md` 7 2. `AGENT_INSTRUCTIONS.md` 8 3. `contracts/crates/release.v2.toml` 9 4. `contracts/crates/release_v1/radroots_crates_release_v1.toml` for 10 crate-surface work 11 5. the affected manifests, implementation, contracts, and tests 12 13 The release-v1 architecture identifier is `radroots.crates.release.v1`. This 14 repository owns its first 17 public packages, from `radroots_core` through 15 `radroots_geonames`; the standalone SDK repository owns `radroots_sdk` and 16 `radroots`. 17 18 ## Workflow 19 20 1. Inspect repository status and the current source authority. 21 2. Make one coherent, commit-sized change. 22 3. Update public contracts, tests, fixtures, generated authorities, and docs 23 with the implementation they govern. 24 4. Run the narrowest repository-owned validation that proves the change, then 25 the broader contract or release lane required by its scope. 26 5. Review the staged diff for API leakage, private dependencies, generated 27 drift, secrets, hidden side effects, and unrelated changes. 28 29 Run `cargo extbuild doctor` before governed verification. Canonical 30 repository-wide lanes are the extbuild-routed workspace format, check, test, 31 Clippy, Rustdoc, contract, release-preflight, coverage, and 32 generated-freshness commands. Nix evaluation and Nix-derived outputs are 33 currently deferred and unclaimed; they are not prerequisites for native 34 qualification. 35 36 ## Commits and deviations 37 38 Use this commit form: 39 40 ```text 41 <scope>: <lower-case imperative summary> 42 ``` 43 44 Keep commits focused and keep public commit language independent of any 45 private checkout. Do not publish, tag, merge, or change registry ownership 46 without explicit authorization. 47 48 When current evidence proves a planned step obsolete or unsafe, update 49 `contracts/architecture/deviations.toml` and validate it with 50 `cargo xtask architecture`. Record the evidence and affected machine-contract 51 anchor before changing the plan. Anchors must use a validated Release V1 TOML 52 selector (`repositories.<name>`, `repository_policy`, `release_policy`, 53 `quality_policy.coverage`, or `package.<name>`); Markdown heading fragments are 54 not machine anchors. A normative change also requires the applicable machine 55 decision. Do not silently redefine the architecture.