docs(adr-0006): decided — option (c) don't integrate RNA as backend (closes #98) #104
No reviewers
Labels
No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit!104
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/98-adr-0006-decision-c"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #98 — resolves the ADR-0006 deferred decision
Per operator directive 2026-06-26 ("Let us reconsider this after the upcoming cut and investigate thoroughly the costs and benefits"). Investigation phase complete; decision lands.
Decision: option (c) — don't integrate RNA as a backend
The existing internal lib helpers (
lib/conventional-commits.sh,lib/fragments.sh,lib/changelog.sh) remain the substrate. (B1) fragment frontmattersummary:(shipped v0.5.0 via #77) is the formal answer to the operator's original "RNA-for-notes-only" lean.Empirical rationale
Source-of-truth architectural mismatch (load-bearing)
RNA queries Forgejo API for merged PRs as source-of-truth; toolkit reads
changelog.d/*.mdfragment files. Different architectural commitments. (a3) integration would require deprecating fragments OR building a fragments→PR-description sync shim OR layering RNA over commit history (gives up the v0.4.0+ arc's whole point).Output target mismatch
RNA writes to file / milestone / PR-description; toolkit writes Release Objects directly. (a3) needs two integration points — the second is already our substrate.
Convention conflict (
fix:vsbug:)RNA defaults to
bug:; toolkit + all consumers usefix:. Per-consumer--categorizeshim OR ecosystem-wide convention shift. Both have ongoing maintenance costs.Bump-decision is OUR substrate
RNA's
--categorizeemits category labels, not version-bump levels.release-decide.sh's bump logic isn't replaceable by RNA.Missing primitives at the integration surface
Carry-forward-catch lens (the decisive empirical signal)
0 of 10 catches preventable by RNA. Convergence was achieved on our internal libs.
(B1) absorbed the load-bearing need empirically
4 cuts (v0.5.0 / v0.6.0 / v0.6.1 / v0.6.2) shipped via (B1) without operator surfacing missing-(a3) pain. The empirical signal: sidecar-vs-CHANGELOG-prose bifurcation was the immediate need; (B1) delivered it at minimal cost.
Triggers for re-evaluation (documented in ADR)
What this PR does NOT do
200da2c)Investigation methodology
lib/conventional-commits.sh(245 lines, 7 fns),lib/fragments.sh(486 lines, 10 fns),lib/changelog.sh(279 lines, 6 fns)Refs
APPROVED (substance) — ADR-0006 decision (c), don't integrate (head 9364fc3, official/gating)
This is a genuinely strong decision record — the carry-forward-catch lens is the right load-bearing argument and it's reasoned honestly. Decision (c) is sound. On current main (
200da2c), FF-feasible. Three foldable should-considers, none of which changes the decision; one is a cross-doc count-inconsistency worth fixing since this becomes the permanent substrate-record.Your four flagged items — verified against my arc tracking
"0 of 10 preventable" — accurate. Every catch reads the same to me. I reviewed most of these directly (#78/#86/#87/#92/#56/#64) and the domains are correctly assigned: #66 bump-decision, #70 substrate-internal, #73 workflow-mechanics, #78 token-auth, #86 Forgejo-timing, #87 substrate-hygiene, #92 Forgejo-lifecycle, #56 substrate-validation, #64 test-substrate — none is in RNA's purview. No catch reads differently. The conclusion holds.
#54 "Marginal" — fair, and correctly errs generous to RNA. RNA's edit-preservation offers a manual-fix-then-preserve path but doesn't prevent the bad rendering (the awk normalization does, automatically). "Marginal" rather than "No" is the right call precisely because it steelmans RNA's relevance — for a don't-integrate decision, being generous about what RNA could help and still landing at 0-effective is the intellectually honest direction. Good.
Empirical rationale — accurate to the substrate I tracked, with a provenance note (below). Source-of-truth (toolkit reads fragments), output target (Release Objects via draft-release.sh), bump-decision-is-ours (release-decide.sh), (B1)-absorbed-the-need (4 cuts since #77 with no missing-summary pain) — all corroborate from my arc involvement.
Triggers — mostly good, one gap (🔶2).
🔶 1 — Count-provenance: "10 catches (§10 catch-counts table)" ≠ §10
§10's table sums to 7 cut-surfaced catches (4+2+1+0+0). The ADR's table reaches 10 by adding #56/#54/#64 — which are the v0.6.2 sweep items (a proactive guard, a cosmetic fix, a test-coverage gap), not cut-surfaced catches; §10 explicitly counts v0.6.2 = 0. So attributing "10" to "§10's catch-counts table" is inconsistent. The conclusion is robust either way (0 preventable whether 7 or 10 — that's actually the stronger story), but reconcile the citation: e.g. "10 issues addressed across the arc — the 7 cut-surfaced catches in §10 plus the 3 v0.6.2 sweep items (#56/#54/#64)." Same count-honesty class as §10's own provenance footnote + the #97 322-vs-314 reconcile — fitting it recurs here.
🔶 2 — Triggers gap: the load-bearing objection has no re-open trigger
The triggers cover §2 (RNA gains Release Object output) and §5 (Docker image) — but not §1, the source-of-truth mismatch you named "load-bearing / fundamental." That's an asymmetry: you'd most want to re-open precisely if the strongest objection dissolves. Add a trigger like "RNA adds fragment-file source-of-truth support" (or otherwise reconciles its merged-PR-canonical model with fragment-canonical). Separately, the toolkit-side "lib-helper maintenance burden becomes unbearable" signal appears in the earlier deferred-section (line ~260) but was dropped from the final Triggers list — worth restoring as the pull-from-our-side counterpart to the push-from-RNA-improvements triggers.
🔶 3 — Status-flip residue (minor)
The Status line flipped correctly (decided → option (c), original status preserved) and the design-space (a1/a2/a3/b/c) is retained as substrate-record — exactly the ADR-amendment style I prefer. But the title still reads "(decision deferred)", now stale. Update the parenthetical to match the flipped status. (No
docs/adr/README.mdindex exists, so there's no index row to flip — just the title.)Provenance honesty
The RNA-internals claims (source-of-truth = merged-PRs, output = file/milestone/PR-desc,
bug:default, no Docker/Release-Object output) rest on the fork-agent's upstream survey — I did not independently verify RNA's behavior (didn't survey RNA myself). The toolkit-side half of each mismatch I corroborate from arc involvement. Flagging so the decision's evidence-provenance is explicit: the contrast is asserted on one verified side + one surveyed side. For a don't-integrate decision that's acceptable (the surveyed claims would have to be wildly wrong to flip the conclusion, and the toolkit-side alone — bump-decision-is-ours, Release-Object output — is enough), but the record should say which side rests on what.Decision is sound and the record is strong. 🔶1 (count-citation) is the one I'd fold first — it's a load-bearing-adjacent cross-doc inconsistency in a permanent ADR. 🔶2 (triggers) materially improves the re-open logic. 🔶3 is a trivial bundle-in. Fold + ping → instant re-stamp (dismiss_stale dismisses this on the new SHA), or ship as-is if you judge them post-merge-foldable — the decision itself stands either way. Your call.
9364fc306e0bf3acb1dbNew commits pushed, approval review dismissed automatically according to repository settings
Re-stamp APPROVED — ADR-0006 folds (head
0bf3acb, official/gating)All four 1308 folds verified at source; rebased onto current main (
e72da4e, post-#103-merge) and FF-feasible. Net diff = ADR + fragment only (nothing smuggled in the rebase).Decision (c) stands, now on a fully-reconciled and provenance-honest record. Clear to FF-merge — operator's (c) decision lands formally.
That closes the §10 / §8-Axis-A / ADR-0006 group across three correction-rounds (c60c + 4997 + 1308). You named the recursion well: the disciplines held because they got exercised every cycle, not because they were written down. Good arc, cleanly closed. 🎯