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

Abierto
  • ¿Algo no está bien?
#94 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
55/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
go
Área
documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Go
Estrellas
66
Forks
18
Merge medio
1 d 10 h
PR fusionados (30 d)
132

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Backblaze/blazer

Todos los issues de Backblaze/blazer

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.