docs: add RELEASE.md with the Go module release process

Aperta
  • Qualcosa non va?
#94 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
55/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
go
Ambito
documentation

Direzione di ricerca

Start with the root README.md and CONTRIBUTING.md, then inspect CHANGELOG.md, go.mod, go.work, existing tags, and the related release documentation in backblaze-labs/b2-mcp. Draft RELEASE.md with the listed Go module release steps and link it from both project guides; verify commands in a real or scratch tag workflow. Done when maintainers can follow the documented process for the next tagged release.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation

Add a RELEASE.md at the repo root documenting how blazer is released as a Go module. It should be adapted from the release doc in backblaze-labs/b2-mcp, keeping the structure (changelog discipline, release gate, normal release, prerelease, rollback, deprecation, support policy) and replacing everything npm, GHCR and MCPB specific with Go module equivalents.

Context: blazer is at major version 0. The last tag before the current line was v0.7.2, the fix for #31 sat unreleased for months, a v0.8.0 tag now exists, and there are no GitHub Releases at all. A written process would have prevented the unreleased-fix gap.

Sections to include:

  • Ownership: release owner and security/quality reviewer (names to be filled in by maintainers).
  • Changelog discipline: every user-visible change goes under [Unreleased] in CHANGELOG.md using Keep a Changelog headings (Added, Changed, Deprecated, Removed, Fixed, Security); promote to a dated version section only when tagging; no GitHub Release without a matching changelog section and tag.
  • Versioning rules: semver with a v prefix; v0 and v1 module paths carry no suffix, a /vN suffix is required only from v2 onward; v0 gives no compatibility guarantee but breaking changes should still be called out in the changelog; pseudo-versions are not releases.
  • Multi-module layout: go.work includes ./bin/b2keys, which is a separate module, so it is tagged with a path prefix (bin/b2keys/vX.Y.Z) and must not be tagged by accident with the root tag. Document when it needs its own release and how its require on the root module is updated first. go.work is for local development only and must not affect released modules.
  • Release gate (run from a clean, up-to-date default branch): go mod tidy -diff, gofmt -l . empty, go build ./..., go vet ./..., go test -race ./..., the linter and govulncheck ./... once the CI issues land, the live integration suite run with the standard B2_APPLICATION_KEY_ID, B2_APPLICATION_KEY, B2_MASTER_KEY_ID, B2_MASTER_KEY and B2_REGION variables, and apidiff or gorelease against the previous tag to confirm the exported API changes match the version bump.
  • Normal release: update CHANGELOG.md and compare links, commit, create a signed tag (git tag -s vX.Y.Z -m vX.Y.Z), push the commit and let default-branch CI pass before pushing the tag, then create the GitHub Release from the tag with notes copied from the changelog. Never publish from a workstation without the gate; prefer a tag-triggered workflow once CI exists.
  • Module proxy propagation: after tagging, request the version from the proxy (GOPROXY=https://proxy.golang.org go list -m github.com/Backblaze/[email protected]) and confirm it resolves on pkg.go.dev, because the proxy and checksum database cache versions permanently.
  • Tags are immutable: never delete, move or force-push a release tag, since sum.golang.org records the first hash it sees and a changed tag breaks every consumer with a checksum mismatch. Protect v* tags with a tag ruleset limited to release owners.
  • Prerelease: tags such as v0.10.0-rc.1, same flow, validated with go get github.com/Backblaze/[email protected] in a scratch module before advertising.
  • Rollback and bad releases: versions cannot be unpublished from the proxy. Add a retract directive (with a rationale comment) in go.mod and publish a higher fixed version; the retraction only takes effect once the new version is tagged and fetched.
  • Deprecation: mark a package or module with a // Deprecated: paragraph in its doc comment, naming the replacement.
  • Support policy: only the latest minor line receives fixes; earlier releases are not patched in place; consumers such as restic are told to upgrade. Cross-link SECURITY.md for vulnerability handling and the Go version support (minimum go directive in go.mod, and when it may be raised).
  • Breaking-change notes: how to document API removals or signature changes in release notes, with a migration table where useful.
  • Post-release checks: pkg.go.dev shows the new version, the changelog compare link resolves, and downstream pinned consumers are notified for fixes they were waiting on.

Acceptance: RELEASE.md is merged, linked from README.md and CONTRIBUTING.md, every command in it has been run against a real or scratch tag, and the process is used for the next tagged release.

Related: #93 (zizmor), #92 (rename master to main; update the branch name in RELEASE.md accordingly), and the CI work that the tag-triggered release step depends on.

Lingua principale
Go
Stelle
66
Fork
18
Merge medio
1g 10h
PR unite (30g)
132

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Backblaze/blazer

Tutte le issue di Backblaze/blazer

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.