docs(positioning): declare release-toolkit Codeberg-primary — close round-4 positioning ambiguity #400

Merged

herald merged 2 commits from i/397-codeberg-primary-positioning into main 2026-07-04 23:51:34 +02:00

Conversation 2 Commits 2 Files changed 4 +34 -15

herald commented 2026-07-04 23:44:53 +02:00

Owner

Copy link

Closes #397.

Replaces the 4-axis "what's supported" matrix (README Positioning) that external cold-read round 4 flagged as ambiguous with a single definitive answer.

The reframe (ratified with Bosun)

The matrix conflated two orthogonal questions. The fix disentangles them:

Question	Answer
Where does the project live? (browse / clone / releases / trust)	Codeberg-primary — codeberg.org/frankenbit/release-toolkit
What CI runtime does it target?	Forgejo Actions — maintainers develop on a self-hosted Forgejo and mirror code + releases to Codeberg

The three hedged "can I run it on Forgejo/Gitea/Codeberg?" axes collapse into a secondary Runtime-compatibility list. Crucially, the Forgejo-Actions-native runtime fact is preserved, not replaced — there is no Codeberg CI runner (the old matrix said so itself), so a blanket "Codeberg-primary" swap over the runtime claim would have shipped a technical inaccuracy.

Empirical-contact scope notes

Reading the actual repo state before drafting caught three things the dispatch's literal framing would have gotten wrong:

• uses: frankenbit/release-toolkit/…@vX.Y.Z shorthand left untouched — it's a Forgejo-runner-resolved owner/repo ref, not a URL; can't be Codeberg-ized.
• AGENTS.md unchanged for #397 — its only git.frankenbit.de refs are issue-links (§10 catch table), and issues don't mirror to Codeberg (git-only mirror, per the issue's own substrate note). Codeberg-izing them would create dead links; issue-links correctly stay on the Forgejo substrate.
• No CONTRIBUTING.md exists — the "README → CONTRIBUTING → AGENTS.md" read-path has a missing middle; not perpetuating a link to a nonexistent file.

Files

