From 9cdaf86eff4b0c87c1ac8ad09e1395409fab5d14 Mon Sep 17 00:00:00 2001 From: Stackie Jia Date: Tue, 18 Aug 2026 01:50:44 +0800 Subject: [PATCH] docs(release): collapse superseded prerelease notes after GA Co-authored-by: Cursor --- .agents/skills/release/SKILL.md | 70 ++++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 10 deletions(-) diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md index 7f462272..884f7385 100644 --- a/.agents/skills/release/SKILL.md +++ b/.agents/skills/release/SKILL.md @@ -1,6 +1,6 @@ --- name: release -description: Execute the rtp2httpd release workflow — cumulative prerelease and formal release notes, tagging, GitHub releases, CI handling, and stable branch updates. +description: Execute the rtp2httpd release workflow — cumulative prerelease and formal release notes, tagging, GitHub releases, collapsing superseded prerelease notes after GA, CI handling, and stable branch updates. --- # rtp2httpd Release Workflow @@ -35,6 +35,8 @@ Follow these steps in order. - every published prerelease whose SemVer suffix can be stripped to exactly the target base version; and - the latest such prerelease by publication time, if any. These are release-note sources, not just version-number inputs. Never use prerelease notes from another base version. + After a formal release is published, the same-series prerelease list is reused to collapse those GitHub Release + notes into a default-hidden accordion. --- @@ -104,9 +106,11 @@ subjects as evidence, not release-note copy: retain user-focused wording from ex remove it. If the evidence is ambiguous, keep it and flag it during review rather than silently dropping it. - User-provided corrections take precedence over inherited wording. Otherwise, avoid gratuitously rewriting established prerelease notes when preparing the formal release. -- Normalize each source body before merging: remove the complete donation table using the donation asset URL as its - marker, then split at the standalone `---` separator into Chinese and English sections. Do not confuse that separator - with the donation table's `| --- |` row. +- Normalize each source body before merging: unwrap a GitHub `
` accordion if present (drop the outer + `
` / `` / `
` tags and keep only the inner markdown; do not treat the summary line as a + release-note item), remove the complete donation table using the donation asset URL as its marker, then split at the + standalone `---` separator into Chinese and English sections. Do not confuse that separator with the donation + table's `| --- |` row. - Treat each retained or new change as a bilingual item pair. Merge and deduplicate the pairs, keep the two language sections semantically aligned, and update the counterpart translation whenever a correction changes one language. - Rebuild the canonical structure below only after merging so the final file contains exactly one donation block. @@ -204,8 +208,8 @@ Use `AskQuestion` with header "Ready to release?": > Ready to create release v3.x.y? Show a summary: release notes file path, the release-note sources used (including inherited prereleases), lint, tag -creation, release creation, previous-release donation cleanup, and the CI/stable behavior appropriate for a formal -release or prerelease. +creation, release creation, previous-release donation cleanup, collapsing same-series prerelease notes after a formal +release, and the CI/stable behavior appropriate for a formal release or prerelease. Options: - **Yes, release it!** — proceed with the release @@ -315,7 +319,50 @@ latest published release (formal or prerelease): exactly one donation block immediately previous release: no donation block ``` -### Step 10: Handle the CI `versioned` Job +### Step 10: Collapse Same-Series Prerelease Notes After a Formal Release + +If the GitHub Release is a prerelease, **skip this step entirely**. Earlier prereleases in an in-progress series must +remain fully visible. + +After a formal release is published, the same-base-version prereleases are superseded by the GA notes. Collapse each of +those prerelease GitHub Release bodies into a default-hidden accordion so they no longer occupy the releases page. + +Use the same-series prerelease tags identified in Step 0 — every published prerelease whose SemVer suffix strips to +exactly the new formal tag's base version (for example `v3.16.0-beta.0`, `v3.16.0-beta.1`, `v3.16.0-beta.2` after +publishing `v3.16.0`). Do not include prereleases from a different base version. + +For each such tag: + +1. Fetch the current body with `gh release view --json body`. +2. If the body is already wrapped in a top-level `
` accordion, skip that tag. Do not nest another wrapper. +3. Preserve the inner notes exactly. Do not add or remove the donation block in this step; donation cleanup is Step 9 + only. +4. Wrap the body with this canonical GitHub Flavored Markdown accordion. Do **not** add the `open` attribute — the + section must be collapsed by default. Leave a blank line after `` so GitHub renders the inner markdown: + +```markdown +
+预发布说明（已并入 v3.x.y） / Prerelease notes (included in v3.x.y) + +{original body} + +
+``` + +Replace `v3.x.y` with the formal tag just published. Keep the summary wording exactly in this bilingual form. + +5. Write the wrapped notes to a temporary file and apply them with `gh release edit --notes-file ...`. Do not + pass multiline notes as command arguments. +6. Run any wrapping helper through `uv run`, never directly through `python`. +7. Retry transient GitHub API 503s; if an edit still fails, report the remaining tags and a safe retry command. Do not + delete or recreate the new formal release. + +Do not wrap the newly published formal release, prereleases from another base version, or older formal releases. + +Verify afterward that each updated prerelease body contains `
` and `
`, does not contain +`
` + accordion. Leave in-progress prerelease series fully visible. Do not wrap the new formal release. - The latest published release always contains the donation QR block after its Chinese content; the immediately previous release has that block removed after publishing. - Never force-push to `main` or `stable`.