app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

CONTRIBUTING.md (6517B)


      1 # Contributing
      2 
      3 ## Start with the repository contract
      4 
      5 Read `AGENTS.md` before changing product behaviour or architecture. When this
      6 repository is consumed by the Radroots monorepo, also read the relevant
      7 normative material under its `docs/oss/harvestcircle/` tree. Standalone changes
      8 must not add normative documentation roots to this repository.
      9 
     10 ## Runtime ownership
     11 
     12 Native presentation belongs in `app/`; product-specific Rust, SQLx persistence,
     13 native signing and OS keyring orchestration belong in `core/`. Root Gradle and
     14 native configuration retain their existing ownership. Keep generated UniFFI
     15 bindings derived from the canonical Rust producer.
     16 
     17 The browser bootstrap exists in `web/` with SvelteKit, strict TypeScript,
     18 static output, and web-owned package inputs. Its IndexedDB, sessions, explicit
     19 extension signing, and Applesauce Nostr adapters are separate from native
     20 storage, custody, and FFI. Use Node 24.21.0 and Corepack with pnpm 12.9.1,
     21 then `make web-doctor`, `make web-install`, `make web-check`, and
     22 `make web-build`; `make web-dev` starts the guarded Vite server. Follow
     23 `web/AGENTS.md`; ordinary browser work must not depend
     24 on Cargo, Gradle, native binaries, or parent artifacts.
     25 
     26 Shared public conformance vectors are planned under `contracts/interop/`.
     27 They test the exact pinned Radroots semantics rather than establish new shared
     28 protocol policy. Current static-shell conformance runs through `web-check`;
     29 Food/Message interop and real extension/relay qualification remain pending.
     30 
     31 Run commands from this checkout's root, including when the path contains
     32 spaces; from elsewhere use `make -C "/path/to/HarvestCircle" <target>`.
     33 Native commands require Rust 1.99.0, the pinned JDK/Gradle wrapper and the
     34 supported host's native prerequisites described in README. They do not require
     35 Node or pnpm. Browser commands require the pinned Node/Corepack/pnpm inputs,
     36 Make and ordinary shell/Git utilities; they do not require Rust, Java or Gradle
     37 in standalone mode. Governed browser execution additionally requires extbuild.
     38 Install tooling explicitly before diagnosis; `web-doctor` checks selected
     39 versions without fetching a missing package manager, and `web-install` is the
     40 explicit frozen dependency installation step.
     41 
     42 `web-check` runs check, lint, unit/provenance and static conformance scripts;
     43 conformance also builds the static output. Integration and browser suites are
     44 separate existing package scripts: from `web/`, run `corepack pnpm run
     45 test:integration` and `corepack pnpm run test:e2e`. The browser suite requires
     46 its qualified Playwright browser. `web-dev` and `native-dev` start their
     47 respective runtime; neither installs the other runtime's dependencies.
     48 
     49 Unqualified `dev`, `check`, `build`, `package-check` and `clean` retain native
     50 meaning. `clean` removes native Cargo output for both Rust graphs and Gradle
     51 output for the root and included build; it is not part of routine verification.
     52 It does not request deletion of browser dependencies, static output, local
     53 browser state, sibling source or desktop user data. There is no root web-clean,
     54 check-all, repo-check, interop-check or web-integration-check target currently;
     55 do not substitute an absent target for an executed check. To verify both
     56 runtimes, select the existing native and browser lanes explicitly and supply
     57 all their prerequisites. Package/release qualification retains its separate
     58 authority and does not follow implicitly from development checks.
     59 
     60 `make mode-check` executes disposable command-boundary fixtures for both
     61 modes, including tool isolation, checkout cwd, missing tools, failures and
     62 bounded clean effects. The tools in those fixtures are stand-ins: passing them
     63 does not qualify product execution or prove the workstation lacks a toolchain.
     64 Changes to root dispatch or its tests require fresh affected native and browser
     65 checks; unchanged-native evidence cannot be reused for such changes.
     66 
     67 ## Development flow
     68 
     69 1. Use the current development branch policy and work from this capsule root.
     70 2. Make one coherent change at a time.
     71 3. Add or update tests.
     72 4. Run focused checks for the affected runtime and repository boundaries.
     73    Native `make native-doctor`, `make native-dev`, `make native-check`,
     74    `make native-build`, and `make native-package-check` alias the existing
     75    native targets without changing their prerequisites or evidence rules.
     76 5. In the standalone native lane, run `make native-doctor`, then:
     77 
     78 ```sh
     79 make format
     80 make lint
     81 make test
     82 make check
     83 ```
     84 
     85 6. Do not hand-edit generated UniFFI code.
     86 7. Do not include secrets or private event plaintext.
     87 8. Document intentional architecture deviations.
     88 
     89 Standalone is the default build mode and requires no extbuild or private
     90 parent. Where governed execution is required, run `cargo extbuild doctor`
     91 first and use `BUILD_MODE=governed` on the native targets. Existing
     92 `governed-check`, `governed-integration-check`, `governed-development-check`,
     93 and `governed-linux-x86_64-development-check` select their governed native
     94 lanes. Follow the README for development qualification; package/release checks
     95 remain deferred and require separate candidate authority.
     96 
     97 Parent orchestration may invoke these standalone lanes for integration, but
     98 must not become a build/test prerequisite. Keep normative records in the
     99 consuming parent's documentation; do not add `docs/`, `spec/`, `.github/`, or
    100 `.act/` here. Standalone inputs must not require private contracts, unpublished
    101 artifacts, implicit sibling checkouts, or absolute host paths.
    102 
    103 Preserve the artifact-v3 exact clean Git-tree archive contract, including
    104 tracked browser source. Do not relabel a native-only filtered bundle as an
    105 exact-tree archive. Record actual revisions and runtime inputs, and distinguish
    106 fresh checks from reused evidence. Production archives and release qualification
    107 remain deferred and unclaimed.
    108 
    109 ## Commit style
    110 
    111 ```text
    112 <scope>: <imperative summary>
    113 ```
    114 
    115 ## Public contracts
    116 
    117 Changes to FFI, product coordinates, storage migrations, or future Radroots
    118 event contracts require explicit compatibility review.
    119 
    120 Preserve native runtime behavior, persisted paths,
    121 installation/keyring identities, schema v3, storage API v3, FFI v4.5, snapshot
    122 v1, migrations, custody, and the exact Radroots source pin. HCAV-021 and later
    123 desktop availability work remain paused. The existing HCP/HCR checkpoints,
    124 product/design acceptance obligations, and eleven planned browser routes remain
    125 in force; repository guidance does not qualify the product or resume them.