Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
18 changes: 18 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
10 changes: 10 additions & 0 deletions docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Loading