Building and distributing a golang module is relatively easy. You need to create a GitHub repository and push your code. That's all, isn't it?

Not really. An adequately distributed module needs to be tagged and versioned so people can trust your module for production usage.

How do you decide when or how to bump your package version?

Luckily, you don't need to reinvent the wheel. Most packages inside and outside the golang community follow SemVer. TL;DR:

1. You have three numbers divided by a dot (.) -> 1.2.5
2. For changes that break the existing API, you change the first number
3. For changes that add new capabilities but don't affect existing ones, you change the second
4. For changes that fix existing behavior because of a bug, you change the third.

There are minor trade-offs and personal tastes that might change the practical application. Still, the core concepts are as simple as that 4 points, and with that foundation, the semantic-release package was created.

Commit Convention

Using a proper commit convention is crucial for versioning and keeping an up-to-date change log easily. I have been using Convetional Commit for a few years. From my point of view, it is the easiest to adopt and manage with a great return on investment.

Check, how clean and clear the semantic-release git history feels.

Tag and release

Suppose you are using Convetional Commit, and you want proper semantic versioning. In that case, the best choice is the semantic release package.

At first sight, you might find it strange because the tool is written in JS, designed for the nodejs environment. Still, you can abstract those implementation details using GitHub and GitHub action.

Semantic Version with golang

The package will create a release and a tag on the GitHub repository. You can check an example on my go-again repository

You need both the GitHub Action configuration and the .releaserc file.

name: Release
on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@master
      - name: Release
        uses: codfish/semantic-release-action@v2.0.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

And the .releaserc

branches:
  - name: "main"

plugins:
  - "@semantic-release/commit-analyzer"
  - "@semantic-release/release-notes-generator"
  - "@semantic-release/GitHub"

Every time you merge or push a commit to the repository, you will get a new version following the conventional commit to semantic versioning:

• fix: --> patch
• feat --> minor
• BREAKING CHANGES -> Major

The translation for commit type to semantic versioning bump is configurable using the commit-analyzer package