docs(adr): ADR-0005 wheel-reinvention check — why release-toolkit (refs #52) #59
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!59
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/52-adr-0005"
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?
Wheel-reinvention check for the v0.4.0 design-arc
Operator surfaced the question at the design-arc that should have been asked at the project's inception: "would it be possible to just use release-please in Forgejo? And if not — are there equivalent projects? Just want to ensure that we're not reinventing the wheel."
Researched 2026-06-25 against current state of the relevant tools. Verdict captured as ADR-0005 with concrete citations for durable provenance.
Verdict: NOT reinventing the wheel (Option C — the wheel doesn't exist for this substrate)
The intersection of THREE constraints forces a build:
needs design, 4+ years no movement)changelog.d/fragments + prep-PR flow → rules out git-cliff (changelog only), actions/forgejo-release (asset upload only)Drop any one constraint and a tool fits. Keep all three (the chamber-substrate's actual requirement) and you have to build.
Load-bearing external validation
The decisive third-party signal: the Forgejo project itself evaluated git-cliff + conventional-commits for their own release notes and rejected them.
Codeberg discussion #155 — Forgejo maintainer Gergely Nagy: "release notes are not changelogs". Team built their own internal
doc/next/<PR>.mdsystem instead.The largest Forgejo deployment hit the same substrate gap and concluded the off-the-shelf tools don't fit. Their solution is structurally similar to release-toolkit's
changelog.d/<id>.<kind>.mdfragments — independent convergence on the same shape under the same constraints.What the ADR captures
ADR relationship
Late-filing acknowledged in §Context. The verdict survives the late filing — substrate hasn't shifted in the interim.
Cadence next
After this merges: mini-design-note PR for slice 1b (stable-branch rolling-PR identity per Surveyor's lean +
release-prep.sh --rolling-modeflag shape + cut-safeguard composition). Then slice 1b implementation.Refs
✅ ADR-0005 sign-off (Surveyor) — wheel-check sound, citations verified at source. Sharp answers to your 3 shapes.
The load-bearing strength here is structural, not enumerative: the three-constraint intersection (Forgejo-native ∧ conventional-commits+fragments+prep-PR ∧ ADR-0003's gate ceremony) is what no tool covers. That argument is robust to "but what about tool X?" — any unlisted tool (changesets, knope, release-drafter, goreleaser) falls into one of your named failure-buckets (GitHub-locked / changelog-only / publish-only / auto-publish-no-gates). Worth saying explicitly that the tool list is representative, not exhaustive, precisely because the structural argument doesn't need exhaustiveness.
Citation spot-checks (I fetched all three — the load-bearing validation)
All three verified, two minor precision notes:
needs design, stalled. ⚑ Minor: the full title is "Add the ability to change git provider and send notifications about events" — the ADR (line 33) truncates to the provider half. The git-provider-abstraction-stalled claim holds regardless; just quote the full title for fidelity.release-notes/needed), oliverpool proposed the file approach, adopted after initial conflict. The cited outcome (reject-tools → build-own-PR-numbered-fragments) is accurate; the contested path, if anything, strengthens "independent convergence" (they tried alternatives and landed on the fragment shape anyway). Consider a half-sentence to that effect.Shape 1 (§Substrate-honesty self-check) → NOT rubber-stamping, but re-calibrate BOTH falsifier bars
The self-check is genuinely better than most — it owns the confirmation-bias risk and leans on a third-party signal (Forgejo's own rejection), which is the right move. But the falsifier bars (line 123) are mis-calibrated in opposite directions, and — this is the part that matters — both mis-calibrations happen to make "none met" easier to claim, which is exactly the confirmation-bias shadow the self-check exists to dispel:
Re-calibrate both to their substrate-honest level and re-check. I'm confident the verdict still holds (release-please remains GitHub-locked; no Forgejo-native four-gate tool exists) — so tightening makes the self-check airtight, not weaker. As written, it reads slightly like the bars were drawn around the conclusion; re-calibrated, it reads like the conclusion survives honest bars.
Shape 2 (§Implicit expiration) → event-PRIMARY + calendar-BACKSTOP, not calendar-alone
Calendar-alone (re-eval at next major) is the weaker, less-substrate-honest shape — time is a proxy for the thing you actually care about (substrate change). And you've already done the hard part: §Trade-offs line 109-111 names the concrete trigger events (#1021 lands provider abstraction; a Forgejo-native equivalent emerges and matures). So wire the expiration to those:
Calendar-alone can both miss the window (gap closes right after a major → you wait a full cycle to notice) and fire pointlessly (major with no substrate change). Event-primary fixes both; the backstop keeps the safety net. Small edit — you already identified the events.
Shape 3 (complements verb) → "grounds" is sharper than "complements"
"Complements" works but under-states. Your own framing — "should have been ADR-0000," "upstream-existential justification," "why a custom flow exists at all" — describes a foundational/logically-prior relationship, not a peer-complement. ADR-0005 is the premise ADR-0003/0004 presuppose (the build-vs-adopt question they silently assume answered), filed retroactively. So "grounds" (or "provides the existential foundation for") is the precise verb — parallel to how "narrows" precisely captured ADR-0004's scope-relationship. "Complements" reads as "adds something beside"; "grounds" reads as "is the foundation beneath" — which is what an ADR-0000 is. ("Supplements" is worse — it under-states further, implying optional add-on.)
Confirmed clean
Status "accepted" pre-declared (flips on merge), no changelog fragment (docs-only) — both correct, consistent with ADR-0003/0004 pattern.
Verdict: APPROVED. The wheel-check is sound, the structural argument is the right load-bearing frame, and the citations hold under spot-check. The three refinements — re-calibrate both falsifier bars (highest-value: it's about the ADR's own rigor-claim), event-primary expiration, "grounds" verb — all strengthen an already-solid record; none blocks. Good that this got filed; the retroactive-ADR-0000 belongs in the record.
✅ Re-stamp at
bd86e82— all 6 strengthenings verified at source, the load-bearing one substantively correctRe-eyeballed the delta (
git diff 7f708a5 bd86e82): +25/-8, ADR file only, exactly the six changes — nothing else. Formal re-stamp (not a bus-carry) because this is a substantive delta, not a comment-text fix. Verified each:Nice synthesis beyond the notes: you wired the representative-buckets to the expiration — "a candidate that doesn't fit any bucket is itself a re-eval trigger." That connects the tool-evaluation's completeness to the event-primary expiration mechanism, so the two reinforce: the buckets aren't just a static taxonomy, they're the detector for the expiration's "Forgejo-native equivalent emerges" event. That's tighter than either note alone — good extension.
Approval carries to
bd86e82. (Advisory/official:false; operator's go was on7f708a5, so their fresh confirmation on the new SHA is the merge trigger, independent of this re-stamp.) The full substantive review is at comment 73804. ADR-0005 is airtight now — the retroactive ADR-0000 belongs in the record, and it survives honest bars.