When to update your semver version number

Anyone who is familiar with package versioning has used, or at the very least heard of, Semantic Versioning. For the uninitiated, semver is a three part version number in the format MAJOR.MINOR.PATCH ex) 1.13.2, and you can find very in-depth details on the semver website.

The semver website outlines the rules for incrementing version numbers as:

• MAJOR: When you make incompatible API changes.
• MINOR: When you add functionality in a backwards-compatible manner.
• PATCH: When you make backwards compatible bug fixes. At gophercon I had a discussion with another engineer about what these mean. When does a change make the API incompatible with a previous release? Take the following contrived example:

Your API typically returns a key/value pair for a requested field:

{ foo: ‘bar’ }

But now you decide to change the value returned by capitalizing the first character in the returned strings:

{ foo: ‘Bar’ }

What portion of the version should be updated with this change?

• MAJOR: It could break someones code who is relying on the case of the returned value.
• MINOR: This is adding functionality because the value being returned is actually a title for a story.
• PATCH: Stories should always have been capitalized so this is actually a bug fix. This shows that the rules are up for a lot of interpretation and will depend heavily on your situation. This unfortunately doesn’t make it easier to explain to someone who is new to, or skeptical of, semver. As a solution I came up with a slightly more specific set of rules which I think make the decision much easier for everyone.

Jeff’s semver incrementing version number rules:

I inverted the rule set so it can be read that any later rule overwrites the previous rule so the version section moves up a level.

• If this is fixing a reported bug in your system: PATCH
• If this is adding a feature to your public or private api: MINOR
• If this is a change to your private methods or data structures: MINOR
• If it broke your public api call tests: MAJOR Because your tests should test exactly what you expect your public API to return it should be very trivial to know when a change is breaking what others could be relying on.

What do you think of this approach? Do you find it any easier to understand? Do you have any other rules to add? Or are you already using semver and have a different approach to deciding when to increase which number? Comment below or mention me on twitter @fromanegg and let me know. Thanks for reading!