From 1cf001180847a77d882f975e6727428eecfda1bd Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 26 May 2026 18:32:43 +0100 Subject: [PATCH] docs: adopt docs-template/ skeleton (architecture/usage/contributing/troubleshooting + ADR) Closes Row-2 Phase 2 of the 2026-05-26 estate tech-debt audit chain for this repo. The 2026-05-26 documentation-debt audit (hyperpolymath/standards#197) flagged this repo as MEDIUM doc-debt: substantial top-level README but no docs/ tree. This PR seeds docs/ with the canonical 4-section + ADR skeleton from hyperpolymath/rsr-template-repo#75: - docs/architecture.adoc (system overview, components, invariants) - docs/usage.adoc (consumer perspective) - docs/contributing.adoc (developer perspective) - docs/troubleshooting.adoc (FAQ-style) - docs/decisions/0001-template.adoc (ADR template) Placeholders ({{PROJECT_NAME}}, etc.) have been substituted to this repo's actual values. The skeleton structure is canonical; the substantive content is owed to the maintainer. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/architecture.adoc | 78 +++++++++++++++++++++++++++ docs/contributing.adoc | 90 +++++++++++++++++++++++++++++++ docs/decisions/0001-template.adoc | 53 ++++++++++++++++++ docs/troubleshooting.adoc | 57 ++++++++++++++++++++ docs/usage.adoc | 81 ++++++++++++++++++++++++++++ 5 files changed, 359 insertions(+) create mode 100644 docs/architecture.adoc create mode 100644 docs/contributing.adoc create mode 100644 docs/decisions/0001-template.adoc create mode 100644 docs/troubleshooting.adoc create mode 100644 docs/usage.adoc diff --git a/docs/architecture.adoc b/docs/architecture.adoc new file mode 100644 index 0000000..8e3d8ac --- /dev/null +++ b/docs/architecture.adoc @@ -0,0 +1,78 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> += Architecture — a2ml_ex +:revdate: 2026-MM-DD + +== System overview + +One paragraph: what this project does and what it does not do. State the +*invariant* — the property that, if violated, would make the whole project +pointless. Future maintainers will read this paragraph first. + +== Component diagram + +Replace this section with an ASCII or Mermaid diagram. Keep it under 20 +lines — anything bigger belongs in `architecture/`. + +[source] +---- ++------------------+ +------------------+ +| Component A | ---> | Component B | ++------------------+ +------------------+ + | + v ++------------------+ +| Component C | ++------------------+ +---- + +== Data flow + +For each external input, describe: + +* **Source**: where it comes from. +* **Validation**: what guarantees we enforce on entry. +* **Transformation**: high-level processing stages. +* **Sink**: where the result goes. + +== Key invariants + +Enumerate the load-bearing invariants of the system. Each should have: + +. A one-line statement. +. The code location(s) that enforce it. +. The failure mode if the invariant is violated. + +Example: + +[cols="1,2,2,2", options="header"] +|=== +| # | Invariant | Enforced at | Failure mode + +| 1 +| All HTTP requests carry a valid `X-Request-ID`. +| `src/middleware/request_id.rs` +| Logs become unjoinable; correlation breaks. + +| 2 +| The output buffer is always flushed before exit. +| `src/main.rs:88-92` (Drop impl) +| Last ~16KB of log lost on crash. +|=== + +== Dependencies + +* **Internal**: list other hyperpolymath repos this depends on. +* **External**: SHA-pinned (see `Cargo.lock` / `deno.lock` / etc.). +* **Build-time**: tools required to build (just, deno, cargo, …). + +== Out of scope + +Explicit non-goals. Things we deliberately do *not* do, with a one-line +reason for each. This section saves more time than the rest combined. + +== See also + +* link:./usage.adoc[Usage] — consumer perspective. +* link:./contributing.adoc[Contributing] — developer setup. +* link:./decisions/[ADRs] — historical record of why this shape. diff --git a/docs/contributing.adoc b/docs/contributing.adoc new file mode 100644 index 0000000..e9b15ee --- /dev/null +++ b/docs/contributing.adoc @@ -0,0 +1,90 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> += Contributing — a2ml_ex +:revdate: 2026-MM-DD + +== Audience + +Developers working *on* `a2ml_ex`. For consumers (people calling +or depending on it) see link:./usage.adoc[usage.adoc]. + +== Local-dev setup + +Prerequisites — the minimum versions and where to get them: + +* `` v`` — ``. +* `` v`` — ``. +* GPG signing key configured (estate policy — all commits must be + signed). See + link:https://github.com/hyperpolymath/standards/blob/main/docs/secure-coding-training.md[standards/docs/secure-coding-training.md]. + +One-shot setup: + +[source,bash] +---- +git clone git@github.com:hyperpolymath/a2ml_ex.git +cd a2ml_ex +just setup # installs deps, sets up hooks +just test # runs the full test suite +---- + +== Running tests + +* **Unit**: `just test-unit` — fast, no I/O. +* **Integration**: `just test-int` — uses real services (database, + HTTP, etc.). Estate policy: prefer real over mocked + (see `feedback_integration_tests_real_db` in maintainer's memory). +* **Property**: `just test-prop` — randomised, slower; budget + documented in `docs/proof-debt.md` if applicable. +* **Full**: `just test` — runs all of the above. + +== Code style + +We enforce style via CI (governance-reusable.yml from hyperpolymath/standards). +Locally: + +[source,bash] +---- +just fmt # auto-format +just lint # static checks +---- + +* All commits must be **GPG-signed** (CI enforces; see + link:https://github.com/hyperpolymath/standards[standards]). +* All source files must carry an **SPDX-License-Identifier** header + (CI enforces). +* Conventional commits — `feat`, `fix`, `chore`, `refactor`, `docs`, + `test`, `ci`, `revert` (CHANGELOG is auto-generated from these + via link:https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`changelog-reusable.yml`]). + +== Branching & PR workflow + +. Branch off `main` as `claude/` (for AI agents) or + `/` (for humans). +. Make focused, narrow commits — one logical change per commit. +. Open a PR against `main`. +. **Enable auto-merge immediately** on every PR you open + (`gh pr merge --auto --squash`) — estate standing policy + (see standards#196 audit and policies). +. CI must be green. The PR auto-merges when checks pass + reviews land. + +== Adding a new dependency + +. State the *why* in the PR body — what does this dependency unlock? +. Check provenance (maintained, audited, no malicious history). +. Pin to a SHA, not a tag. +. Update `docs/architecture.adoc#Dependencies`. + +== Adding an ADR + +When you make a non-obvious design decision, write it down: + +. Copy `docs/decisions/0001-template.adoc` → `0002-.adoc`. +. Fill in: Context, Decision, Consequences, Alternatives. +. Link the ADR from the README or relevant code as a comment. + +== Reporting issues + +* Bugs in `a2ml_ex`: file at `hyperpolymath/a2ml_ex/issues`. +* Estate-wide concerns (policy, conventions, CI): file at + `hyperpolymath/standards/issues`. diff --git a/docs/decisions/0001-template.adoc b/docs/decisions/0001-template.adoc new file mode 100644 index 0000000..1f128dd --- /dev/null +++ b/docs/decisions/0001-template.adoc @@ -0,0 +1,53 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> += ADR-0001 — Use Architecture Decision Records +:revdate: 2026-MM-DD +:status: ACCEPTED + +== Context + +We need a lightweight way to record significant architectural decisions +and the reasoning behind them, so future maintainers (and AI agents) +can understand *why* the project is shaped as it is. + +== Decision + +Adopt link:https://adr.github.io/[Architecture Decision Records (ADRs)] +in `docs/decisions/`, numbered sequentially (0001, 0002, ...). + +* Each ADR is a single `.adoc` file. +* The first ADR (this one) records the decision to use ADRs. +* Status values: PROPOSED, ACCEPTED, DEPRECATED, SUPERSEDED. +* When a decision is overturned, the new ADR records the supersession + and updates the old one's status to `SUPERSEDED by 00NN`. + +== Consequences + +. **Positive**: future readers see *why* without git-archaeology. +. **Positive**: design alternatives are documented, not just the + winning choice. +. **Positive**: ADRs are reviewable in PRs — the design discussion + happens alongside the code that implements it. +. **Negative**: maintenance burden — every non-obvious decision now + warrants an ADR. (We mitigate by keeping ADRs short; "non-obvious" + is a judgment call.) +. **Negative**: ADRs can rot. We accept this; the SUPERSEDED chain + is the recovery mechanism. + +== Alternatives considered + +. **Comments in code** — too local; doesn't capture cross-cutting + decisions. +. **Wiki / external doc** — drifts from code; not in PR review. +. **Commit messages** — too transient and not discoverable. +. **No record** — discarded; this is how every project ends up with + "I don't know why we do it this way" debt. + +== Companion ADRs + +* (None yet — this is the first ADR.) + +== References + +* MADR template — `https://adr.github.io/madr/` +* Estate convention — `hyperpolymath/standards/docs/RSR_OUTLINE.adoc` diff --git a/docs/troubleshooting.adoc b/docs/troubleshooting.adoc new file mode 100644 index 0000000..e1312ca --- /dev/null +++ b/docs/troubleshooting.adoc @@ -0,0 +1,57 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> += Troubleshooting — a2ml_ex +:revdate: 2026-MM-DD + +This file is a *living FAQ* — known failure modes and recovery paths. +Add a new entry every time you debug something that took more than 15 +minutes; future-you (and other maintainers) will thank you. + +== Known failure modes + +=== `` + +**Symptom**: short reproduction. What does the user see? + +**Cause**: root cause (one or two sentences). + +**Fix**: +[source,bash] +---- + +---- + +**Avoidance**: how to not hit this again (config setting, doc link, etc.). + +--- + +=== `` + +(Replace this and the above example with real entries as you encounter +them.) + +== Diagnostic toolkit + +When something is wrong, run these first: + +[source,bash] +---- +just doctor # runs all available self-checks +just version # prints the version & build hash +just log-tail # last N lines of logs +---- + +== When to escalate + +. Filed an issue with: version, OS, exact command, full error output, + and the symptom in plain English. +. Linked from the issue: the relevant ADR(s) and any related issues. +. For *security*-relevant findings, see + link:./../SECURITY.md[SECURITY.md] — do **not** file public issues. + +== Where to look for more help + +* `docs/architecture.adoc` — internals. +* `docs/decisions/` — historical record of why things are this shape. +* `https://github.com/hyperpolymath/a2ml_ex/issues?q=is%3Aissue+` — has anyone hit this before? +* `https://github.com/hyperpolymath/standards/issues` — for estate-wide problems. diff --git a/docs/usage.adoc b/docs/usage.adoc new file mode 100644 index 0000000..7d0b874 --- /dev/null +++ b/docs/usage.adoc @@ -0,0 +1,81 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> += Usage — a2ml_ex +:revdate: 2026-MM-DD + +== Audience + +This document is for *consumers* of `a2ml_ex` — people who depend +on it, call it, or include it. For developers working *on* it, see +link:./contributing.adoc[contributing.adoc]. + +== Quickstart + +The shortest path from zero to a working call: + +[source,bash] +---- +# 1. Install +just install # or: cargo install --path . / deno task install + +# 2. Configure +cp examples/config.example.toml ./config.toml +# Edit minimal required fields. + +# 3. Run +just run # or the equivalent for your language +---- + +Expected output: + +[source] +---- +a2ml_ex v0.0.0 +Listening on 127.0.0.1:8080 +---- + +== Common use cases + +For each canonical use case, give: + +. A one-line statement of the goal. +. The minimal invocation. +. Expected output / side effect. + +=== Use case 1: + +(Replace with real content.) + +=== Use case 2: + +== Configuration reference + +Document every configurable field. Keep this section authoritative — if +the code grows a new option, this table must grow too (CI can be wired +to enforce this). + +[cols="1,1,1,3", options="header"] +|=== +| Field | Type | Default | Meaning + +| `` | `` | `` | +|=== + +== Stability guarantees + +Be explicit: + +* **Stable**: API surfaces that follow SemVer (breaking change = major bump). +* **Unstable**: behind a flag / pre-1.0 / explicitly marked. +* **Internal**: documented for reference but no compatibility promise. + +== Limits & known constraints + +* Maximum supported ``: ``. +* `` is not yet implemented; track at issue `#`. +* On ``, `` behaves differently because ``. + +== See also + +* link:./architecture.adoc[Architecture] — how it works internally. +* link:./troubleshooting.adoc[Troubleshooting] — when things go wrong.