When we exploring projects on GitHub, many times you can find the version number of artifacts like 0.9 or similar to that. Also very popular Frameworks like Spring mark their Artifacts with a label for example 5.1.2.Release. Sometimes appearing patterns like 3.0.0-alpha or 3.0.0-beta. Of course you can choose every pattern you like, to mark a special status of your application or library. But if you think twice about it, you may will realize this is not a recommendable practice.
By personal experience, I would always recommend to follow the semantic versioning (https://semver.org) approach. Semantic Versioning is an unofficial standard and with his short rule set easy to learn and use. But before I explain all the benefits you will win with this way of setting your version numbers, let me show how easy it works.
• Major: incompatible API changes
• Minor: add/ update functionality
• Patch: BugFixes
• Label: SNAPSHOT – to mark the under development status
With this simple overview, you already have everything you need to start with semantic versioning. Let’s have a bit deeper insight to these points and for what they stands for in the context of source code.
I. An incompatible API change means that a method you already have in your code base is removed or the signature is changed. In those cases the MAJOR part of the version number have to increase.
II. As long only new classes or methods are added, we did not infect to the usage of the previous work. This scenarios usually describe adding new functionality. In this context we increment the MINOR version number.
III. At least, when a bug is fixed we need to deliver the corrections in an own release and we have to increment the PATCH level. This changes don’t include feature updates or something other than the correction.
IV. During the implementation the version number is labeled with SNAPSHOT.
This simple rule set allows you an easy setup of you git branches, because in general you work in the master or develop branch. Only in the case of a fix for an already deployed release, we go back to the revision is marked with the release tag and create a bug fix branch. In this branch we only perform the fix and prepare a new release after everything is well. In this point you don’t effect any other work, because you are isolated. You can not bring in that way by accident new and untested functionality to the correction. After the correction is done, easily you can merge the bug fix branch to the master without having any conflict.
In my perception a version number less than 1.0 or labels like alpha suggest an incomplete or not well developed artifact. As consequence I try to avoid the usage of such marked releases. When I start with a new project I always start with 1.0-SNAPSHOT as first version number. Only when the minimal functionality is implemented, that the artifact is usable, then and only then I prepare the first release 1.0 and publish the binary. If after that an heavy bug is detected I perform a correction and publish the fixed artifact under 1.0.1 version number. In between I work on version 1.1-SNAPSHOT till I have the new functionality in a status is working well.
Always when I see a new major release of a library I use, I check as first if there some incompatibilities to my project. Then I can decide if I want to update my project to this newer version. Sometimes its to much work and you need to shift an update to a time when you have enough resources to do the migration well. Not every Major release brings feal benefits to your own project. The idea of “Always latest is greatest.” is not that good advice like it sometimes seems.
Top comments (0)