Go Modules Quick Start Guide

Semantic Versioning

Modules use vMajor.Minor.Patch format for package versions.

For beta or alpha versions, add a hyphen followed by dot-separated identifiers. For example, v1.0.1-beta.2 indicates a pre-release version.

Version Upgrade Rules

Unstable Releases

New packages start with major version v0, indicating an initial unstable dependency. The API isn’t guaranteed stable under this major version. Here’s how new packages iterate:

// Local
$ go mod tidy
$ go test ./...

// Remote
$ git commit -m "write something"
$ git tag v0.1.0
$ git push origin v0.1.0

Verify the released version works for others:

$ go list -m example.com/hello@v0.1.0

Stable Releases

At this point, API design stabilizes. Exported functions and method signatures must remain unchanged. Exported types must persist. For new features, bump the minor version. For bug fixes, bump the patch version.

Major Version Upgrades

When you need to break backward compatibility and redesign APIs, change the major version. Users must manually update their import paths to use the new version. For example, import "rsc.io/quote/v3" explicitly uses version v3 of the package.

Multiple Versions Coexistence

In your project root where go.mod exists, create a v2 folder. Copy your .go files there, then use edit to make v2 a new module:

go mod edit -module github.com/googleapis/gax-go/v2 v2/go.mod

After making breaking changes, you can batch update import paths locally in programs that reference this package:

find . -type f \
    -name '*.go' \
    -exec sed -i -e 's,github.com/my/project,github.com/my/project/v2,g' {} \;

For pre-releases, tag with appropriate test versions like v2.0.0-alpha1. After testing, apply the official version tag and publish.