From ec8cfc7ebd84efcb732e2927399bc84bf7461445 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 14 May 2026 15:06:37 +0100 Subject: [PATCH] docs: add CONTRIBUTING-DEV.adoc Closes #63. `.github/CONTRIBUTING.md` covers RSR conventions (commit signing, contractiles, repo structure) but not "how do I add code to *this* codebase?" Add a developer-facing guide with three concrete walkthroughs: - adding a new database backend (enum variant + dialect + tests) - adding a new drift category (ADR + measure fn + report wiring) - adding a new Tier 2 overlay (Tier2Config field + DDL + interceptor) Each walkthrough is an interactive checklist so PR authors can paste it into a PR body and tick items as they go. The checklists reference real file paths from the current tree, not aspirational ones. The clone/build/test section also documents the Windows integration-test gotcha (TOML path escape) so contributors don't chase it. Co-Authored-By: Claude Opus 4.7 --- CONTRIBUTING-DEV.adoc | 114 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 CONTRIBUTING-DEV.adoc diff --git a/CONTRIBUTING-DEV.adoc b/CONTRIBUTING-DEV.adoc new file mode 100644 index 0000000..de22f05 --- /dev/null +++ b/CONTRIBUTING-DEV.adoc @@ -0,0 +1,114 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += Contributing — Developer Guide +Jonathan D.A. Jewell +:toc: left +:toclevels: 3 +:icons: font +:source-highlighter: rouge + +This guide is for contributors making *code changes* to verisimiser. For +repository-wide RSR conventions (commit signing, file layout, contractiles) +see `.github/CONTRIBUTING.md`. + +Three common contribution shapes get a checklist each: + +* Adding a new database backend +* Adding a new drift category +* Adding a new Tier 2 overlay + +== Clone, build, test + +[source,bash] +---- +git clone git@github.com:hyperpolymath/verisimiser.git +cd verisimiser +cargo build +cargo test --lib --bins +cargo clippy --all-targets -- -D warnings +---- + +The full `cargo test` runs integration tests under `tests/`. On Windows those +hit a TOML path-escape issue and fail spuriously; CI is the source of truth. + +The `Justfile` lists shorthand recipes for the common loops (`just test`, +`just quality`, etc.). New Justfile recipes are only added once their +underlying command works — see `docs/decisions/0002-no-aspirational-justfile-recipes.adoc`. + +== Adding a database backend + +Adding a backend (say, MySQL) means making the entire codegen + interception +pipeline aware of it. Checklist: + +[%interactive] +* [ ] Add a variant to `enum DatabaseBackend` in `src/abi/mod.rs`. +* [ ] Update `DatabaseBackend::from_str` to recognise the new name plus + common aliases. +* [ ] Update `DatabaseBackend::as_str` (and any `Display` impl) for the + new variant. +* [ ] Decide the *interception strategy* (binlog CDC, change streams, + WAL monitoring, application middleware …) and document it on the + enum variant doc comment. +* [ ] Add the dialect to `src/codegen/query.rs::build_entity_id_expr` + so the no-PK fallback row identifier is correct (e.g. SQLite uses + `rowid`, Postgres uses `ctid`). +* [ ] Add a dialect branch to any other backend-aware site in + `src/codegen/` — search for `DatabaseBackend::` usages. +* [ ] If the backend needs a separate sidecar dialect, extend + `src/codegen/overlay.rs` to emit the right `CREATE TABLE` syntax. +* [ ] Add a unit test in `src/codegen/query.rs::tests` covering the new + variant for at least one interceptor type. +* [ ] Update `Cargo.toml` only if the backend needs a new connector + crate (e.g. `mysql_async`). Prefer interception via the database's + replication interface; pull in connector crates only as a fallback. +* [ ] If the backend belongs in the published interception list, add it + to `README.adoc` under *Interception methods*. Otherwise leave it + in `ROADMAP.adoc`. + +== Adding a drift category + +The drift system is V-L1-E (see #48 for the eight-category ADR). Each +category is an isolated detector with input type, distance function, and +threshold. + +[%interactive] +* [ ] Open an ADR in `docs/decisions/` documenting the category's input + type, distance function, and default threshold. +* [ ] Add a variant to `DriftCategory` in `src/tier1/drift.rs`. +* [ ] Implement a `measure(prior, current) -> f64` function returning a + distance in `[0.0, 1.0]`. +* [ ] Wire the measurement into the `DriftReport` aggregator. +* [ ] Add unit tests for: identical inputs → 0.0; maximally different + inputs → 1.0; threshold-edge cases. +* [ ] Update `docs/architecture/THREAT-MODEL.adoc` if the category has + adversarial implications. + +== Adding a Tier 2 overlay + +Tier 2 overlays require additional storage alongside the target database +(graph, vector, tensor, semantic, …). New overlays are not the same as +new backends. + +[%interactive] +* [ ] Add a boolean field to `Tier2Config` in `src/manifest/mod.rs` (and + its `Default` impl) for the manifest toggle. +* [ ] Decide the sidecar storage technology (pure Rust, HNSW, ndarray, …) + and document it on the `Tier2Config` field doc comment. +* [ ] Add overlay DDL emission in `src/codegen/overlay.rs` behind the new + flag. +* [ ] Add an interceptor in `src/codegen/query.rs` that routes the right + queries to the overlay. +* [ ] Add a round-trip test in `src/codegen/overlay.rs::tests` covering + the flag both on and off. +* [ ] Update `README.adoc`'s *Octad: Eight Modalities* table to reflect + the new overlay's tier and storage. + +== Style notes + +* Treat `cargo clippy --all-targets -- -D warnings` as part of `cargo + build`. The crate has no blanket `#![allow(...)]` blocks + (`docs/decisions/0001` and 0002 keep the surface clean). +* Public items used as the library API should be `pub`; binary-only + helpers stay private. +* All commits are SSH-signed (see `.github/CONTRIBUTING.md`). +* PRs target `main`. Auto-merge with `--squash` is the norm.