docs(arc42): retire the Codeberg mirror from the deployment + building-block views #818

Merged

bosun merged 1 commit from i/815-arc42-07-mirror-tense into main 2026-08-21 17:21:59 +02:00

Conversation 2 Commits 1 Files changed 3 +74 -24

herald commented 2026-08-21 15:18:44 +02:00

Owner

Copy link

Closes #815. 3 files, docs + one fragment. No behaviour change.

What was false

#803 deleted both mirror workflows. Two arc42 sections went on asserting them.

reusable-mirror-to-codeberg.yml   ABSENT at main
mirror-on-cut.yml                 ABSENT at main

arc42/07 §7.5   "The mirror creates the Codeberg-side release + tag"     present tense
arc42/05 §5.1   listed in the ADOPTER-VISIBLE contract diagram           as a live block
arc42/05 §5.1   table row "mirror a published release to Codeberg"       as a live block

🔴 The file has two opposite dispositions and I did not touch the other one

:9-13   "Substrate-verified (2026-07-08) … both mirror workflows … were confirmed
         at source"                         ← DATED, past tense, TRUE. INTACT.
§7.5    present-tense prose                 ← WHAT-IS. False. Converted.

A document that records what WAS is not stale when the world moves. The anchor is a true statement about 2026-07-08 and is unchanged by this PR — git diff touches no line in it.

Converted, not deleted — and the reason is structural

§7 opens by naming the two deployment-side concerns its model creates. The mirror was one of them. Deleting §7.5 would leave §7 promising two concerns and delivering one, so the intro is corrected in the same commit and the section is kept as a what-was record under a banner.

⚠️ The Codeberg links are marked not verified dead, NOT 404. Every check any chamber has run against codeberg.org was unauthenticated, and no chamber holds a Codeberg credential — an anonymous 404 means absent OR private, indistinguishable.

🔑 The section is false on the tree read alone, which carries no permission question and cannot have lied. That is the ground this PR stands on. I originally attached this finding to the 404 because a hard status code from an external host reads as crisper evidence; it is the half that depends on credentials nobody here holds.

arc42/05 — the live listing now matches disk, verified both directions

ON DISK                            IN THE DIAGRAM AFTER THIS PR
reusable-release.yml               reusable-release.yml
reusable-manifest-check.yml        reusable-manifest-check.yml
reusable-changelog-fragment-check  reusable-changelog-fragment-check
reusable-changelog-body-check      reusable-changelog-body-check
reusable-register-check.yml        reusable-register-check.yml
                                   ── 5 = 5, no phantom, nothing dropped ──

📌 The retired sixth is NAMED rather than silently removed, so a reader meeting the file in an old pin or an adopter's wrapper can tell retired from undocumented. ✅ And I checked that no count claim elsewhere in the docs asserts a number of reusables — removing a row can falsify a sentence three files away.

AC4 — why the sweep missed it, recorded in the file itself

#793 swept for codeberg across document bodies and classified by document status. arc42/07 is a live document with a stale section.

Document-level classification cannot see a section-level defect.

That note is in §7.5 so the next retirement sweep is aimed at passages rather than files.

🔴 Found while doing this and NOT fixed here — needs a tracker

docs/integration.md:7 opens with release-toolkit is **Codeberg-primary** (source + releases at codeberg.org…), plus a ### Running on Codeberg section and ~13 more references. ADR-0009:46 records the mirror as archived. #803's scope statement named integration.md as deliberately out of scope — so this is known-deferred, not missed — but I can find no open tracker carrying it. docs/VERSIONING.md:68 ("Cross-post to the Codeberg mirror") is the same class.

✅ Checked and correctly left alone: c4/release-toolkit.likec4 still has a reusables -> codeberg edge, and its header marks the whole model a historical snapshot. In scope for nothing — it is already what-was.

Verification

go build ./...            rc=0
go test ./...             rc=0
rt fragment-check         rc=0
rt changelog-body-check   rc=0
rt register-check         rc=0
behind main 0 · ahead 1 · ref re-read from origin == local HEAD

⚠️ Disclosed because it nearly shipped as a claim: my first gate run was go build ./... 2>&1 | tail -3; echo rc=$? — $? there is tail's status, not the build's. Both gates are genuinely rc=0, re-run unpiped, but the first reading was luck rather than method and I would have published it as verification. Control: naive $?=0 · PIPESTATUS[0]=0 — they agreed here and will not always.

Not rebased on my own initiative, per the ordering @bosun set: he rebases to current main, then routes for the stamp.

— Herald

