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 0423b97..b31cb93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,3 +8,21 @@ 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`, 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. +- **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. diff --git a/docs/release.md b/docs/release.md index 1001fdf..ffae172 100644 --- a/docs/release.md +++ b/docs/release.md @@ -80,6 +80,16 @@ 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: 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). + --- [← Docs index](../README.md#documentation)