When to increment the version using Semantic Versioning?

Asked

Viewed 1,008 times

29

When using Semantic Versioning we define different versions in the X.Y.Z format being X, Y, Z nonnegative integers. Thus, given an X.Y.Z version:

  • We increment X if a modification incompatible with the current version is made
  • We increment Y if a new functionality compatible with the current API is added
  • Increment Z if a bug fix compatible with the current API is performed

In the third case it is very easy to know when to increment. We have a bug, we fix it without breaking the API and then we should increment.

In the first two cases it seems to be more complicated. In the second case for example, a new functionality may be a simple addition of a method in a class, as to the creation of several new classes that together allow to satisfy a given requirement.

In the first case there is also this. A modification can affect a single line of code or multiple files.

Thus, in these first two cases, as we know the amount of modification that really makes sense to increase the version?

1 answer

20


We don’t know. Deep down, until someone presents me with a reliable study that shows otherwise, this is more or less arbitrary.

You must be referring to the concept described in website "officer" on the subject. There are some rules but it’s all very generic, as it should be.

Bug

You set well how to proceed in the third case. But remember that a correction of bug can break the API. Some people might say that if the bug was so serious that it breaks the API so it’s an improvement. It may be, but I don’t know how far this discussion goes, and how relevant it is.

What I realize is that many projects where the community has a voice are wasted more time discussing which version should increase than improving code :P

Greater X Minor

Inheritance

I do not know if it is so difficult to identify the difference between the first and second cases. Creating a new class usually does not create incompatibilities. Creating a new method usually does not create either. Although it can create problems in some cases.

When you create a new method in a class that is normally inherited it potentially creates incompatibilities. This is not a best practice, so it might count as a modification that generates incompatibility and would fall in the first case.

I have no experience with the subject and I don’t really like these formalisms when they don’t solve real problems. In many cases formal documents cannot solve anything. That being said, even if the document does not specify anything I would adopt this policy of changing the larger version whenever you introduce a potentially incompatible change. Unless it was documented that this method could be created in the future and that no one could create a method with the same name/signing.

If you are providing an API that can be inherited this danger exists. If there is no inheritance possibility or if your application does not provide a public API that can be accessed programmatically directly, the risk does not exist. So people say to use inheritance as a last resort.

You may be wondering why the creation of a method can be compatible if there is no inheritance, and be incompatible if there is one. Inheritance is a bad idea that should be used very carefully in the rare cases where it really is very beneficial. One of the reasons for this is precisely because you have no control over how your class will be consumed. If someone creates a method called B() in the daughter class, the mother class can never create this method without breaking compatibility since probably this B() does not do what is expected of him according to the new contract in the mother class.

Inheritance is so complicated that some programmers prefer to create a new class than a new method when they need to improve an existing class. So the change that would be incompatible becomes compatible. But it creates two classes to maintain and for people to choose and use.

Implementation

A change to the implementation, even if it keeps the API shell compatible, may make a major version change necessary. Technically if you can continue using the API in the same way but the result may be different, you have an incompatible change. Although, technically, you shouldn’t change API results without changing it officially (documenting this). Some will say that the API has been modified in this case, debatable, but may be.

Perhaps the worst thing to do would be to make something incompatible without making it clear that it’s incompatible.

Therefore I find it more difficult to know if you are in the first or third case. A simple correction of bug may inadvertently render the API incompatible, even if it is not the intention. Consistent testing will help in this. But who consistently tests consistent tests?

Obsolescence

I think it’s pretty obvious that stripping functionality makes change incompatible, right?

Completion

That is, it is not the amount of modification that will define which version to change but the quality of it. A single modified comma can bring an incompatibility and thousands of new lines can only fix one bug or make an improvement on the implementation (change the complexity from O(n) to O(log n), for example) and everything continues to work the same.

One of the reasons for creating this specification is to decrease the number of incompatible changes and increase planning. In the ideal world the version should never go beyond 1.y.z.

Apart from these remarks and following what the document on semantic versioning says, I think any decision is subjective, even if it tries to use objective criteria. The document itself speaks in common sense. There are people who have, there are people who don’t, and I don’t know if this can be taught.

This may be the case but in most real cases programmers do not produce accessible Apis and the formally defined semantic version will hardly bring much advantage. In fact the first item of the document requires that there is an API to use the term formally.

Browser other questions tagged

You are not signed in. Login or sign up in order to post.