Gorelease

Gorelease is an experimental command-line tool that helps Go module authors avoid common problems before releasing a new version of a module. It analyzes changes in the public API and dependencies, checks compatibility against semantic versioning rules, and recommends appropriate version numbers for releases.

Package Information

• Package Name: golang.org/x/exp/cmd/gorelease
• Package Type: golang (CLI tool)
• Language: Go
• Installation: go install golang.org/x/exp/cmd/gorelease@latest

Core Usage

The gorelease command is executed from the root directory of a Go module:

gorelease [-base={version|none}] [-version=version]

Basic Usage

Gorelease simplifies the release process by automatically checking API compatibility and suggesting appropriate versions:

# Simple usage - compare with latest version and suggest a new version
gorelease

# Specify a base version to compare against
gorelease -base=v1.2.3

# Check if a specific version is valid for release
gorelease -version=v1.3.0

# Check a specific version against a specific base version
gorelease -base=v1.2.3 -version=v1.3.0

# Release the first version of a new major version (no base to compare)
gorelease -base=none -version=v2.0.0

# Compare against a different major version
gorelease -base=example.com/mod/v2@v2.5.2

How Gorelease Works

Gorelease analyzes changes in the public API and dependencies of the main module by comparing a base version (set with -base) against the currently checked-out revision. Based on the changes detected, it validates whether a proposed release version (set with -version) is consistent with semantic versioning rules. If no version is proposed, gorelease suggests the lowest version consistent with semantic versioning.

Versioning Rules

No API Changes: When there are no visible changes in the module's public API, gorelease accepts versions that increment the minor or patch version numbers. The tool will suggest the patch version increment (e.g., v2.3.2 from v2.3.1), but also accepts higher increments and prerelease versions.

Base version: v2.3.1
Accepted: v2.3.2, v2.4.0, v2.4.0-beta, v3.0.0
Suggested: v2.3.2

Backward Compatible API Changes: When there are only backward compatible additions or enhancements to the module's public API, gorelease only accepts versions that increment the minor version. Patch version increments are not permitted.

Base version: v2.3.1
Accepted: v2.4.0, v2.4.0-beta, v3.0.0
Rejected: v2.3.2, v2.3.3

Incompatible API Changes: When there are incompatible (breaking) API differences:

• For proposed versions with major version 1 or higher: Gorelease exits with non-zero status, as incompatible changes may only be released in a new major version, which requires creating a module with a different path (e.g., example.com/mod/v2).
• For proposed versions with major version 0 (pre-release): Gorelease describes all changes but doesn't fail on incompatible changes, since v0.x versions are allowed to have breaking changes.

Command-Line Flags

Gorelease accepts the following flags:

-base=version

Specifies the version that the current version of the module will be compared against.

Accepted values:

• A specific version tag like v1.5.2
• A version query like latest (automatically resolved to the most recent release)
• none (skips comparison and only validates the current version)
• A version with module path like example.com/mod/v2@v2.5.2 (useful for comparing against different major versions or forks)

Default behavior: If -base is not specified, gorelease attempts to infer a base version from the -version flag and available released versions.

Use cases:

• -base=v1.5.2: Compare against a specific release
• -base=latest: Compare against the most recently released version
• -base=none: Check the first release of a new major version without comparing to previous versions
• -base=example.com/mod/v2@v2.5.2: Compare against a different major version

-version=version

Specifies the proposed version to be released.

If specified, gorelease confirms whether this version is consistent with changes made to the module's public API. Gorelease exits with a non-zero status if the version is not valid.

If not specified, gorelease suggests the lowest version consistent with semantic versioning based on the detected API changes.

Important Notes

Build Metadata: Gorelease does not accept build metadata in releases (like v1.0.0+debug). Although build metadata is valid according to semantic versioning, the Go tool and other tools in the ecosystem do not support it, so its use is not recommended.

Prerelease Versions: Gorelease accepts and can suggest prerelease versions (like v1.4.0-beta or v1.4.0-rc1). When no version is proposed with -version, gorelease suggests a stable release version, but users can manually specify prerelease versions for validation.

Module Path: The tool operates on the main module defined in the current directory's go.mod file.

Semantic Versioning: For more information on semantic versioning and its rules, see https://semver.org.

Use Cases

Pre-release Validation

Before tagging and pushing a release, validate that your proposed version is correct:

gorelease -version=v1.2.0

Getting Release Recommendations

Let gorelease suggest the appropriate next version based on API changes:

gorelease

First Release of Major Version

When releasing the first version of a new major version (e.g., v2.0.0) without comparing to the previous major version:

gorelease -base=none -version=v2.0.0

Comparing Across Major Versions

When you need to compare against a different major version or a fork:

gorelease -base=example.com/mod/v2@v2.1.0

Validating Against Specific Base

When you want to validate against a specific historical version:

gorelease -base=v1.5.0 -version=v1.6.0

Exit Status

Gorelease exits with:

• Status 0: The proposed version (or suggested version) is valid and consistent with semantic versioning
• Non-zero status: The proposed version is invalid for the detected API changes, or incompatible changes are being released in a major version 1 or higher without a major version bump

Future Development

Gorelease is an experimental tool that is eventually intended to be merged into the go command as go release. For discussion and tracking of this feature, see golang.org/issues/26420.

See Also

• apidiff: The package that powers gorelease's API change detection - see apidiff documentation
• Semantic Versioning: https://semver.org
• Go Module Documentation: https://golang.org/ref/mod