chore(release): v0.5.0

forgejo-actions commented

2026-06-26 00:40:40 +02:00

Added

fragments: release-notes/CHANGELOG bifurcation via summary frontmatter (closes #77)

Fixed

_release: manifest update via PR instead of direct-push to main (closes #78)

Added

v0.5.0 docs lock-in — the final slice of the v0.4.0 architectural arc (#52).

docs/integration.md rewritten for the v0.4.0+ shape — push: branches: [main] trigger, rolling-PR mechanic, single _release.yml reusable (no more separate release-draft.yml). Added two new sections: (a) Fragment summary: frontmatter explaining the (B1) release-notes/CHANGELOG bifurcation + the quote-your-#-references convention with the empirical YAML-comment-truncation regression guard; (b) Branch protection compatibility explaining the (B) manifest-via-PR cut-path mechanic + the auto-merge fallback behavior.
AGENTS.md (new) — the implementer pre-flight checklist for contributors touching _release.yml / release-prep.sh / draft-release.sh / lib/fragments.sh. Codifies the carry-forward enumeration discipline (predecessor-step audit; Surveyor ec4c framing), the self-bootstrap re-pin pattern (Surveyor b7e7 axis-sharpening — mechanism-of-touch, not version-magnitude), the YAML / awk / bash gotchas surfaced during the v0.4.0–v0.5.0 arc, cut-verification-as-load-bearing (Surveyor d64a), decision-tree-not-conclusion in PR bodies, source-grounded vs invented claims (Surveyor 5bbe placebo-test catch + 6a82 stale-clone-origin-main self-correction), and the filed-root-cause-is-hypothesis discipline. Each item is anchored to the specific empirical catch that surfaced it.
docs/migration/v0.3-to-v0.5.md (new) — step-by-step migration guide for v0.3.x consumers moving to v0.5.0. Covers the release.yml rewrite, release-draft.yml deletion, manifest bootstrap, branch-protection check, and optional summary: frontmatter retrofit. Includes a rollback section — @v0.3.x workflows remain published, no forced cutover.
changelog.d/78-cut-path-manifest-via-pr.fixed.md updated with a summary: frontmatter so the v0.5.0 release-notes body is concise (operator-flagged on the v0.4.0 cut; per Surveyor 015d's sequencing flag this had to land in slice 5 before the v0.5.0 cut to avoid shipping the long fallback in production release notes).

Closes #52 slice 5.

Fragment frontmatter (B1) — release-notes vs CHANGELOG.md bifurcation. Fragments now accept an optional YAML frontmatter with a summary: field that feeds into the Forgejo release-notes body without affecting CHANGELOG.md composition (the full body still lands there, verbatim, for repo history / developer audience). The release-notes pipeline reads .release-toolkit-release-notes.md (a sidecar written by release-prep.sh from fragment summaries grouped by kind); draft-release.sh consumes the sidecar as the release body, falling back to the CHANGELOG section when the sidecar is absent (v0.3.x behavior preserved).

Authors can opt in by adding frontmatter to any fragment:

---
summary: 'Short consumer-facing summary, quoted because of #N references.'
---

Long-form prose for the CHANGELOG.md section — substrate-honest context,
root-cause analysis, design tradeoffs, all the developer-audience detail
that would clutter the release page but belongs in repo history.

Quoting is required when the summary contains # (YAML treats unquoted # as start-of-comment; the bats suite includes a regression guard demonstrating the truncation behavior so the convention is enforced empirically, not just documented). Block-scalar form (summary: |) is also supported for multi-line summaries.

Fragments without frontmatter continue to work unchanged — the fallback path uses the first non-empty paragraph of the body as the summary. Backward-compatible; opt-in per fragment.

Lighter sibling of ADR-0006 path (a3) — bifurcates the prose without bifurcating the lifecycle (sidecar overwrites each cut; CHANGELOG.md accumulates). Closes #77.

fragments: release-notes/CHANGELOG bifurcation via summary frontmatter (closes #77)

Fixed

_release.yml cut path + lib/forgejo-api.sh: the cut path now opens a PR for the manifest update instead of direct-pushing to main, then attempts to auto-merge via the Forgejo API. Previously the workflow's GITHUB_TOKEN got rejected by the pre-receive hook on any branch-protected main (where apply_to_admins: false); the cut completed the draft release but left the manifest update stranded. The new path is self-contained — no admin-scope tokens required from consumers (path (B) in #78, operator-selected over (A) admin-PAT for the security-surface asymmetry). New helpers forgejo_merge_pr + forgejo_create_issue_comment added to lib/forgejo-api.sh. If auto-merge fails (e.g., branch protection still forbids the workflow token from merging), the PR sits open with an explanatory comment and manual-merge instructions in the body. Closes #78.

_release: manifest update via PR instead of direct-push to main (closes #78)

### Added - **fragments**: release-notes/CHANGELOG bifurcation via summary frontmatter (closes #77) ### Fixed - **_release**: manifest update via PR instead of direct-push to main (closes #78) ### Added **v0.5.0 docs lock-in** — the final slice of the v0.4.0 architectural arc ([#52](https://git.frankenbit.de/frankenbit/release-toolkit/issues/52)). - **`docs/integration.md`** rewritten for the v0.4.0+ shape — `push: branches: [main]` trigger, rolling-PR mechanic, single `_release.yml` reusable (no more separate `release-draft.yml`). Added two new sections: (a) **Fragment `summary:` frontmatter** explaining the (B1) release-notes/CHANGELOG bifurcation + the quote-your-`#`-references convention with the empirical YAML-comment-truncation regression guard; (b) **Branch protection compatibility** explaining the (B) manifest-via-PR cut-path mechanic + the auto-merge fallback behavior. - **`AGENTS.md`** (new) — the implementer pre-flight checklist for contributors touching `_release.yml` / `release-prep.sh` / `draft-release.sh` / `lib/fragments.sh`. Codifies the carry-forward enumeration discipline (predecessor-step audit; Surveyor ec4c framing), the self-bootstrap re-pin pattern (Surveyor b7e7 axis-sharpening — mechanism-of-touch, not version-magnitude), the YAML / awk / bash gotchas surfaced during the v0.4.0–v0.5.0 arc, cut-verification-as-load-bearing (Surveyor d64a), decision-tree-not-conclusion in PR bodies, source-grounded vs invented claims (Surveyor 5bbe placebo-test catch + 6a82 stale-clone-origin-main self-correction), and the filed-root-cause-is-hypothesis discipline. Each item is anchored to the specific empirical catch that surfaced it. - **`docs/migration/v0.3-to-v0.5.md`** (new) — step-by-step migration guide for v0.3.x consumers moving to v0.5.0. Covers the `release.yml` rewrite, `release-draft.yml` deletion, manifest bootstrap, branch-protection check, and optional `summary:` frontmatter retrofit. Includes a rollback section — `@v0.3.x` workflows remain published, no forced cutover. - **`changelog.d/78-cut-path-manifest-via-pr.fixed.md`** updated with a `summary:` frontmatter so the v0.5.0 release-notes body is concise (operator-flagged on the v0.4.0 cut; per Surveyor 015d's sequencing flag this had to land in slice 5 before the v0.5.0 cut to avoid shipping the long fallback in production release notes). Closes [#52](https://git.frankenbit.de/frankenbit/release-toolkit/issues/52) slice 5. **Fragment frontmatter (B1) — release-notes vs CHANGELOG.md bifurcation.** Fragments now accept an optional YAML frontmatter with a `summary:` field that feeds into the Forgejo release-notes body without affecting CHANGELOG.md composition (the full body still lands there, verbatim, for repo history / developer audience). The release-notes pipeline reads `.release-toolkit-release-notes.md` (a sidecar written by `release-prep.sh` from fragment summaries grouped by kind); `draft-release.sh` consumes the sidecar as the release body, falling back to the CHANGELOG section when the sidecar is absent (v0.3.x behavior preserved). Authors can opt in by adding frontmatter to any fragment: ```markdown --- summary: 'Short consumer-facing summary, quoted because of #N references.' --- Long-form prose for the CHANGELOG.md section — substrate-honest context, root-cause analysis, design tradeoffs, all the developer-audience detail that would clutter the release page but belongs in repo history. ``` Quoting is required when the summary contains `#` (YAML treats unquoted `#` as start-of-comment; the bats suite includes a regression guard demonstrating the truncation behavior so the convention is enforced empirically, not just documented). Block-scalar form (`summary: |`) is also supported for multi-line summaries. Fragments without frontmatter continue to work unchanged — the fallback path uses the first non-empty paragraph of the body as the summary. Backward-compatible; opt-in per fragment. Lighter sibling of ADR-0006 path (a3) — bifurcates the prose without bifurcating the lifecycle (sidecar overwrites each cut; CHANGELOG.md accumulates). Closes [#77](https://git.frankenbit.de/frankenbit/release-toolkit/issues/77). - **fragments**: release-notes/CHANGELOG bifurcation via summary frontmatter (closes #77) ### Fixed **`_release.yml` cut path + `lib/forgejo-api.sh`**: the cut path now opens a PR for the manifest update instead of direct-pushing to `main`, then attempts to auto-merge via the Forgejo API. Previously the workflow's `GITHUB_TOKEN` got rejected by the pre-receive hook on any branch-protected `main` (where `apply_to_admins: false`); the cut completed the draft release but left the manifest update stranded. The new path is self-contained — no admin-scope tokens required from consumers (path **(B)** in [#78](https://git.frankenbit.de/frankenbit/release-toolkit/issues/78), operator-selected over **(A)** admin-PAT for the security-surface asymmetry). New helpers `forgejo_merge_pr` + `forgejo_create_issue_comment` added to `lib/forgejo-api.sh`. If auto-merge fails (e.g., branch protection still forbids the workflow token from merging), the PR sits open with an explanatory comment and manual-merge instructions in the body. Closes [#78](https://git.frankenbit.de/frankenbit/release-toolkit/issues/78). - **_release**: manifest update via PR instead of direct-push to main (closes #78)

quartermaster force-pushed release-prep/rolling from 830a523851 to 04cc73999a

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s

Details

manifest-check / check (pull_request) Successful in 0s

Details

2026-06-26 00:43:00 +02:00

Compare

quartermaster closed this pull request

2026-06-26 00:50:12 +02:00

quartermaster commented

2026-06-26 00:50:12 +02:00

Owner

Closing as stale. This PR was opened at 00:40:40 by the Layer 2 cut-safeguard protective fall-through after operator merged the original v0.5.0 rolling PR #80 at 00:40:30 — forgejo_find_pr_by_merge_sha lookup lagged ~8s behind the merge, so Layer 2 couldn't verify #80's head=release-prep/rolling provenance and fell through to mode=update (safe-fail), opening this PR as a precaution.

The actual v0.5.0 cut was later dispatched manually (after Forgejo's API caught up) and completed end-to-end: v0.5.0 draft → operator Publish → v0.5.0 GA, with PR #85 carrying the manifest update.

Follow-up trackers filed for the underlying substrate gaps:

Layer 2 race-condition needs retry-with-backoff (v0.5.1 candidate)
Stale rolling PR cleanup after fall-through + later cut success (v0.5.1 candidate)

No merge action needed on this PR. The release-prep/rolling branch is preserved (stable identity); the next legitimate mode=update will force-reset it cleanly.

Closing as stale. This PR was opened at 00:40:40 by the Layer 2 cut-safeguard protective fall-through after operator merged the original v0.5.0 rolling PR #80 at 00:40:30 — `forgejo_find_pr_by_merge_sha` lookup lagged ~8s behind the merge, so Layer 2 couldn't verify #80's head=release-prep/rolling provenance and fell through to mode=update (safe-fail), opening this PR as a precaution. The actual v0.5.0 cut was later dispatched manually (after Forgejo's API caught up) and completed end-to-end: v0.5.0 draft → operator Publish → v0.5.0 GA, with PR #85 carrying the manifest update. Follow-up trackers filed for the underlying substrate gaps: - Layer 2 race-condition needs retry-with-backoff (v0.5.1 candidate) - Stale rolling PR cleanup after fall-through + later cut success (v0.5.1 candidate) No merge action needed on this PR. The release-prep/rolling branch is preserved (stable identity); the next legitimate mode=update will force-reset it cleanly.

quartermaster referenced this pull request

2026-06-26 00:50:44 +02:00

bug(release-decide): Layer 2 cut-safeguard race condition — forgejo_find_pr_by_merge_sha lags ~8s behind fresh merge #86

quartermaster referenced this pull request

2026-06-26 00:51:01 +02:00

bug(_release.yml): stale rolling PR not auto-closed after Layer 2 fall-through + later cut success #87

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s

Required

Details

manifest-check / check (pull_request) Successful in 0s

Required

Details

ac-closure-check / ac-closure check (pull_request)

Required

ac-closure-check / check (pull_request)

Required

changelog-body-check / changelog body Cold-Read linter (pull_request)

Required

changelog-body-check / check (pull_request)

Required

check-self-bootstrap / check (pull_request)

Required

fragment-check / check (pull_request)

Required

fragment-check / coverage (pull_request)

Required

fragment-check / density (pull_request)

Required

gitea-twin-check / check (pull_request)

Required

go-ci / lint + build + test (pull_request)

Required

prep-order-check / check (pull_request)

Required

readme-pin-check / digest (pull_request)

Required

register-check / check (pull_request)

Required

register-check / register-drift check (pull_request)

Required

tests / bats (pull_request)

Required

tests / contract-paths (pull_request)

Required

tests / dated-examples (pull_request)

Required

tests / shellcheck (pull_request)

Required

tests / workflow-schema (pull_request)

Required

toolkit-self-gates / toolkit-self gates (PR's own rt) (pull_request)

Required

workflow-parse-check / check (pull_request)

Required

workflow-parse-check / toolkit-self parse guard and controls (pull_request)

Required

workflow-parse-check / workflow parse and schema (pull_request)

Required

Pull request closed

Please reopen this pull request to perform a merge.

Rows
Columns

chore(release): v0.5.0 #84

Added

Fixed

Added

Fixed

Pull request closed