modver

README

Modver

This is modver, a Go package and command that helps you obey semantic versioning rules in your Go module.

It can read and compare two different versions of the same module, from two different directories, or two different Git commits. It then reports whether the changes require an increase in the major-version number, the minor-version number, or the patchlevel.

Installation and usage

Install the modver command using Go 1.16 or later like this:

go install github.com/bobg/modver/cmd/modver@latest

Assuming the current directory is the root of a cloned Git repository, you can run it like this:

$ modver -git .git HEAD~1 HEAD

to tell what kind of version-number change is needed for the latest commit. The -git .git gives the path to the repository’s info; it can also be something like https://github.com/bobg/modver. The arguments HEAD~1 and HEAD specify two Git revisions to compare; in this case, the latest two commits on the current branch. These could also be tags or commit hashes.

Modver also has a simple API for use from within Go programs.

Semantic versioning

Briefly, a major-version bump is needed for incompatible changes in the public API, such as when a type is removed or renamed, or parameters or results are added to or removed from a function. Old callers cannot expect to use the new version without being updated.

A minor-version bump is needed when new features are added to the public API, like a new entrypoint or new fields in an existing struct. Old callers can continue using the new version without being updated, but callers depending on the new features cannot use the old version.

A patchlevel bump is needed for most other changes.

The result produced by modver is the minimal change required. The actual change required may be greater. For example, if a new method is added to a type, this function will return Minor. However, if something also changed about an existing method that breaks the old contract - it accepts a narrower range of inputs, for example, or returns errors in some new cases - that may well require a major-version bump, and this function can't detect those cases.

You can be assured, however, that if this function returns Major, a minor-version bump won't suffice, and if this function returns Minor, a patchlevel bump won't suffice, etc.

The modver command (in the cmd/modver subdirectory) can be used, among other ways, to test that each commit to a Git repository increments the module’s version number appropriately. This is done for modver itself using GitHub Actions, here.

(Note that the standard actions/checkout@v2 action, for cloning a repository during GitHub Actions, creates a shallow clone with just one commit’s worth of history. For the usage here to work, you’ll need more history: at least two commit’s worth and maybe more to pull in the latest tag for the previous revision. The clone depth can be overridden with the fetch-depth parameter, which modver does here.)

Documentation

Overview

Package modver compares two versions of the same Go module. It can tell whether the differences require at least a patchlevel version change, or a minor version change, or a major version change, according to semver rules (https://semver.org/).

Index

• type Result
  • func Compare(olders, newers []*packages.Package) Result
  • func CompareDirs(older, newer string) (Result, error)
  • func CompareGit(ctx context.Context, repoURL, olderRev, newerRev string) (Result, error)
  • func CompareGitWith(ctx context.Context, repoURL, olderRev, newerRev string, ...) (Result, error)
• type ResultCode
  • func (r ResultCode) Code() ResultCode
  • func (r ResultCode) String() string

Types

type Result

type Result interface {
	Code() ResultCode
	String() string
	// contains filtered or unexported methods
}

Result is the result of Compare.

func Compare

func Compare(olders, newers []*packages.Package) Result

Compare compares an "older" version of a Go module to a "newer" version of the same module. It tells whether the changes from "older" to "newer" require an increase in the major, minor, or patchlevel version numbers, according to semver rules (https://semver.org/).

Briefly, a major-version bump is needed for incompatible changes in the public API, such as when a type is removed or renamed, or parameters or results are added to or removed from a function. Old callers cannot expect to use the new version without being updated.

A minor-version bump is needed when new features are added to the public API, like a new entrypoint or new fields in an existing struct. Old callers _can_ continue using the new version without being updated, but callers depending on the new features cannot use the old version.

A patchlevel bump is needed for most other changes.

The result of Compare is the _minimal_ change required. The actual change required may be greater. For example, if a new method is added to a type, this function will return Minor. However, if something also changed about an existing method that breaks the old contract - it accepts a narrower range of inputs, for example, or returns errors in some new cases - that may well require a major-version bump, and this function can't detect those cases.

You can be assured, however, that if this function returns Major, a minor-version bump won't suffice, and if this function returns Minor, a patchlevel bump won't suffice, etc.

The packages passed to this function should have no load errors (that is, len(p.Errors) should be 0 for each package p in `olders` and `newers`). If you are using packages.Load (see https://pkg.go.dev/golang.org/x/tools/go/packages#Load), you will need at least

packages.NeedName | packages.NeedTypes | packages.NeedSyntax | packages.NeedTypesInfo

in your Config.Mode. See CompareDirs for an example of how to call Compare with the result of packages.Load.

func CompareDirs

func CompareDirs(older, newer string) (Result, error)

CompareDirs loads Go modules from the directories at older and newer and calls Compare on the results.

func CompareGit

func CompareGit(ctx context.Context, repoURL, olderRev, newerRev string) (Result, error)

CompareGit compares the Go packages in two revisions of a Git repo at the given URL.

func CompareGitWith

func CompareGitWith(ctx context.Context, repoURL, olderRev, newerRev string, f func(older, newer string) (Result, error)) (Result, error)

CompareGitWith compares the Go packages in two revisions of a Git repo at the given URL. It uses the given callback function to perform the comparison.

The callback function receives the paths to two directories, containing two clones of the repo: one checked out at the older revision and one checked out at the newer revision.

Note that CompareGit(...) is simply CompareGitWith(..., CompareDirs).

type ResultCode

type ResultCode int

ResultCode is the required version-bump level as detected by Compare.

const (
	None ResultCode = iota
	Patchlevel
	Minor
	Major
)

Values for ResultCode.

func (ResultCode) Code

func (r ResultCode) Code() ResultCode

Code implements Result.Code.

func (ResultCode) String

func (r ResultCode) String() string

String implements Result.String.