Releasing a library¶
ContainerSSH is made up of over 30 libraries. These libraries are all written in Go and must, therefore, follow the Go modules specification. It's not the most exciting read, but you should familiarize yourself with the process. We will attempt to outline the most important steps here.
When heading up to a release versioning must be kept in mind. We follow SemVer, so only major versions may contain breaking changes. The only exception is versions before
1.0.0, these may break in minor versions too. This includes methods like factories (e.g.
With Go modules versions beyond version 1 should have the module suffix
v3, etc. For example, you may have a module called
Once the main branch is ready for release the last step is writing release notes. We do not follow the concept of simply listing the commits, we aim to write human-readable release notes that explain the changes. The explanation has to be detailed enough so anyone from the target audience can understand what is changing without needing to understand the implementation.
The release notes should be added to
Updating the README¶
Before creating a release the
README.md file should be updated such that consumers of the library know how to use the new version of the library. Except for a few libraries like auth and configuration our libraries are intended only for consumption in ContainerSSH. This means that you can write the documentation from that perspective.
Creating a release¶
The day has finally come: the release notes and codes are in, tests are passing. Now we need to create a release. We do this exclusively from the GitHub interface. We name versions for libraries in the format of
v1.2.3 so Go can pull them in, while applications are named
1.2.3 to avoid pulling them in from a Go program.
We copy the name and description from the
CHANGELOG.md into the release notes on GitHub. For applications the release mechanism will create and upload the binaries.