Basic

Semantic version numbers

Three numbers with meaning: major, minor, patch. The meaning is the contract, and the contract is what a tool compares when it decides whether an upgrade is safe. Choosing which number to move is a decision about what a consumer may assume.

What you will see

Minor, and patch resets to zero. The old commands still work, which is the minor promise.

About 1 min of reading

Try It

Choose the number.

1

A bug fix

print('2.4.1 -> 2.4.2')

Before you run it, say out loud what it will print. Then open the answer.

What it prints
Patch. Nothing was added, so the minor number must not move.
2

A new command

print('2.4.2 -> 2.5.0')

Before you run it, say out loud what it will print. Then open the answer.

What it prints
Minor, and patch resets to zero. The old commands still work, which is the minor promise.

Data Flow

The number carries the promise.
1 Decide what changed
↓
2 Pick the number that matches
↓
3 Reset the lower numbers
↓
4 Consumers compare on the promise
Line by line

Read the first example one line at a time. A line that prints shows what appears on screen; the rest set things up quietly.

print('2.4.1 -> 2.4.2') Patch. Nothing was added, so the minor number must not move.
Why this works
Reset the lower numbers

Moving major sets minor and patch to zero. A version 3.4.2 released as a major is a mistake, because the number then claims compatibility that a major does not promise.

Pre-release tags

A version can carry a suffix for a build that is not final. That suffix is what keeps a release candidate from being mistaken for a release, which is a real confusion in a team that ships.

Examples

Patch is safe

2.4.1 to 2.4.2 is fixes only. A consumer that pinned 2.4 can take 2.4.2 without a test, because the contract says nothing was added or removed.

Minor adds

2.4 to 2.5 adds features and keeps the old ones working. A consumer can upgrade and its existing calls still work, which is the promise the minor number carries.

Major may break

2.x to 3.x allows removals and changes. A consumer that auto takes majors will get a broken program, which is why dependency ranges stop at the major.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Why versions exist
Previous Lesson
Why versions exist
Next Lesson
Tagging a release in git
Tagging a release in git →