lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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.