It was introduced in 2009 by Tom Preston-Werner, co-founder of a GitHub. It was designed to provide a clear and universal way to mark software updates. There was a convention, which was almost the same as semver. But the word almost is not good enough, when you want to know what exactly the impact of changes is.

Semantic versioning is a convention, how to set versions to your code artifacts. It is called semantic, because it communicates the changes in the version, comparing to the previous version. Managing code dependency versions can become challenging if you are not aware of changes present in new version of artifact.

- Imagine you have 100 dependencies. How to know what dependencies can I update? Reading the release notes will be time consuming for the 100 dependencies.

- What if you need bug or security fix. Does new release contains only this bug fix or something else that can break an API?

- What if I need this new feature, but also I do not want to migrate?

- Is this version stable?

- How to add canary version build metadata into version?

All of these questions together with many others can be answered just looking at the version. SemVer has an answer to all these questions. The convention is very simple:

- X.Y.Z are the mandatory parts of version, where each letter i a numerical value

- X - called major version, updating it means that breaking changes are present in the API

- Y - called minor version, updating it means that new feature is added to the API

- Z - called patch version, updating it means that no API changes are done, only bug/security/performance fixes

- "+" indicates the build metadata (1.2.3+20240417)

- "-" indicates the prerelease version (1.2.3-canary.1)

## **Who is using SemVer?**

