From 4c672a846f6211d0ffaf76f6825ed190c5cf1aa9 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Mon, 2 Nov 2026 02:48:27 -0500 Subject: [PATCH 1/2] ci(release): publish an -rc tag as a pre-release without its own CHANGELOG section --- .github/workflows/release.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ffda2dc..1eb737d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -115,6 +115,13 @@ jobs: found { print } ' CHANGELOG.md)" + # A pre-release tag (vX.Y.Z-rc.N) is a test build: it publishes as a GitHub + # pre-release and needs no CHANGELOG section of its own. A final tag still + # fails closed below. + if [ -z "$(printf '%s' "$SECTION" | tr -d '[:space:]')" ] && [[ "$VERSION" == *-* ]]; then + SECTION="Pre-release build ${GITHUB_REF_NAME}, for testing. It is not a release; the notes ship with the final v${VERSION%%-*} tag." + fi + # Fail closed. A tag whose version has no CHANGELOG section is a tag # pointing at the wrong commit, or a release nobody wrote notes for — # both are reasons to stop, not to publish auto-generated notes and From 08ed5de707715977bb7afcc9df8f6190f3394415 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Mon, 2 Nov 2026 02:49:12 -0500 Subject: [PATCH 2/2] docs: describe what a moved tag breaks and how -rc tags publish --- CONTRIBUTING.md | 5 +++-- docs/release.md | 6 +++--- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b31cb93..bba9db1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,8 +13,9 @@ or the upstream source instead. - **A version tag is pushed only for final code.** `vX.Y.Z` marks a release, nothing else. To try a release build first, push a pre-release tag, `vX.Y.Z-rc.N`, which uses up no release number. It runs - the same release workflow, so the tagged commit needs its own `## [X.Y.Z-rc.N]` CHANGELOG section - (the workflow refuses to publish without one), and it is published as a GitHub pre-release. + the same release workflow and publishes as a GitHub pre-release. It needs no CHANGELOG section of + its own: the workflow uses a `## [X.Y.Z-rc.N]` section when the commit has one, and a fixed + test-build note otherwise. - **A public tag is never moved, deleted or reused.** Once a tag has been fetched, moving it makes consumers of the same version disagree. Composer and npm git dependencies resolve the tag afresh, so new installs get the moved commit while every existing lockfile and cache keeps the old one (an npm diff --git a/docs/release.md b/docs/release.md index ffae172..857ea70 100644 --- a/docs/release.md +++ b/docs/release.md @@ -85,9 +85,9 @@ issues refer to that earlier series. A pushed `vX.Y.Z` tag is never moved, deleted or reused: once a tag has been fetched, lockfiles and caches keep the commit it named while fresh installs resolve the moved one, so two consumers of the same version run different code (and for a Go module, `sum.golang.org` makes the moved version fail -verification). Test a release with a pre-release tag (`vX.Y.Z-rc.N`), whose commit needs its own -`## [X.Y.Z-rc.N]` CHANGELOG section and which publishes as a GitHub pre-release. Retract a bad -release and fix it forward in the next version. The full rules are in +verification). Test a release with a pre-release tag (`vX.Y.Z-rc.N`): it publishes as a GitHub +pre-release, and needs no CHANGELOG section of its own. Retract a bad release and fix it forward in +the next version. The full rules are in [CONTRIBUTING.md](../CONTRIBUTING.md#releases-and-versioning). ---