The article comes from a time curious about the change log of a fairly familiar extension is chat ++ . When looking at the change log in this repo, I find the versioning rules quite miscellaneous . For example being in 5.6.3 jumps to 5.7.0 but not to 5.6.4 . After a while of research and stupid question, I got a brother who gave keyword Semantic versioning to explain how to set the version for each release .

But before explaining the other “formula” for versioning, we will learn a bit about Semantic versioning see what they are? and solve what purpose.

1. How did semantic versioning come about?

The story is that one fine day, I need to retrieve information of A-star singers for the purpose of displaying on my website. Fortunately, after a while of searching, there is also a service, I temporarily call service X that provides an API that displays the entire list of information of these singers.

When information about this API, I can list a few notable components as follows:

• API URL: https: // xxx / list-singer
• METHOD: GET
• Response:

So in my code, just call the API and assign it to a variable named singers

That’s good, I’ve completed listing singers based on a public API. But after a while, on the website, I suddenly saw an error of name undefined . After a while debugging, I discovered the other API end had changed the format response returned.

So I just fixed the bug and wrote an email to curse the supplier, saying why did you change the reponse code leading to an error in my system. And given the provider that during operation, there was a client side that needed to provide additional status code and something else, so the dev team had to change the response.

Based on the above bogus story we can realize two problems about how to develop an API as follows.

1. On the client side, in particular, the developer has to depend on the API response leading to when the API changes, the client also changes. We try to imagine a service of ours that needs to call 100 vendors providing APIs, so it is the developer ‘s job to just eat and modify the code according to the API response.

This problem is called Dependency hell – Passively Dependency

2. On the vendor side that provides the API, they will have to be more careful in the process of changing the response, how even if there is an additional response – as in the above story status does not affect the logic of the client ‘s code. But it is difficult to chiều lòng all vendors so there are some API providers who choose to not improve the response any more, with the criterion: Nếu nó đang hoạt động, đừng sửa nó .

This issue is called version lock – No further development is possible.

To solve the above problem, the above developers thought of versioning for thay đổi . How to make each response change, here temporarily considered a release, they will provide a new version to ensure that will not affect the old version. For example, at the top of the post they are there

• API URL: https: // xxx / list-singer

Now after versioning for releases, the URL will change to v1 format

• API URL: https: // xxx / v1 / list-singer

When there is a change, there will be another version of v2 for example

• API URL: https: // xxx / v2 / list-singer In order not to affect API calls of old client but to be able to develop new versions.

Or when we install a package form

After the developer releases version 5.9.0 , it does not affect the currently used version.

2. Rules of versioning

In the previous section, we talked about the need for version but there is no specific rule. Without rules there are a few minor problems, for example when, during the maintain, some minor logic fixes that do not affect the old logic need to be versioned.

The first versioning rule was created by Tom Preston-Werner , who is also the inventor of Gravatar and co-owner of GitHub .

This rule is based on 3 main numbers MAJOR , MINOR , PATCH . It corresponds to 3 numbers in defining the version of an API or a package.

To explain the above 3 keywords we go into the following specific example.

• For the first version /v1/users/:id , we write an api that returns the following data:

• Then we need to add some information about the age, for example, we update it to.

=> This new api only adds the “age” field, and the 2 old schools are still compatible with the previous one, so this is called MINOR change , something that doesn’t affect the old active part. And as such, the api version remains v1.

Then, we realize that returning string age is an error, and we correct it to a number. => This new api just fixes the data type, fixes a small error, doesn’t add anything new and is still compatible with the previous version, so it is called PATCH (patch). And so the api version remains v1.

At some point, we find that our api needs to return more information than just the user information.

=> This new api is completely different from v1 running, if we fix the code, the calling parts will be okay. So we have to write a new api labeled / v2 / users /: id. This is MAJOR or breaking change , the change is not compatible with the old version.

So in short

• MAJOR : Represents a major change, not compatible with the old version.
• PATCH : Representing small changes, still compatible with the old version, often changes will be some update . It makes me refer to PUT , PATCH in Http request methods .
• MINOR : Represent for small changes, still compatible with the old version, it will be different from PATCH that instead of update something will create something.

Based on the above explanation, we can completely rely on the circumstances of each different release to decide to increase the MAJOR , PATCH or MINOR .

3. Some notes on using Semantic versioning

Some note of versioning is defined in semver . I ask for permission to translate again.

1. Software using Semantic versioning(semver) must be a public API . However, with the internal api I think you should also version to deploy zero time if you build BE and FE in 2 separate repos. This is also a bit long. So if you want to learn more, please comment below me to explain.
2. A correctly defined version must include 3 XYZ numbers corresponding to MAJOR , PATCH , and MINOR . Each element must increment 1.9.0 -> 1.10.0 -> 1.11.0 . From now on when calling X, Y, Z, they are mistakenly understood as the numbers above. These numbers should be positive integers with no leading zeros.

3. When a package has been released. Not allowed to change content in that version , but must release in another version . Although the change is the smallest.
4. Major version zero(0.yz) is for development. This is not considered a stable release for use.
5. Version 1.0.0 defined for the first release . The decision that X, Y, Z will increase in subsequent releases depends on different circumstances.
6. Patch version Z (xyZ | x > 0) must be incremented for each fix. I have mentioned this above.
7. Minor version Y (xYz | x > 0) must be incremented if there is something new, which is compatible with the old version. It must also be increased if some functionality in the API is not used. It can be incremented if there is an improvement in the code. Patch version must reset to 0 if Minor version increases.
8. Major version X (Xyz | X > 0) must be incremented if there is a major change, not compatible with the old version. It may include alterations of Y, Z Patch and minor must be reset to 0 if X is incremented.
9. pre-release can be further represented by adding a hyphen (-) to the ASCII . The pre-release signifies that this is not a complete version . For example 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-xyz.–. .
10. The priority of software using semver is defined as follows

• The priority depends on the magnitude of X, Y, Z from left to right. Example 1.0.0 <2.0.0 <2.1.0 <2.1.1
• Priority of version release takes precedence over pre-release version. Example 1.0.0-alpha < 1.0.0
• Priority of pre-release versions is also evaluated from left to right, numbers with numbers, letters and letters. For example 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

4. Summary

Above I have introduced to you why to type version for each release and use Semantic versioning . Once we have understanding of version we will avoid making mistakes in the release times. Evaluate whether changes affect logic or not.

Semantic also not the principle of typing the only version, in addition it also has a full number type, including 4 more parts: Major.Minor.Revision.Build . You can learn more.

Based on the knowledge of the article, we also partly explain why chat++ in 5.6.3 jumps to 5.7.0 but not to 5.6.4 , right.

Thank you for watching the article, if the article is useful, you press upvote to support me and follow to receive notification every time I have a new article.

5. References

My posts include the research and comments of the members of Avengers Group to make the article more complete. Also referenced from the official Semantic Versioning documentation . You probably should read that more.