¿What is semantic versioning?

Semantic versioning is a standard to define a version for a public API or a library in the open-source software world.

When we are creating software we need a way to know if the last version of a tool is an absolute change in the behavior or if it is only fixing some minor issues. In other words, we need to a way to communicate to our users the type of change and the scope of the last version published.

¿How to use versioning?

It consists of 3 non-negative integer numbers separated by dots.

1.2.8 // major.minor.patch

If we read them from left to right, the first number (1) is called “major”, the second one (2) is “minor” and the last one (8) is “patch”.

These number are increased by 1 every time an API or library suffers changes that are published. Let’s go into more detail, ¿what do they mean? and ¿when and how should we use them?

Patch

The third number (left to right), must be incremented if compatible fixes were introduced.

1.2.1 // current version with errors
1.2.2 // new compatible version with errors solved

Minor

The number in the middle is going to increment when:

• Compatible errors were fixed.
• Compatible improvements.
• Non-crucial new features were added.

Even if the version was updated, every change will be compatible with the previous versions. If the minor version is incremented, the minor number must be reset.

1.2.4 // previous version
1.3.0 // new compatible version

Major

Indicates that the library has changed and might generate errors for the people using it. The changes might include:

• Error fixing or improvements.
• New features.

It might include minor and patch changes. Minor and patch must be reset if the major version is incremented.

1.3.4 // previous version
2.0.0 // new version

Tags and pre-release

They are used with a hyphen and a tag immediately after the patch version. They indicate that the version is not ready to be released in a stable environment.

1. Alpha

1.0.0-alpha.1

This is an unstable version that probably includes several errors, but first we want to be test it in order to find possible issues and verify every feature.

2. Beta

1.0.0-beta.3

It is more stable than Alpha and the software is ready, but in this case we are going to execute performance tests, usability and probably some modules to make sure that it works well in non-controlled environments.

3. Pre-release

1.0.0-rc.8

The next step is going to be “RC”, release candidate. This is going to be the last step for the software to be released to production.

Real example of the entire flow

Let’s imagine you have a stable application with version 1.4.6, you decided that is time to develop the new version, number 2.The first changes and features are going to be in the version 2.0.0, but since you are still starting and testing things, you might add an identifier that tell other people the current situation of your application. So your version is going to look like 2.0.0-alpha.1, and by doing so people will know it is an “alpha” version and it is not considered very stable.

1.4.6         // stable version
2.0.0-alpha.1 // develop version

As the develop process advances, you will get a beta version that is going to look like 2.0.0-beta.3 (some teams go directly to release candidate). You will continue in that way until everything is ready to be released like 2.0.0-rc.7.

1.4.6         // stable version
2.0.0-alpha.1 // develop version
2.0.0-rc.1    // release candidate version

Once you complete the release candidate you can publish your API or library incrementing the version to 2.0.0 (Every tag must be removed, also we must reset the minor and patch).

Important: First version

The first version of a public API or library must start with 0.1.0 and when it goes on production must be 1.0.0

¿How to include an API or library?

When we use versioning or we want to include any library into our projects we can do it in different ways:

• Exact version: It will get a specific version of an API or library and it will be updated only if we change it manually.
• Major version: It is represented with ”>”, it will get the latest version. It increments the major, minor and patch versions available (normally generates errors).
• Minor version: It is represented with “^” and it updates the last compatible changes. Minor and patch might be updated.
• Patch version: It is represented with “~” and it updates the last minor change available. Also compatible with the current version.

For instance:

"some-library": "5.21.7"   // exact version
"some-library": ">5.21.7"  // every new available version
"some-library": "^5.21.8"  // every new compatible version
"some-library": "~5.21.8"  // every minor version available