Contents
This blog describes what module version numbers mean. Go module's versioning number can signal different things, including stability, backward compatibility, and release changes. Version number also indicates the state of external modules, e.g. stability.
Version Number Meaning
Modules are published with a version number uses the semantic versioning model as depicted in the image below:
The following table describes how the parts of a version number signify a module's stability and backward compatibility.
| Version stage | Example | Meaning |
|---|---|---|
| In development | Automatic pseudo-version number v0.x.x | Signals that the module is still in development and unstable. This release carries no backward compatibility or stability guarantee |
| Major | v1.x.x | Backward-incompatilbe public API changes. This release carries no guarantee that it will be backward compatible with preceding major versions |
| Minor | vx.4.x | Backward compatible public API changes. This release guarantees background compatibility and stability |
| Patch | vx.x.1 | Carries changes that don't affect the module's public API or its dependencies. This release guarantees backward compatibility and stability |
| Pre-release | vx.x.x-beta.2 | Pre-release milestone, such as an alpha or beta. This release carries no stability guarantee |
In Development
This version release carries no backward compatibility or stability. The version number can take on of the following forms:
Pseudo-version number
The syntax for this version is baseVersionPrefix-timestamp-revisionIdentifier for instance: v0.0.0-20170915032832-14c0d48ead0c If a module has not been tagged in its repository, Go will generate a pseudo-version number for use in go.mod. The version number is generated against the commit that hasn't been tagged with semantic version tag.
Parts explained below:- baseVersionPrefix is a value that is either derived from the preceding tag, or from vX.0.0 if there is no tag
- timestamp is the UTC time the revision was created. In Git this is the commit time .
- revisionIdentifier is a 12 character prefix of the commit hash, or in Subversion, a zero-padded revision number.
v0 number
The syntax takes the form of v0.x.x A module published with a v0 number will have a
formal semantic version number with a major, minor, and patch part, as well as an optional
pre-release identifier.
Version v0 can be used in production, but it makes no stability or backward compatibility
guarantees. In addition, future versions v1 and later are allowed to break backward
compatibility for code using the v0 versions. Thus, developers must pay attention when
upgrading from v0.
Pre-release Version
This version has no stability guarantees. It signals a pre-release milestone, i.e. alpha or beta, for instance vx.x.x-beta.2.
Minor Version
This syntax is vx.2.x. The changes in this kind of version is backward compatible and stabile. The changes in this version may includes changes to the module's dependencies, or the addition of new functions, methods, struct fields, or types.
Patch Version
The syntax takes the form of vx.x.5. This version guarantees backward compatibility and stability. The changes in this version don't affect the module's functionality or its dependencies. An increment number is only for minor changes such as bug fixes.
Major Version
The syntax takes the form of v1.x.x. A version of v1 or above signals that the module is stable for use, however, it doesn't guarantee backward compatibility. The increment in this version number represents a significant disruption for the developers whose code uses function in the upgraded module. The disruption may include backward compatibility issues.