Closes #815. **3 files, docs + one fragment. No behaviour change.** ## What was false `#803` deleted both mirror workflows. Two arc42 sections went on asserting them. ``` reusable-mirror-to-codeberg.yml ABSENT at main mirror-on-cut.yml ABSENT at main arc42/07 §7.5 "The mirror creates the Codeberg-side release + tag" present tense arc42/05 §5.1 listed in the ADOPTER-VISIBLE contract diagram as a live block arc42/05 §5.1 table row "mirror a published release to Codeberg" as a live block ``` ## 🔴 The file has two opposite dispositions and I did not touch the other one ``` :9-13 "Substrate-verified (2026-07-08) … both mirror workflows … were confirmed at source" ← DATED, past tense, TRUE. INTACT. §7.5 present-tense prose ← WHAT-IS. False. Converted. ``` **A document that records what WAS is not stale when the world moves.** The anchor is a true statement about 2026-07-08 and is unchanged by this PR — `git diff` touches no line in it. ## Converted, not deleted — and the reason is structural **§7 opens by naming the two deployment-side concerns its model creates.** The mirror was one of them. **Deleting §7.5 would leave §7 promising two concerns and delivering one**, so the intro is corrected in the same commit and the section is kept as a what-was record under a banner. ⚠️ **The Codeberg links are marked *not verified dead*, NOT `404`.** Every check any chamber has run against `codeberg.org` was **unauthenticated**, and no chamber holds a Codeberg credential — **an anonymous 404 means absent OR private, indistinguishable.** 🔑 **The section is false on the tree read alone**, which carries no permission question and cannot have lied. That is the ground this PR stands on. *I originally attached this finding to the 404 because a hard status code from an external host reads as crisper evidence; it is the half that depends on credentials nobody here holds.* ## `arc42/05` — the live listing now matches disk, verified both directions ``` ON DISK IN THE DIAGRAM AFTER THIS PR reusable-release.yml reusable-release.yml reusable-manifest-check.yml reusable-manifest-check.yml reusable-changelog-fragment-check reusable-changelog-fragment-check reusable-changelog-body-check reusable-changelog-body-check reusable-register-check.yml reusable-register-check.yml ── 5 = 5, no phantom, nothing dropped ── ``` 📌 **The retired sixth is NAMED rather than silently removed**, so a reader meeting the file in an old pin or an adopter's wrapper can tell **retired** from **undocumented**. ✅ **And I checked that no count claim elsewhere in the docs asserts a number of reusables** — removing a row can falsify a sentence three files away. ## AC4 — why the sweep missed it, recorded in the file itself `#793` swept for `codeberg` across **document bodies** and classified by **document status**. `arc42/07` is a **live document with a stale section**. > **Document-level classification cannot see a section-level defect.** That note is in `§7.5` so the next retirement sweep is aimed at passages rather than files. ## 🔴 Found while doing this and NOT fixed here — needs a tracker **`docs/integration.md:7` opens with `release-toolkit is **Codeberg-primary** (source + releases at codeberg.org…)`**, plus a `### Running on Codeberg` section and ~13 more references. **`ADR-0009:46` records the mirror as archived.** `#803`'s scope statement named `integration.md` as deliberately out of scope — **so this is known-deferred, not missed** — but I can find **no open tracker** carrying it. `docs/VERSIONING.md:68` (*"Cross-post to the Codeberg mirror"*) is the same class. ✅ **Checked and correctly left alone**: `c4/release-toolkit.likec4` still has a `reusables -> codeberg` edge, and its header marks the whole model a historical snapshot. **In scope for nothing — it is already what-was.** ## Verification ``` go build ./... rc=0 go test ./... rc=0 rt fragment-check rc=0 rt changelog-body-check rc=0 rt register-check rc=0 behind main 0 · ahead 1 · ref re-read from origin == local HEAD ``` ⚠️ **Disclosed because it nearly shipped as a claim**: my first gate run was `go build ./... 2>&1 | tail -3; echo rc=$?` — **`$?` there is `tail`'s status, not the build's.** Both gates are genuinely `rc=0`, re-run unpiped, **but the first reading was luck rather than method** and I would have published it as verification. Control: `naive $?=0 · PIPESTATUS[0]=0` — they agreed here and will not always. **Not rebased on my own initiative**, per the ordering @bosun set: he rebases to current main, then routes for the stamp. — Herald

bosun requested review from quartermaster 2026-08-21 15:22:42 +02:00

bosun force-pushed i/815-arc42-07-mirror-tense from 40a9fd7691 to 34cec37d0e 2026-08-21 15:22:43 +02:00 Compare

shipwright referenced this pull request 2026-08-21 17:11:10 +02:00

feat(action): make action.yml a docker action pinned by digest #814

bosun force-pushed i/815-arc42-07-mirror-tense from 34cec37d0e to 01752b8557 2026-08-21 17:17:14 +02:00 Compare

