The semantics of Go module versions

When you are developing Go modules (executables or libraries), at some point you will want to release them and make them available to others (whether internally or publicly). As your module improves over time, with bug fixes and new features, you will want to release new version of the software to share your work with your community of users.

Fortunately, instead of an arbitrary version label, Go has adopted a standard way of labeling module versions known as Semantic Versioning (or SemVer). Semantic versioning combines three different version numbers to communicate to users the type of changes their potential impact to the user community.

SemVer labels have a simple format where they start with the letter "v" followed by 3 dot-separated numbers as shown below:

vMAJOR.MINOR.PATCH        

The reason why it is called semantic versioning is because each number in the version label has a specific meaning.

• PATCH - ?this number increases after any break/fix, bugs, or backward-compatible changes that do not change functionality of the software
• MINOR - ?this number increases when there are (backward-compatible) functionality updates to the code. When this number increases, PATCH is reset to zero.
• MAJOR - this version number increases to indicate that there are possible backward-incompatible changes in the release. When this changes, it resets both MINOR and PATCH to zero.

Here are some examples of semantic version labels:

v0.1.0 
v0.1.2 
v0.6.0 
v1.0.0        

Unstable version semantics

Using semantic versioning, we can express that a given version is considered unstable. An unstable version is one that?makes no compatibility guarantees with previous versions.

Major version Zero?

When the MAJOR version number is zero (v0) it indicates that the module is still under initial development and may experience breaking changes. This means that v0.2.0 any other previous version v0 versions are not guaranteed to be API compatible. That being said, most project authors tend to honor that guarantee anyway even when using v0.

Examples of versions zero releases:

v0.1.0
v0.34.1        

Pre-released versions

The semantic label string can include a trailing text (appended after the PATCH). It is there for additional version context information. Specifically, it is used to provide information about a pre-released versions which may not be backward compatible with previous versions.

Example pre-released versions:

v0.5.0-beta
v1.0.0-rc1        

Why it matters

Semantic versioning offers several crucial benefits for both module developers and users:

• Clear Communication: It instantly tells users the nature of changes in a new version.
• Dependency Management: Go's tooling uses SemVer to automatically manage dependencies and ensure compatibility.
• Predictability: When you follow SemVer, users know what to expect during the evolution of the module updates.

Summary of versioning your modules

Here's a summarized list of how you should evolve your own module over time:

• v0.1.0: Initial release.
• v0.2.0: Added new features.
• v0.2.1: Fixed a bugs.
• v1.0.0: API is stable with guarantee to remain backward compatible for all of v1.x.x. family
• v1.1.0: Introduced new back-ward compatible features.

Beyond v1 - releasing the next major version

Increasing the MOJOR version from v1 -> v2 has major implications. You are indicating to your user base that your API has no guaranteed of backward compatibility. Beside the maintenance overhead (if you want to continue to support the v1 versions), user using v1.x.x family will be required change their import paths to pick up the new v2 versions.

Learn more

You can learn more about Go modules and how to use effectively use semantic versioning for your modules in LinkedIn course Programming with Go Modules.