• README.md — Positioning section rewritten; intro now links release-toolkit's own releases to Codeberg. Heading Positioning — what's supported? (#358) → Positioning (anchor change).
• docs/integration.md — Forgejo variant support section reframed to Positioning and runtime support; the sole inbound anchor ref updated to #positioning (heading-anchor discipline).
• changelog.d/397.changed.md — fragment.

Verification

• README residue-clean: no 4-axis matrix / old anchor / Codeberg-hosted / Mirror-releases-to-Codeberg remnants
• codeberg.org/frankenbit/release-toolkit resolves (HTTP 200); lowercase frankenbit kept for consistency with existing refs
• All 8 uses:@ref shorthands intact
• The one inbound anchor ref (integration.md → README#positioning) updated in the same change; no dangling links

Sibling to #398 (docs/internal → BookStack migration, comes next). Part of the operator-ratified Codeberg-primary shift, 2026-07-04.

Closes #397. Replaces the 4-axis "what's supported" matrix (README Positioning) that external cold-read round 4 flagged as ambiguous with a **single definitive answer**. ## The reframe (ratified with Bosun) The matrix conflated two orthogonal questions. The fix disentangles them: | Question | Answer | |----------|--------| | **Where does the project live?** (browse / clone / releases / trust) | **Codeberg-primary** — `codeberg.org/frankenbit/release-toolkit` | | **What CI runtime does it target?** | **Forgejo Actions** — maintainers develop on a self-hosted Forgejo and mirror code + releases to Codeberg | The three hedged "can I run it on Forgejo/Gitea/Codeberg?" axes collapse into a secondary **Runtime-compatibility** list. Crucially, the Forgejo-Actions-native runtime fact is **preserved, not replaced** — there is no Codeberg CI runner (the old matrix said so itself), so a blanket "Codeberg-primary" swap over the runtime claim would have shipped a technical inaccuracy. ## Empirical-contact scope notes Reading the actual repo state before drafting caught three things the dispatch's literal framing would have gotten wrong: - **`uses: frankenbit/release-toolkit/…@vX.Y.Z` shorthand left untouched** — it's a Forgejo-runner-resolved owner/repo ref, not a URL; can't be Codeberg-ized. - **AGENTS.md unchanged for #397** — its only `git.frankenbit.de` refs are **issue-links** (§10 catch table), and issues don't mirror to Codeberg (git-only mirror, per the issue's own substrate note). Codeberg-izing them would create dead links; issue-links correctly stay on the Forgejo substrate. - **No `CONTRIBUTING.md`** exists — the "README → CONTRIBUTING → AGENTS.md" read-path has a missing middle; not perpetuating a link to a nonexistent file. ## Files - `README.md` — Positioning section rewritten; intro now links release-toolkit's own releases to Codeberg. Heading `Positioning — what's supported? (#358)` → `Positioning` (anchor change). - `docs/integration.md` — `Forgejo variant support` section reframed to `Positioning and runtime support`; the sole inbound anchor ref updated to `#positioning` (heading-anchor discipline). - `changelog.d/397.changed.md` — fragment. ## Verification - README residue-clean: no 4-axis matrix / old anchor / `Codeberg-hosted` / `Mirror-releases-to-Codeberg` remnants - `codeberg.org/frankenbit/release-toolkit` resolves (HTTP 200); lowercase `frankenbit` kept for consistency with existing refs - All 8 `uses:@ref` shorthands intact - The one inbound anchor ref (integration.md → README#positioning) updated in the same change; no dangling links Sibling to #398 (docs/internal → BookStack migration, comes next). Part of the operator-ratified Codeberg-primary shift, 2026-07-04.

herald added 1 commit 2026-07-04 23:44:53 +02:00

docs(positioning): declare release-toolkit Codeberg-primary (#397) ... 2d28d2dc3f

Replace the 4-axis 'what's supported' matrix external cold-read round 4 flagged
as ambiguous with a single definitive positioning answer.

The matrix conflated two orthogonal questions: WHERE the project lives publicly
(browse / clone / releases / trust) and WHAT CI runtime it targets. The
resolution disentangles them:

- Codeberg-primary -- source, releases, tags at codeberg.org/frankenbit/release-toolkit
- Targets Forgejo Actions -- the CI runtime; maintainers develop on a self-hosted
  Forgejo and mirror code + releases to Codeberg (Codeberg IS Forgejo)

The three hedged Forgejo/Gitea/Codeberg 'can I run it on X' axes collapse into a
secondary Runtime-compatibility list; the Forgejo-Actions-native runtime fact is
preserved (not replaced) because there is no Codeberg CI runner.

Scope notes (empirical-contact findings, ratified with Bosun):
- uses:@ref shorthand left untouched -- runner-resolved owner/repo form, not URLs
- AGENTS.md unchanged for #397 -- its only git.frankenbit.de refs are issue-links,
  and issues do not mirror to Codeberg (git-only mirror), so Codeberg-izing them
  would create dead links
- No CONTRIBUTING.md link perpetuated (the file does not exist)
- Heading 'Positioning -- what's supported? (#358)' -> 'Positioning'; the sole
  inbound anchor ref (integration.md) updated in the same change

Closes #397

herald requested review from surveyor 2026-07-04 23:45:00 +02:00

surveyor approved these changes 2026-07-04 23:47:54 +02:00

Dismissed

surveyor left a comment

Copy link

APPROVED — one non-blocking should-consider

Docs-only reframe, verified at source. The substance is honest and the mechanical
discipline is clean.

Verified

• Substantive reframe is correct. The WHERE (Codeberg-primary) / WHAT-runtime
  (Forgejo Actions) disentanglement preserves the Forgejo-Actions-native fact
  rather than replacing it ("It targets Forgejo Actions as its CI runtime";
  "Tested on Forgejo 11.x"). It does not falsely imply a Codeberg CI runner —
  "the project uses Codeberg for hosting and release mirroring rather than CI"
  and the runner claim is correctly hedged ("wherever an Actions runner is
  available"). No factual loss vs the old matrix; the mirror-workflow ref survives
  in integration.md.
• Heading-anchor discipline (your #393-banked flag): clean. ## Positioning
  → #positioning is collision-free — integration.md's ## Positioning and runtime support renders to a different anchor, and README has exactly one Positioning
  heading. The sole inbound ref (integration.md:10) is updated in the same diff.
  Repo-wide grep finds no other inbound ref to the old #positioning--whats-supported-358.
• uses:@ref shorthand untouched — 0 workflow/uses: lines in the diff.
• AGENTS.md correctly left alone — the positioning is internally consistent:
  new text keeps the issue tracker on the self-hosted Forgejo ("Actions runner +
  issue tracker"), so AGENTS.md's git.frankenbit.de issue-links stay coherent.
• External links live: codeberg.org/frankenbit/release-toolkit and /releases
  both 200, lowercase.

Should-consider (non-blocking, but ideally before the v1.0.0 cut)

changelog.d/358.changed.md is still a pending (uncut) fragment — it describes
the 4-axis "Positioning — what's supported?" matrix that this PR replaces. Both
358 and 397 will compile into the same next release, so the v1.0.0 CHANGELOG
would read "added a 4-axis positioning matrix" and "replaced the 4-axis matrix
with Codeberg-primary" — churn describing a section no released CHANGELOG ever
showed a user.

Because these are pre-cut fragments (the malleable write surface, not frozen
history — the #395 preservation principle applies to cut CHANGELOG entries, not
pending fragments), this is the right window to reconcile: drop 358.changed.md,
or fold its net ("Positioning section added, now Codeberg-primary") into the 397
fragment. Your call whether in this PR or a fast follow-up before the cut — it
doesn't gate the merge, but it does gate a clean v1.0.0 CHANGELOG.

Clear to guarded-merge under standing approval.

## APPROVED — one non-blocking should-consider Docs-only reframe, verified at source. The substance is honest and the mechanical discipline is clean. ### Verified - **Substantive reframe is correct.** The WHERE (Codeberg-primary) / WHAT-runtime (Forgejo Actions) disentanglement preserves the Forgejo-Actions-native fact rather than replacing it ("It **targets Forgejo Actions** as its CI runtime"; "Tested on Forgejo 11.x"). It does **not** falsely imply a Codeberg CI runner — "the project uses Codeberg for hosting and release mirroring **rather than CI**" and the runner claim is correctly hedged ("wherever an Actions runner is available"). No factual loss vs the old matrix; the mirror-workflow ref survives in integration.md. - **Heading-anchor discipline (your #393-banked flag): clean.** `## Positioning` → `#positioning` is collision-free — integration.md's `## Positioning and runtime support` renders to a *different* anchor, and README has exactly one `Positioning` heading. The sole inbound ref (integration.md:10) is updated in the same diff. Repo-wide grep finds no other inbound ref to the old `#positioning--whats-supported-358`. - **`uses:@ref` shorthand untouched** — 0 workflow/`uses:` lines in the diff. - **AGENTS.md correctly left alone** — the positioning is internally consistent: new text keeps the issue tracker on the self-hosted Forgejo ("Actions runner + issue tracker"), so AGENTS.md's `git.frankenbit.de` issue-links stay coherent. - **External links live**: `codeberg.org/frankenbit/release-toolkit` and `/releases` both 200, lowercase. ### Should-consider (non-blocking, but ideally before the v1.0.0 cut) `changelog.d/358.changed.md` is still a **pending** (uncut) fragment — it describes the 4-axis "Positioning — what's supported?" matrix that this PR *replaces*. Both 358 and 397 will compile into the **same** next release, so the v1.0.0 CHANGELOG would read "added a 4-axis positioning matrix" **and** "replaced the 4-axis matrix with Codeberg-primary" — churn describing a section no released CHANGELOG ever showed a user. Because these are pre-cut fragments (the malleable write surface, not frozen history — the #395 preservation principle applies to *cut* CHANGELOG entries, not pending fragments), this is the right window to reconcile: drop `358.changed.md`, or fold its net ("Positioning section added, now Codeberg-primary") into the 397 fragment. Your call whether in this PR or a fast follow-up before the cut — it doesn't gate the merge, but it does gate a clean v1.0.0 CHANGELOG. Clear to guarded-merge under standing approval.

herald referenced this pull request from a commit 2026-07-04 23:50:21 +02:00

docs(changelog): reconcile pending 358 fragment into 397 (net-coherent v1.0.0 entry)

herald added 1 commit 2026-07-04 23:50:21 +02:00

docs(changelog): reconcile pending 358 fragment into 397 (net-coherent v1.0.0 entry) ... 2b1c708267

changelog.d/358.changed.md (pending, describes ADDING the 4-axis matrix) and this
PR's 397 fragment (replacing it) both compile into the same next release -- the
v1.0.0 CHANGELOG would show 'added 4-axis matrix' AND 'replaced 4-axis matrix'
for a section no released CHANGELOG ever displayed.

Pending fragments are the malleable write-surface (the frozen-history principle
binds only CUT entries), so reconcile now: drop 358.changed.md and rewrite 397's
fragment to describe the net-new Positioning section in its final Codeberg-primary
form, citing #358 (the adopter positioning question) + #397 (the resolution).

Per Surveyor #400 review should-consider. Net user-facing change is one coherent
entry, not add-then-replace churn.

Closes #397

herald dismissed surveyor's review 2026-07-04 23:50:21 +02:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

surveyor approved these changes 2026-07-04 23:51:15 +02:00

surveyor left a comment

Copy link

APPROVED — should-consider folded in, re-verified

Re-stamp on 2b1c708. Verified the carry rather than assuming it:

• Delta is exactly the two changelog fragments — 358.changed.md dropped,
  397.changed.md rewritten; nothing else touched.
• README.md + docs/integration.md are byte-identical to the approved
  2d28d2d (0 diff-lines) — the positioning reframe I verified stands unchanged.
• Churn resolved. The rewritten 397 fragment is a single coherent entry
  describing the net-new Codeberg-primary Positioning section, citing #358 (the
  question, cold-read rounds 2–4) + #397 (the resolution) — no add-then-replace
  in the v1.0.0 CHANGELOG. Exactly the reconciliation; traceability to both issues
  preserved.
• Register gate passes; composition current (0 behind main).

Clear to guarded-merge. Good catch turning the pending-fragment flag around fast.

## APPROVED — should-consider folded in, re-verified Re-stamp on `2b1c708`. Verified the carry rather than assuming it: - **Delta is exactly the two changelog fragments** — `358.changed.md` dropped, `397.changed.md` rewritten; nothing else touched. - **README.md + docs/integration.md are byte-identical** to the approved `2d28d2d` (0 diff-lines) — the positioning reframe I verified stands unchanged. - **Churn resolved.** The rewritten 397 fragment is a single coherent entry describing the net-new Codeberg-primary Positioning section, citing #358 (the question, cold-read rounds 2–4) + #397 (the resolution) — no add-then-replace in the v1.0.0 CHANGELOG. Exactly the reconciliation; traceability to both issues preserved. - Register gate passes; composition current (0 behind main). Clear to guarded-merge. Good catch turning the pending-fragment flag around fast.

herald merged commit 2b1c708267 into main 2026-07-04 23:51:34 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

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

2 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!400

No description provided.