- SemVer is enforced in the npm(Node Package Manager) repository. Your version myst syntactically comply with the SemVer rules. It is central part of managing versions in the JavaScript world. Though you cannot automate the validation of breaking changes npm repository. This is the [recommendation of npm ath their page](https://docs.npmjs.com/about-semantic-versioning).

- RubyGems, package manager for ruby libraries is also a broadly adopted convention of managing artifact versions. The official documentation [describes semver as a pattern](https://guides.rubygems.org/patterns/) you should name your version.

- Docker Hub, repository for Docker images does nor fully support SemVer, though the community want to adopt the semver. The "+" symbol is not supported in the Docker Hub and maintainer is not willing to add support for it. This is the [GitHub issue maintainers comment](https://github.com/distribution/distribution/pull/1202#issuecomment-160761964), on the SemVer and "+" build metadata in the tag.

- Go is also embracing SemVer for its packages and [describes how to do it](https://go.dev/doc/modules/version-numbers).

Semantic Versioning solves multiple problems in the dependency management area. It is widely adopted, because it is easy to use and the version communicates changes being made. For some software projects this is go-to versioning strategy. Lots of tooling supports semver to manage package releases. It helps to remove version-lock problem, when you need to release a package, because your dependency changed and you do not know the impact of changes. Sem

## **Other versioning systems**

Though this versioning system is not the only one. There is also:

- Calendar Versioning (CalVer), it includes year, month and possibly day when it was released (2024.01, 2024.02).

- Sequential versioning - version-1, version-2...

- Release Train Model - where you have planned release schedule and you are naming the release artifact version based on a release number, rather than on a feature completion or changes in the software. Version name can combine CalVer, Sequential versioning or other versioning models (24.1, 24.2).

There are more versioning systems used in the software world. You need to chose the right tool for the job. And in many cases the semver is a right tool.

Semantic Versioning (SemVer)

Breaking changes is a result of a code changes, that how the API behaves. It can be low level code API, REST API, any microservice API or even user interface behavior.

Breaking changes can be of two types: structural and semantic.

## **Structural Breaking Changes**

Structural changes appears when the structure (contract) of an API changed. Changes can be in any code structural element. This is the list of structural breaking changes groups:

- remove parameter

- add parameter

- change parameter type

- change return type

- add required constructor

- make attribute required

- add type required restriction (also called generic)

Let's explore a **`lodash`** popular utils library in JavaScript ecosystem. In a [changelog](https://github.com/lodash/lodash/wiki/Changelog) we can find breaking changes in a version 3.0.0. When semver major version changes, it indicates, that API contains breaking changes.

```javascript
var wrapped = _([1, 2, 3]);

// in 2.4.1
wrapped.forEach(function(n) { console.log(n); });
// ➜ logs each value from left to right and returns the lodash wrapper

// in 3.0.0
wrapped.forEach(function(n) { console.log(n); });
// ➜ returns the lodash wrapper without logging until `value` is called
wrapped.forEach(function(n) { console.log(n); }).value();
// ➜ logs each value from left to right and returns the array
```

This example depicts the structural breaking changes, where the return type of function changed. In version 2.x this function was calling **`forEach`** eagerly. In version 3.x **`lodash`** made this function lazy, and returns wrapper instead of **`void`**.

## **Semantic Breaking Changes**

Semantic changes appears when output or side effect of API changed/added/removed. This is the list of semantic breaking changes groups:

- adding/removing/changing sorting return type. Consumer may rely on the way array is sorted or not sorted in the return of API.

- evaluation side effect. Chat GPT stores and "remembers" history by a chat id. Breaking change may appear if the storing algorithm is changed or how the history is red.

- additional constraints/validation on input

- adding/changing/removing implicit modification logic. As an example: submit the form and some default values are applied. Changes in the implicit date formatting, changes in the timezone, setting date to an attribute changes.

Let's explore a **`lodash`** again. In a [changelog](https://github.com/lodash/lodash/wiki/Changelog) we can find breaking changes in a version 3.0.0. When semver major version changes, it indicates, that API contains semantic breaking changes.

```javascript
var array = [1],
    wrapped = _(array);

// in 2.4.1
var a = wrapped.push(2), // pushes `2` to `array`
    b = wrapped.push(3); // pushes `3` to `array`

a.value(); // ➜ returns `array`; [1, 2, 3]
b.value(); // ➜ returns `array`; [1, 2, 3]

// in 3.0.0
var a = wrapped.push(2), // creates a lazy sequence to push `2` to `array`
    b = wrapped.push(3); // creates a lazy sequence to push `3` to `array`

a.value(); // ➜ pushes `2` to `array` and returns `array`; [1, 2]
b.value(); // ➜ pushes `3` to `array` and returns `array`; [1, 2, 3]
a.value(); // ➜ pushes `2` to `array` and returns `array`; [1, 2, 3, 2]
b.value(); // ➜ pushes `3` to `array` and returns `array`; [1, 2, 3, 2, 3]

// use `_#commit` to commit a sequence and continue chaining
var a = wrapped.push(2).commit(), // pushes `2` to `array`
    b = wrapped.push(3).commit(); // pushes `3` to `array`

a.value(); // ➜ returns `array`; [1, 2, 3]
b.value(); // ➜ returns `array`; [1, 2, 3]
```

This example depicts none of the structural changes. But calling the same function in different major versions (2.x and 3.x) results in different inner state of closure.

## **How to avoid breaking changes?**

Structural breaking changes can be avoided by providing additional method/function/constructor/class. Consider the case with the **`lodash`** and **`forEach`**. **`lodash`** could avoid the breaking changes by adding another method/function instead of **`forEach`**, they could add **`forEachLazy`** or **`lazyForEach`** which will provide the same eager API as in 2.x version. Another option how to avoid breaking changes is create new lazy API, by adding an additional parameter to the default export function as **`_.({lazy: true})`**. In this case only lazy wrapper with explicitly called **`value()`** method will be created.

## **Why we are doing breaking changes?**

An example with **`forEach`** has two options how to avoid breaking changes.

- add another method/function **`forEachLazy`**

- add function overload for a default **`lodash`** function with additional optional parameters.

Both of these cases will complicate **`lodash`** API, will make it less consistent with other functions. Also it will increase maintenance cost of two different approaches to be handled for array methods.

These two reasons are not the only reasons to make breaking changes. In my opinion those are the main reasons. To make decision you need to balance between API complexity / maintenance cost and consumer migration cost / benefit.