references/go.md
Go Release Practices
Use the standard go toolchain for everything.
Module setup
- Initialize with the canonical repository path:
go mod init github.com/<org>/<project>. The module path is the import path, so set it correctly before anyone depends on the project. - Set the
godirective ingo.modto the latest stable release for greenfield code.
Project layout
cmd/<appname>/main.gofor each binary entry point.internal/for packages that must not be imported by other modules — use it liberally; exporting a package is an API commitment.- Do not create a
pkg/directory reflexively; the official module layout guidance recommends putting importable packages at the repository root unless there is a concrete conflict. - Keep packages focused on a single responsibility, handle every error, and
reserve
panicfor unrecoverable states. Follow Effective Go and the Go style guide.
Testing, formatting, and linting
go test ./...in CI, with-raceenabled — the race detector is cheap insurance for any code with goroutines.gofmt(orgo fmt) before committing; enforce in CI.- golangci-lint with a committed configuration.
- govulncheck in CI to flag known-vulnerable dependencies actually reachable from the code.
Documentation
Write doc comments for every exported identifier — complete sentences beginning with the identifier name. pkg.go.dev renders them automatically once the module is public and tagged.
Publishing and releases
- There is no central upload step: pushing a semver tag (
vX.Y.Z) to the public repository is publishing. The module proxy and pkg.go.dev pick it up automatically. See developing modules. - Because tags are immutable once fetched through the module proxy, never retag; publish a new patch version instead.
- For binaries, use goreleaser to build multi-platform artifacts, generate release notes from commits, and attach everything to the GitHub Release on each tag. Consider GitHub artifact attestations for provenance on released binaries.