Skip to content

docs: state the release and tag rules - #85

Merged
imanimanyara merged 3 commits into
mainfrom
docs/releases-and-versioning
Nov 1, 2026
Merged

imanimanyara merged 3 commits into
mainfrom
docs/releases-and-versioning

Conversation

@imanimanyara

Copy link
Copy Markdown
Contributor

Summary

  • CONTRIBUTING.md gains a Releases and versioning section: a vX.Y.Z tag only for final code, vX.Y.Z-rc.N for test builds, a public tag never moved, deleted or reused (the Go module proxy, sum.golang.org, Packagist and npm keep the first copy they fetch), the tag ruleset that enforces it once the v0.1.0 tags are pushed, and a bad release retracted and fixed forward (named in the CHANGELOG and release notes; Packagist has no per-version retraction).
  • docs/release.md gains a short Tags are final section pointing at it.

Docs only; no code or metadata changes.

Copilot AI balanced review requested due to automatic review settings November 1, 2026 06:14

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The documentation incorrectly treats Git-tag dependencies as immutable, overlooking that moved tags can cause fresh and lockfile-based installs to resolve different code.

1 open issue
What changed in this PR

This documentation-only PR establishes release and tag rules for maintainers and links them from the release guide.

Changes:

  • Reserves final version tags for releases and uses release-candidate tags for test builds.
  • Documents public-tag immutability and planned tag-ruleset enforcement.
  • Requires bad releases to be documented and fixed in a new version rather than replaced.
File Description
docs/​release.md Adds a “Tags are final” summary linking to the full policy.
CONTRIBUTING.md Adds release, versioning, tag-protection, and bad-release handling rules.

Review effort: Balanced

Comment thread CONTRIBUTING.md Resolved
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.
@imanimanyara
imanimanyara merged commit 42107ca into main Nov 1, 2026
10 checks passed
@imanimanyara
imanimanyara deleted the docs/releases-and-versioning branch November 1, 2026 21:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants