From 7d1d938dbb33d0717696fa60149a8bbe892dcea4 Mon Sep 17 00:00:00 2001 From: vpciii Date: Sun, 21 Jun 2026 12:16:19 -0400 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20record=20the=20=C2=A710=20onboardin?= =?UTF-8?q?g=20bullet=20in=20ADR=200023;=20trim=20changelog?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A PR #25 review (the same-model GitHub reviewer) correctly flagged that the v0.12.0 §10 onboarding bullet is a normative practice extension that shipped without an ADR — against the methodology's own "practice changes get an ADR" rule, and unlike comparable additions (ADR 0014, 0016). ADR 0003 (which defines §10's bullets) is append-only, so ADR 0023 records the new bullet and makes §10 traceable again. Also trims the 0.12.0 changelog entry's process-journal backstory (the #22/#24 narrative), keeping the substance + adoption line and citing ADR 0023. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 13 ++- ...23-one-command-onboarding-in-section-10.md | 80 +++++++++++++++++++ 2 files changed, 86 insertions(+), 7 deletions(-) create mode 100644 adr/0023-one-command-onboarding-in-section-10.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f9e6044..91085e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,14 +16,13 @@ See [ADR 0009](./adr/0009-methodology-as-versioned-dependency.md). ### Added - **One-command onboarding** — §10 gains a bullet: a substantial project - bootstraps from clone to a working environment with one documented, + bootstraps from a clone to a working environment with one documented, reproducible command; "works on my machine" is a defect in the - onboarding path. The developer entry point is the one thing §6/§10's - reproducible-build guidance left unsaid. Added as a sub-bullet, not a - new practice — the one idea from the (withdrawn) PR #22/#24 expansion - exchange that cleared the bar, captured at the right scale. *Adoption: - reference-only; optionally add a one-command setup where a substantial - project lacks one.* + onboarding path. The tool stays the project's choice (no mandate). The + developer entry point is the one thing §6/§10's reproducible-build + guidance left unsaid; recorded as a sub-bullet, not a new practice + (ADR 0023). *Adoption: reference-only; optionally add a one-command + setup where a substantial project lacks one.* ## [0.11.0] - 2026-06-20 diff --git a/adr/0023-one-command-onboarding-in-section-10.md b/adr/0023-one-command-onboarding-in-section-10.md new file mode 100644 index 0000000..c5197fc --- /dev/null +++ b/adr/0023-one-command-onboarding-in-section-10.md @@ -0,0 +1,80 @@ +# ADR 0023: One-command onboarding added to §10 + +- **Status:** Proposed +- **Date:** 2026-06-21 +- **Deciders:** vpc + +## Context + +§10 (Dependencies are decisions) was established by ADR 0003 as exactly +three bullets: adding-is-a-decision, lockfiles-committed, updates-deliberate. +Version 0.12.0 (PR #25) added a **fourth, normative** bullet — +"one-command onboarding; 'works on my machine' is a defect" — but shipped it +**without an ADR**, asserting scale-to-work. + +A PR review flagged the governance gap, and it is real. The methodology's own +rules require it: + +- *"If a practice changes, update the relevant document and record the change + in an ADR."* ("Changing this document") +- *"If you find yourself arguing for or against a practice that isn't listed + here, that is a sign you need an ADR, not a longer methodology doc."* + +PR #25's body was precisely an argument for a practice (it cited the withdrawn +#22/#24 exchange). And the precedent is consistent: comparably-scoped additions +in this repo got ADRs — ADR 0014 (a decision-guide row), ADR 0016 (a +postmortem home). Without this record, §10 carried a normative bullet no ADR +traced to — the doc/decision drift §1 exists to prevent. ADR 0003 is +append-only, so the new bullet is recorded **here**, not by editing it. + +## Decision + +Record the §10 **one-command onboarding** bullet as an accepted extension of +ADR 0003's Dependencies practice: + +> A substantial project bootstraps from a clone to a working environment with +> a single documented, reproducible command; "works on my machine" is a defect +> in the onboarding path. The tool (`make setup` / devcontainer / Nix flake) is +> the project's choice — **no tooling mandate**, consistent with ADR 0003's +> "weigh and record, not a particular tool." + +§10's decision trail is now **ADR 0003 + this ADR** together. The bullet is the +one survivor of the withdrawn #22/#24 expansion exchange, kept at sub-bullet +scale rather than as a new numbered practice. + +## Alternatives considered + +- **Leave the bullet unrecorded** (rely on scale-to-work alone) — rejected: a + normative §10 bullet with no ADR is the exact drift §1 prevents, and the + precedent (0014/0016) records comparable additions. +- **Revert the bullet** — rejected: the developer entry point is the one thing + §6/§10's reproducible-build guidance genuinely left unsaid, and the owner + chose to keep it. +- **Edit ADR 0003's Decision list to add the bullet** (the reviewer's + alternative) — rejected: ADRs are append-only; you supersede or record + anew, never edit. + +## Consequences + +- §10 is traceable to its decisions again. +- A small, deliberate precedent: a normative sub-bullet that extends a practice + gets a short ADR — honoring the "arguing for a practice → ADR" rule without a + whole new practice. +- Cheap to reverse: revert the bullet and supersede this ADR. + +## Adoption impact + +**Reference-only.** The bullet already shipped in 0.12.0; this ADR records the +decision behind it. Nothing for consuming projects to do. + +## References + +- ADR 0003 (`adr/0003-dependencies-are-decisions.md`) — the §10 practice this + extends; `methodology.md` §10, §1, "Changing this document." +- ADR 0014, ADR 0016 — precedent: comparably-scoped additions recorded by ADR. +- PR #25 (the bullet) and its review (the flagged governance gap). + +--- + +> Following the format proposed by Michael Nygard in +> [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). From 81256f367f40db0251fd80e40cb6b73165b3766b Mon Sep 17 00:00:00 2001 From: vpciii Date: Sun, 21 Jun 2026 12:20:42 -0400 Subject: [PATCH 2/2] docs: accept ADR 0023 (human sign-off) Co-Authored-By: Claude Opus 4.8 --- adr/0023-one-command-onboarding-in-section-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adr/0023-one-command-onboarding-in-section-10.md b/adr/0023-one-command-onboarding-in-section-10.md index c5197fc..e09522e 100644 --- a/adr/0023-one-command-onboarding-in-section-10.md +++ b/adr/0023-one-command-onboarding-in-section-10.md @@ -1,6 +1,6 @@ # ADR 0023: One-command onboarding added to §10 -- **Status:** Proposed +- **Status:** Accepted - **Date:** 2026-06-21 - **Deciders:** vpc