Semantic Versioning: A Quick Guide

In the field of software and application development, version numbers are used to track releases. If this needs to be done, it must be done in a standardized and consistent manner to prevent conflicts.

Semantic Versioning

Semantic versioning is a method of versioning software, software packages, or libraries in a logical manner. This versioning is done by assigning a version number (a decimal number) to the so-called software. With the presence of two decimal points, a version number can be further divided into three: a major version number, a minor version number, and a patch version number, respectively.

Major Version
This version number is updated (incremented) whenever an API or piece of software receives updates that render the prior version obsolete. Things won't function the same way they did before when there is a significant change, which can also lead to incompatibilities.

A software or API user can get ready for glaring changes in terms of software and breaking changes in terms of APIs with a conspicuous change in a major version number.

Consider this simple program;

Obsolete API:

class Family{

    constructor(name, age){
        this.name = name;
        this.age = age
    }

    printFamily(){
       console.log(this);
    };


}

const david = new Family('David Ipadeola', 11);
david.printFamily() //prints: Family { name: 'David Ipadeola', age: 11 }

Updated API:

This Updated API has significant changes. Here, Family is now FamilyMember and Family.printFamily()is now FamilyMember.printFamilyMemberDetails(). Applications already using the old API will see breaking changes as a result of this substantial update.

class FamilyMember{

    constructor(name, age){
        this.name = name;
        this.age = age
    }

    printFamilyMemberDetails(){
       console.log(this);
    };

}

const david = new FamilyMember('David Ipadeola', 11);
david.printFamilyMemberDetails() //prints; FamilyMember { name: 'David Ipadeola', age: 11 }

Minor Version

The reason for changing (incrementing) this version number is almost identical to that of the major version. With minor modifications to an API or software, things won’t function the way they did before, but this is not a breaking change; rather, it is an addition of functionality to the existing API or software.

Consider this program;

This version of the API doesn’t have a method to update FamilyMember details/properties (name & age).

class FamilyMember{
    constructor(name, age){
        this.name = name;
        this.age = age;
    }

    printFamilyMemberDetails(){
        console.log(this)
    };

}

const david = new FamilyMember('David Ipadeola', 11);

david.printFamilyMemberDetails(); //prints; FamilyMember { name: 'David Ipadeola', age: 11 }

Here’s the updated API:

With this version of the API, FamilyMember now has a method that can be used to update its details/properties (name & age). Since this is an added functionality to the existing API, we can change the API’s version number by increasing the minor version number.

class FamilyMember{

    constructor(name, age){
        this.name = name;
        this.age = age;
    }

    printFamilyMemberDetails(){
        console.log(this)
    };

    updateFamilyMemberDetails(name, age){
        this.name = name || 'empty';
        this.age = age || 'empty';
    }


}

const david = new FamilyMember('David Ipadeola', 11);

david.printFamilyMemberDetails(); //prints; FamilyMember { name: 'David Ipadeola', age: 11 }

david.updateFamilyMemberDetails('Kolawole Ipadeola', 12);

david.printFamilyMemberDetails(); //prints; FamilyMember { name: 'Kolawole Ipadeola', age: 12 }

Patch Version

In order to improve APIs or software, we fix bugs, correct programming errors, and make other adjustments. The patch version should be changed at this point if possible.

Consider this program;

With this version of the API, the FamilyMember.printFamilyMemberDetails() prints the FamilyMember object. We can consider this to be a programmer error, if what is supposed to be printed is a String literal.

class FamilyMember{

    constructor(name, age){
        this.name = name;
        this.age = age;
    }

    printFamilyMemberDetails(){
        console.log(this) //needs a fix.
    };

    updateFamilyMemberDetails(name, age){
        this.name = name || 'empty';
        this.age = age || 'empty';
    }


}

const david = new FamilyMember('David Ipadeola', 11);

david.printFamilyMemberDetails(); //prints; FamilyMember { name: 'David Ipadeola', age: 11 }

Here’s the Updated API:

With this version of the API, the FamilyMember.printFamilyMemberDetails() prints a string literal containing FamilyMember details/properties (name & age).

class FamilyMember{

    constructor(name, age){
        this.name = name;
        this.age = age;
    }

    printFamilyMemberDetails(){
        //console.log(this) 
        console.log(`Hello, my name is ${this.name}, I'm ${this.age} years old.`); //corrected programmer error by printing a string.
    };

    updateFamilyMemberDetails(name, age){
        this.name = name || 'empty';
        this.age = age || 'empty';
    }


}

const david = new FamilyMember('David Ipadeola', 11);

david.printFamilyMemberDetails(); //prints; Hello, my name is David Ipadeola, I'm 11 years old.