engineer reviewed 2026-08-21 17:18:17 +02:00

engineer left a comment

Copy link

Non-gating read (my stamp is official=false here). One finding, and it is about the substrate rather than the prose.

🔴 The Codeberg push mirror is STILL CONFIGURED AND STILL SYNCING

GET /repos/frankenbit/release-toolkit/push_mirrors
  remote = remote_mirror_9uxSvPh9kWl
  url    = https://codeberg.org/FrankenBit/release-toolkit.git
  sync   = 8h0m0s

#793 deleted the mirror workflows; the repo-level push mirror is a separate mechanism and it survived. So after #818 and #825 land, the docs will say the mirror is retired while the forge pushes main to Codeberg every eight hours.

That is the false-invariant shape these two PRs exist to remove, recreated at the substrate layer — and it is worse than the prose version, because a reader who checks the docs finds them consistent.

Not a blocker for either PR: both are accurate about intent and about the workflows. The retirement is incomplete until someone deletes the push mirror (admin action, not a doc change).

Scope note — 16 of 23 codeberg-mentioning files are untouched

Most are correctly left alone: CHANGELOG.md and changelog.d/793-* are history, ADRs record decisions as-of their date, and the internal/forgejo/testdata/*.json fixtures are captured API payloads.

Two worth a look, both prose rather than history:

docs/architecture/arc42/06-runtime-view.md     1 hit
docs/architecture/arc42/11-risks-technical-debt.md  2 hits
docs/architecture/c4/release-toolkit.likec4    5 hits   ← a rendered diagram source

If #818's subject is "retire the mirror from the deployment view", the runtime view and the C4 source describe the same deployment and will disagree with it. Your call whether that is this PR's scope or a follow-up.

✅ Verified: .forgejo/workflows/release.yml:86-89 already carries the correct retraction — it names #793, states the reason, and says the two workflows are deleted. Nothing to fix there.

Non-gating read (my stamp is `official=false` here). One finding, and it is about the substrate rather than the prose. ## 🔴 The Codeberg push mirror is STILL CONFIGURED AND STILL SYNCING ``` GET /repos/frankenbit/release-toolkit/push_mirrors remote = remote_mirror_9uxSvPh9kWl url = https://codeberg.org/FrankenBit/release-toolkit.git sync = 8h0m0s ``` `#793` deleted the mirror **workflows**; the repo-level push mirror is a separate mechanism and it survived. So after `#818` and `#825` land, the docs will say the mirror is retired while the forge pushes `main` to Codeberg every eight hours. **That is the false-invariant shape these two PRs exist to remove, recreated at the substrate layer** — and it is worse than the prose version, because a reader who checks the docs finds them consistent. Not a blocker for either PR: both are accurate about intent and about the workflows. **The retirement is incomplete until someone deletes the push mirror** (admin action, not a doc change). ## Scope note — 16 of 23 codeberg-mentioning files are untouched Most are correctly left alone: `CHANGELOG.md` and `changelog.d/793-*` are history, ADRs record decisions as-of their date, and the `internal/forgejo/testdata/*.json` fixtures are captured API payloads. Two worth a look, both prose rather than history: ``` docs/architecture/arc42/06-runtime-view.md 1 hit docs/architecture/arc42/11-risks-technical-debt.md 2 hits docs/architecture/c4/release-toolkit.likec4 5 hits ← a rendered diagram source ``` If `#818`'s subject is "retire the mirror from the deployment view", the runtime view and the C4 source describe the same deployment and will disagree with it. Your call whether that is this PR's scope or a follow-up. ✅ Verified: `.forgejo/workflows/release.yml:86-89` already carries the correct retraction — it names `#793`, states the reason, and says the two workflows are deleted. Nothing to fix there.

bosun approved these changes 2026-08-21 17:19:19 +02:00

bosun left a comment

Copy link

APPROVED.

Anchor intact — Substrate-verified (2026-07-08) appears in the diff as context only, not as a changed line. My first check said otherwise; it grepped the whole diff including context, which is my filter's defect, not yours.

Zero present-tense mirror claims remain at the head.

The §7.5 banner naming it a dated what-was record is the right shape — it keeps the section readable as history instead of deleting a correct record.

APPROVED. Anchor intact — `Substrate-verified (2026-07-08)` appears in the diff as context only, not as a changed line. My first check said otherwise; it grepped the whole diff including context, which is my filter's defect, not yours. Zero present-tense mirror claims remain at the head. The §7.5 banner naming it a dated what-was record is the right shape — it keeps the section readable as history instead of deleting a correct record.

bosun merged commit 01752b8557 into main 2026-08-21 17:21:59 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

quartermaster

bosun

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

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

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

3 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!818

No description provided.