From d239ae214b2f1111e0f9392ecdf3a4704c22ec15 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Sun, 1 Nov 2026 01:12:09 -0500 Subject: [PATCH 1/3] docs(contributing): state the release and tag rules --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0423b97..0b3c5f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,3 +8,19 @@ For this pack specifically: icon assets are refreshed from upstream by the [icon-sets-sync](https://opensource.simtabi.com/documentation/ichava/icon-sets-sync/maintainer-sync). Please do not hand-edit generated SVGs; contribute fixes to the sync recipe or the upstream source instead. + +## Releases and versioning + +- **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`: it is cached like any other tag, but it + uses up no release number. +- **A public tag is never moved, deleted or reused.** The first time anything fetches a tag, its + contents are cached for good: by the Go module proxy and `sum.golang.org` for any public GitHub + tag, by Packagist for a Composer package, and by npm and every consumer pinning a git tag for a + JavaScript one. Moving the tag afterwards does not change what those serve; it only makes them + disagree with git. The next fix gets the next number. +- **A tag ruleset enforces this.** Applied once the v0.1.0 tags are pushed, it blocks deleting, + updating and force-pushing `v*` tags on this repository. The v0.1.0 publication as a + single commit was the one planned exception. +- **A bad release is retracted, not replaced.** Name it in the CHANGELOG and the GitHub release notes, and leave it listed on Packagist, which has no per-version retraction (only a whole package can be marked abandoned). Then ship the fix as the next + version. From 965eefb507df418cb1d84fd9a0acd7cf0f115b42 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Sun, 1 Nov 2026 01:12:09 -0500 Subject: [PATCH 2/3] docs(release): say version tags are final --- docs/release.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/release.md b/docs/release.md index 1001fdf..59e86e3 100644 --- a/docs/release.md +++ b/docs/release.md @@ -80,6 +80,14 @@ commit those tags pointed at is on `main`, so no code was lost; their notes are `CHANGELOG.md` under *Archived pre-reset history*. Version numbers in older changelog entries and issues refer to that earlier series. +## Tags are final + +A pushed `vX.Y.Z` tag is never moved, deleted or reused: the Go module proxy, `sum.golang.org`, +Packagist and npm keep the first copy of a tag they fetch, so a moved tag leaves them serving +different code from git. Test a release with a pre-release tag (`vX.Y.Z-rc.N`), and retract a bad +release and fix it forward in the next version. The full rules are in +[CONTRIBUTING.md](../CONTRIBUTING.md#releases-and-versioning). + --- [← Docs index](../README.md#documentation) From 58c5fd06d6cf5a658748cd001fc93d065917f545 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Sun, 1 Nov 2026 15:57:46 -0500 Subject: [PATCH 3/3] Publish RC tags as pre-releases and state what a moved tag breaks The release workflow published a vX.Y.Z-rc.N tag as a regular release, and needed a CHANGELOG section for the RC version that the docs never mentioned. It now sets prerelease for any tag with a suffix, and the docs name the RC section. The tag rule also claimed every registry keeps the first copy of a tag for good. It does not: git dependencies resolve a moved tag afresh while lockfiles keep the old commit, and sum.golang.org records checksums, not code. The rule stays; the reason now says what actually goes wrong. --- .github/workflows/release.yml | 2 ++ CONTRIBUTING.md | 16 +++++++++------- docs/release.md | 8 +++++--- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 80674fa..ffda2dc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -137,6 +137,8 @@ jobs: with: body: ${{ steps.changelog.outputs.body }} generate_release_notes: true + # A `vX.Y.Z-rc.N` tag is a test build, never a release users should pick up. + prerelease: ${{ contains(github.ref_name, '-') }} files: ichava-icon-sets-flag.cdx.json # Explicit, though it is the action's default: a missing SBOM must not # fail the publish, so it must not rest on a default a reader has to know. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0b3c5f1..b31cb93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,13 +12,15 @@ or the upstream source instead. ## Releases and versioning - **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`: it is cached like any other tag, but it - uses up no release number. -- **A public tag is never moved, deleted or reused.** The first time anything fetches a tag, its - contents are cached for good: by the Go module proxy and `sum.golang.org` for any public GitHub - tag, by Packagist for a Composer package, and by npm and every consumer pinning a git tag for a - JavaScript one. Moving the tag afterwards does not change what those serve; it only makes them - disagree with git. The next fix gets the next number. + 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. +- **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 + registry version cannot be republished at all). For a Go module, the module proxy keeps the copy it + first served and `sum.golang.org` records its checksum, so `go` fetches after the move fail + verification. The next fix gets the next number. - **A tag ruleset enforces this.** Applied once the v0.1.0 tags are pushed, it blocks deleting, updating and force-pushing `v*` tags on this repository. The v0.1.0 publication as a single commit was the one planned exception. diff --git a/docs/release.md b/docs/release.md index 59e86e3..ffae172 100644 --- a/docs/release.md +++ b/docs/release.md @@ -82,9 +82,11 @@ issues refer to that earlier series. ## Tags are final -A pushed `vX.Y.Z` tag is never moved, deleted or reused: the Go module proxy, `sum.golang.org`, -Packagist and npm keep the first copy of a tag they fetch, so a moved tag leaves them serving -different code from git. Test a release with a pre-release tag (`vX.Y.Z-rc.N`), and retract a bad +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 [CONTRIBUTING.md](../CONTRIBUTING.md#releases-and-versioning).