CONTRIBUTING.md (4200B)
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 Release V2 records the twenty-two current public Lib packages, including 14 `radroots_sdk` and `radroots`. The earlier `radroots.crates.release.v1` 15 repository split remains immutable history. The approved successor is 16 `contracts/architecture/decisions/shared_sdk_refactor.v1.json`: Lib owns shared 17 semantics and execution, `radroots` remains the facade, and the SDK repository 18 consumes source-owned generators and artifacts. Its target package graph is 19 prospective; implementation, compiler migration and qualification require 20 their actual source-bound checks before acceptance. 21 22 ## Source and behavior provenance 23 24 Reusable application behavior is independently reimplemented in Lib under 25 the shared SDK decision. Referencing Tera's GPL application behavior does not 26 authorize copying or translating its implementation, test bodies, fixtures or 27 generated derivatives into differently licensed packages. Organizational 28 ownership and a Cargo license field do not establish a separate rights grant. 29 Preserve the original source and notices; retain each meaningful test purpose 30 through independently authored successor cases before removing its old owner. 31 32 For an affected implementation, record the exact source repository, revision, 33 path, declared license, retained behavior and successor test. Preserve imported 34 catalog provenance and existing third-party notices. New repository-native 35 packages use the catalog's native introduction-tree mechanism. Neither a 36 catalog entry nor a rewritten implementation claims rights to relicense its 37 references. 38 39 Retained optional capabilities, including mesh, Reticulum, SimpleX, NostrDB 40 and replica support, keep their source and proving obligations. Before exposing 41 them in a supported artifact, review the actual target and feature dependency 42 closure, upstream material and redistribution notices. Resolve incompatible or 43 unverified reuse at its owner; do not discard the approved capability or infer 44 dependency licensing from the workspace license. Generate artifact notices 45 from their source-owned inputs and bind them to the actual shipped bytes. 46 47 ## Workflow 48 49 1. Inspect repository status and the current source authority. 50 2. Make one coherent, commit-sized change. 51 3. Update public contracts, tests, fixtures, generated authorities, and docs 52 with the implementation they govern. 53 4. Run the narrowest repository-owned validation that proves the change, then 54 the broader contract or release lane required by its scope. 55 5. Review the staged diff for API leakage, private dependencies, generated 56 drift, secrets, hidden side effects, and unrelated changes. 57 58 Run `cargo extbuild doctor` before governed verification. Canonical 59 repository-wide lanes are the extbuild-routed workspace format, check, test, 60 Clippy, Rustdoc, contract, release-preflight, coverage, and 61 generated-freshness commands. Nix evaluation and Nix-derived outputs are 62 currently deferred and unclaimed; they are not prerequisites for native 63 qualification. 64 65 ## Commits and deviations 66 67 Use this commit form: 68 69 ```text 70 <scope>: <lower-case imperative summary> 71 ``` 72 73 Keep commits focused and keep public commit language independent of any 74 private checkout. Do not publish, tag, merge, or change registry ownership 75 without explicit authorization. 76 77 When current evidence proves a planned step obsolete or unsafe, update 78 `contracts/architecture/deviations.toml` and validate it with 79 `cargo xtask architecture`. Record the evidence and affected machine-contract 80 anchor before changing the plan. Anchors must use a validated Release V1 TOML 81 selector (`repositories.<name>`, `repository_policy`, `release_policy`, 82 `quality_policy.coverage`, or `package.<name>`); Markdown heading fragments are 83 not machine anchors. A normative change also requires the applicable machine 84 decision. Do not silently redefine the architecture.