Managing the versions of your module

Go tooling uses the semantic versioning system. This means that the version numbers are of the X.Y.z form, broken down as follows:

• X is incremented for major releases that are not necessarily backward compatible.
• Y is incremented for minor releases that are incremental but backward-compatible
• z is incremented for backward-compatible patches

You can learn more about semantic versioning at https://semver.org.

How to do it...

• To publish a patch or minor version, tag the branch containing your changes with the new version number:

  $ git tag v1.0.0
  $ git push origin v1.0.0

• If you want to publish a new release that has an incompatible API with the previous releases, you should increment the major versions of that module. To release a new major version of your module, use a new branch:

  $ git checkout -b v2

  Then, change your module name in go.mod to end with /v2, and update all references in the source tree to use the /v2 version of the module.

For example, let’s say you released the first version of the webform module, v1.0.0. Then, you decided you would like to add new API endpoints. This would not be a breaking change, so you simply increment the minor version number – v1.1.0. But then it turns out some of the APIs you added were causing problems, so you removed them. Now, that is a breaking change, so you should publish v2.0.0 with it. How can you do that?

The answer is, you use a new branch in the version control system. Create the v2 branch:

$ git checkout -b v2

Then, change go.mod to reflect the new version:

module github.com/PacktPublishing/Go-Recipes-for-Developers/chapter1/webform/v2
go 1.22.1
require (
  ...
)

If there are multiple packages in the module, you have to update the source tree so that any references to packages within that module also use the v2 version.

Commit and push the new branch:

$ git add go.mod
$ git commit -m "New version"
$ git push origin v2

To use the new version, you now have to import the v2 version of the packages:

import "github.com/PacktPublishing/Go-Recipes-for-Developers/chapter1/webform/v2/pkg/commentdb"