Is there a more controversial topic in the software world than semantic versioning? It seems there are two camps: those who believe in it and those who think it’s stupid. I fall into the first camp since I believe that the entire web will be Semantic one day.
When done right, semantic versioning makes it clear what has changed between versions, avoids versioning conflicts, and ensures that code remains backward compatible.
It is difficult to know what has changed between versions if you do not use semantic versioning. This methodology encourages you to write backward compatible code, will be be a big help for anyone whose trying to maintain code over time. It also makes it much easier for consumers of your code to understand what has changed between versions, and to know which versions are compatible with each other.
To keep track of which functionality exists in a software component, we label components with a version. The version is often documented with release notes, which describe what has changed and the impacts incurred for an upgrade. Release notes are great but are cumbersome to read and refer back to.
Semantic Versioning
Semantic versioning (aka semver) is a simple convention of labeling versions that communicates the kind of changes that have been made since the last version. The goal is to make it easy for everyone to understand the consequences of upgrading to a new version. To that end, the label for a new version has three parts: major, minor, and patch which describe whether major, minor, or patch changes have been made.
Most of the time, it is okay to pull in minor and patch updates automatically but this versioning format gives us the information we need to make that decision for ourselves.
About the spec
The semver specification is not complicated. It is just a single page. The basic idea is to use a version number in the format MAJOR.MINOR.PATCH. The order matters. Major goes at the front.
Increment the MAJOR version to indicate a breaking change exists. A new MINOR version indicates a backwards-compatible change and a new PATCH version indicates a non-breaking, backwards-compatible change.
This is a simple idea, but it has a profound effect on the way software is built and released. By adhering to the semver specification, you can:
- Build software from small, incremental changes.
- Release new versions frequently and automatically.
- Communicate changes clearly to users.
When you use semver, you’re forced to think about the consequences of every change you make. You have to decide whether it’s a major change that will break existing code, a minor change that adds new functionality, or a patch change that fixes a bug or improve performance.
Will it work for me?
This may seem like a lot of work, but it’s actually a very efficient way to build software. By making small, incremental changes, you can avoid the need for major refactors down the road. And by releasing new versions frequently, you can get feedback from users early and often.
You can also include an optional pre-release version identifier at the end of the version string. This is useful for beta releases and other development versions that are not yet ready for production use.
The semver specification is flexible enough to accommodate a wide range of development styles. You can release new versions as often as you like, and you can make as many changes as you want in each version.
Best Practices for semver
Following these best practices will help you avoid confusion and frustration when using semver.
- Don’t make breaking changes in minor versions.
- Don’t make breaking changes in patch versions unless absolutely necessary.
- Increment the major version number if you make breaking changes.
Reburn Report 
Leave a comment