Managing a public Go module

Aug 16, 2026

A simple guide on how to publish a Go module and manage it over time.

Preparation

mkdir module
cd module

... initialize git and connect to GitHub.

go mod init github.com/yourname/module

touch module.go

And feel free to write some code.

For best practice, don't forget to also add a LICENSE file.

Beta stage

git add .
git commit -m "beta release"
git tag v0.1.0
git push origin master v0.1.0

Documentation: https://pkg.go.dev/github.com/yourname/module@v0.1.0

Installation: go get github.com/yourname/module@v0.1.0

Import: github.com/yourname/module

Always follow Semantic Versioning.

Release

Release it when you're sure that your code is stable for the wild.

git add .
git commit -m "Release v1.0.0"
git tag v1.0.0
git push origin master v1.0.0

Documentation: https://pkg.go.dev/github.com/yourname/module

Installation: go get github.com/yourname/module@v1.0.0

Import: github.com/yourname/module

New major releases

Create them for all breaking changes.

The previous major version should stay in a separate branch to allow releasing patches. So before making new changes, save the current code in a new branch:

git checkout master
git checkout -b v1
git push origin v1

Now you are ready for a major change:

git checkout master

Update module path in go.mod:

module github.com/yourname/module/v2

Update internal imports (if any):

// Change from:
import "github.com/yourname/module/subpackage"
// To:
import "github.com/yourname/module/v2/subpackage"

... make your changes.

git add .
git commit -m "Release v2.0.0"
git tag v2.0.0
git push origin master v2.0.0

Documentation: https://pkg.go.dev/github.com/yourname/module/v2

Installation: go get github.com/yourname/module/v2@v2.0.0

Import: github.com/yourname/module/v2

Example

You can see an example of a simple module that has gone through this life cycle here: https://github.com/cheatsnake/module

Corresponding links to go pkg: