DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

Cover image for 4 Important Rules of Semantic Versioning
Tirth Patel
Tirth Patel

Posted on • Updated on

4 Important Rules of Semantic Versioning

There are many things which a wise developer takes cares of. One of them is Semantic Versioning.

Before jumping onto Semantic versioning, let's consider one example:

Suppose you are developing an app named Building 🏒. While building this app, you need to integrate a third-party package called Crane πŸ—οΈ. When you installed Crane in your Building app, its version was 2.1.0. After some time you need one more package named Truck 🚚, which was having 1.1.4 version. Among these 2 packages; Crane was not following the standards of Semantic Versioning. And package Truck was appropriately following the rules of semantic versioning.

Let's pause this example here for a while and understand what is semantic versioning. At the end of article, we'll continue this example and see how Crane and Truck's releases will affect your Building app.


WHAT? βš™οΈ

Semantic Versioning is also called as SemVer for short notation. It is a standardized pattern to mark versions of any app, package, library, API, or any other product wherever it is applicable. (In the further article SemVer stands for Semantic Versioning)

MAJOR.MINOR.PATCH
Enter fullscreen mode Exit fullscreen mode

Sample SemVer(s)

- 2.4.0 (Major: 2, Minor: 4, Patch: 0)
- 4.6.2 (Major: 4, Minor: 6, Patch: 2)
Enter fullscreen mode Exit fullscreen mode

Semantic Version consists of mainly 3 parts (it may be more depending on how many levels deep you want to take it)

MAJOR: It represents the major version of the app. Any incompatible change, API modification, or such changes are handled under this number.

MINOR: When you add new functionality in a backward compatible manner is introduced in the product. Any improvement (like performance, optimization, etc) can be covered under this.

PATCH: As the name suggests it is reserved for bug fixes internal to the system/product. Note that these bug fixes should be backward compatible.


WHY? πŸ“’

  • Reduce dependency hell: Suppose in an app, you have 15 dependencies of third-party packages. If those 15 packages don't follow the proper practices of SemVer then you will not know which package to update and what impact it will make on the app. At a point, you will end up in dependency hell where you will have to wait for third-party packages to update their versions in order to release your app. Practices rules of SemVer we can easily and efficiently do dependency management.
  • Following standards for release planning and deployments: Any release's stability and lifespan can be judged by its SemVer. For CI/CD pipelines also appropriate versioning plays a vital role.

RULES πŸ“

There are some standard practices that should be followed while using Semantic Versioning.

  1. MAJOR, MINOR, PATCH must be whole numbers (0,1,2...). These should not include negative integers or decimal points.
  2. Once version details are published for any app, they should not be altered. Version values can only be changed as a new release.
  3. Comparing 2 SemVer must be from left to right based on the increasing value of the number. Ex : 1.0.0 < 1.1.0 < 2.0.0 < 2.0.1
  4. Major version 0 (0.x.y) is for the development phase. During this, the app must not be considered stable.

(For more details visit semver.org)


Completing our Building App 🏒

  • Let's wind up our article by completing the example. We're building an app named Building. And among that; Crane was not following SemVer. The truck was following.
  • When you plan the release of the Building app at that time πŸ—οΈ Crane's version -> 2.1.3 & 🚚 Truck's version -> 1.2.2. By this, we can predict that for Crane -> till version 2.x.y & Truck -> till version -> 1.p.q we can publish our app and there will be no breaking changes.
  • But this surety can only be assured by a package Truck and not from Crane. The reason is Crane is not following SemVer standards. So in the next release Crane -> version 2.1.5 they might introduce some breaking changes of which we're unaware.
  • If we're using more ill-planned packages like Crane, this can lead to dependency hell and end up in an issue for App. So be cautious to choose packages...

What about Practical β“πŸ€”

  • Too much technical jargons so far... πŸ˜…. Only theory can't be sufficient. We'll look into the practical application of SemVer by developing a Node-based MunchPay API. Where we'll check each aspect of versioning and deploying.
  • Stay tuned for the continued series article: Semantic Versioning in MunchPay Node API for practical exposure.

Closing comments πŸ™‹β€β™‚οΈ

  • Thank you for reading along with me. If you find any queries on the above-mentioned topic, please ping in the comments.
  • Knowledge spreads by sharing. So please share this article with concerned friends.
  • PS : Also, I humbly request you to write which topic you want in my next blog. I will include that in my target list. 🎯



Tirth Patel, signing off! 🫑

Top comments (0)

Does documenting APIs bring you joy?

πŸ“„ Help Forem tackle our remaining open v1 API documentation issues! πŸ₯°