Rules for incrementing patch number in semver

Question

According to semver

"PATCH version when you make backwards-compatible bug fixes."

and

"A bug fix is defined as an internal change that fixes incorrect behavior."

With this in mind lets say I have a variable that can be called, like a color. And for some reason I need to change the color value.

v1.0.0
$color: #FFF;

v1.0.1
$color: #F0F0F0;

Now this is a variable that is defined in the API as something users can call. I haven't changed the actual variable that is called, only the value it returns. To do this I have to make a change to my code, on an API element, and I must merge this code into the production branch. But does something like this truly warrant incrementing the patch version number of your API?

Answer 1

The point of semantic versioning is to manage dependencies of software systems. Semantic versioning provides an organized specification to standardize this process in order to reliably track the state of these systems. As the specification states,

Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

If your changes affect the behaviour of your api (inputs or outputs) and require a release to be made then that release should be pegged to an appropriate version number. This will allow the users of the package to depend on your package with confidence. Each version will behave as expected; there should be no ambiguity.

---

As an example, let's say you make the change and release it but don't increment the patch number. You could potentially have two users who think they are using the same code but get different values when calling the $color api depending on when they acquired v1.0.0.

It's worth noting that there are different ways to approach getting this change to users depending on how you release your package. I can think of two possible cases:

• If the package source is public, in early development of the package a quick change could be pushed to a development branch in which users could acquire changes at their own risk.
• Alternatively, if the package is not open source, a pre-release could be made by appending an identifier to the version (see items 9 & 10 in the spec).

These are just a couple options. There may be others depending on your specific situation.

TL;DR Answer

Most importantly is that once v1.0.0 has been released, v1.0.0 should always behave the same way. Regardless of how trivial these changes may be they are still changes. This goes for all versions, X.Y.Z.