July 9, 2017
For most of my career I’ve chosen version numbers for software in a moderately arbitrary manner. I would typically have four numbers: major, minor, patch, and build. For some projects the build number would increase every time I compiled. I quickly found that colleagues were scared by the large numbers and I started hiding the build number. My choices for major, minor, and patch were somewhat arbitrary. If it was a big change I’d bump the major number. If it was a moderate change I’d bump the minor. For bug fixes or packaging changes I’d bump the patch number. The only real problem with this approach is that it is arbitrary.
Versioning software is not a new problem. I was recently pleased to find two related projects that take the guess work out of versioning and tracking changes.
The Semantic Versioning project is simple. There are 3 components to the version: major, minor, and patch.
- Major: increment for incompatible API changes
- Minor: increment for backwards compatible additions
- Patch: increment for backwards compatible bugfixes
The website adds some flowery language explaining it all in detail but the above is really all that is needed.
Keep a Changelog aims to have a standard changelog format and encourages the use of Semantic Versioning. It is based around markdown which makes it pretty when rendered, easy to edit, and easy to read even from a text editor. The basics of this are also simple:
- Name the file CHANGELOG.md
- Keep a section for unreleased changes
- Each section header should have the version, the date of the release, and sections for each of the categories listed below.
- For each release have a section that documents changes for the
following categories: added, changed, deprecated, removed, fixed,
and security.