gorelease

Documentation

Overview

gorelease is an experimental tool that helps module authors avoid common problems before releasing a new version of a module.

Usage:

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

Examples:

# Compare with the latest version and suggest a new version.
gorelease

# Compare with a specific version and suggest a new version.
gorelease -base=v1.2.3

# Compare with the latest version and check a specific new version for compatibility.
gorelease -version=v1.3.0

# Compare with a specific version and check a specific new version for compatibility.
gorelease -base=v1.2.3 -version=v1.3.0

gorelease analyzes changes in the public API and dependencies of the main module. It compares a base version (set with -base) with the currently checked out revision. Given a proposed version to release (set with -version), gorelease reports whether the changes are consistent with semantic versioning. If no version is proposed with -version, gorelease suggests the lowest version consistent with semantic versioning.

If there are no visible changes in the module's public API, gorelease accepts versions that increment the minor or patch version numbers. For example, if the base version is "v2.3.1", gorelease would accept "v2.3.2" or "v2.4.0" or any prerelease of those versions, like "v2.4.0-beta". If no version is proposed, gorelease would suggest "v2.3.2".

If there are only backward compatible differences in the module's public API, gorelease only accepts versions that increment the minor version. For example, if the base version is "v2.3.1", gorelease would accept "v2.4.0" but not "v2.3.2".

If there are incompatible API differences for a proposed version with major version 1 or higher, gorelease will exit with a non-zero status. Incompatible differences may only be released in a new major version, which requires creating a module with a different path. For example, if incompatible changes are made in the module "example.com/mod", a new major version must be released as a new module, "example.com/mod/v2". For a proposed version with major version 0, which allows incompatible changes, gorelease will describe all changes, but incompatible changes will not affect its exit status.

For more information on semantic versioning, see https://semver.org.

Note: gorelease does not accept build metadata in releases (like v1.0.0+debug). Although it is valid semver, the Go tool and other tools in the ecosystem do not support it, so its use is not recommended.

gorelease accepts the following flags:

-base=version: The version that the current version of the module will be compared against. This may be a version like "v1.5.2", a version query like "latest", or "none". If the version is "none", gorelease will not compare the current version against any previous version; it will only validate the current version. This is useful for checking the first release of a new major version. The version may be preceded by a different module path and an '@', like -base=example.com/mod/v2@v2.5.2. This is useful to compare against an earlier major version or a fork. If -base is not specified, gorelease will attempt to infer a base version from the -version flag and available released versions.

-version=version: The proposed version to be released. If specified, gorelease will confirm whether this version is consistent with changes made to the module's public API. gorelease will exit with a non-zero status if the version is not valid.

gorelease is eventually intended to be merged into the go command as "go release". See golang.org/issues/26420.