Semantic versioning, tags and releases

Why version numbers need rules

Your app depends on dozens of libraries, and other teams depend on your API. When a new version comes out, they need to know: is it safe to upgrade? Semantic versioning (SemVer) answers that with the number itself. A version has three parts, MAJOR.MINOR.PATCH, such as 2.4.1.

Version 0.y.z is for early development: anything may change at any time. Releasing 1.0.0 is a promise that you now follow these rules for your public API.

Pre-releases and build metadata

A pre-release adds a hyphen and labels after the patch number: 2.0.0-alpha, 2.0.0-beta.2, 2.0.0-rc.1 (release candidate). A pre-release is LOWER than the normal version: 2.0.0-rc.1 comes before 2.0.0. Labels are compared part by part: numbers as numbers, words alphabetically, so 2.0.0-alpha < 2.0.0-alpha.1 < 2.0.0-beta < 2.0.0-rc.1 < 2.0.0.

Build metadata adds a plus sign: 2.0.0+build.417 or 2.0.0+20261019.3f9c2ab. It records how the artefact was built and is ignored when comparing versions, so 2.0.0+a and 2.0.0+b count as the same version.

Version ranges in package managers

npm (and many other package managers) let you accept a range of versions in package.json. The two common symbols are the caret and the tilde.

npm install saves dependencies with ^ by default. The lock file (package-lock.json) then records the exact version installed, so every machine and every CI run installs the same thing. Commit the lock file.

Git tags

A tag is a name that permanently points at one commit, usually a release. Unlike a branch, it does not move. A lightweight tag is just a name. An annotated tag is a full object with the tagger, date and a message, and can be signed. Use annotated tags for releases.

git tag v1.2.0                          # lightweight tag on the current commit
git tag -a v1.2.0 -m "Release 1.2.0"    # annotated tag (preferred for releases)
git tag                                 # list tags
git show v1.2.0                         # tag details and the commit
git push origin v1.2.0                  # tags are NOT pushed by default: push one...
git push --tags                         # ...or push all local tags

Releases and changelogs

On GitHub or GitLab, a release is a page attached to a tag, with release notes and downloadable files. A changelog (CHANGELOG.md) lists notable changes per version under headings such as Added, Changed, Fixed and Removed, newest version first, so users do not have to read commits.

The next version from Conventional Commits

If commit messages follow Conventional Commits, the next version can be computed. Look at all commits since the last tag. Any breaking change means MAJOR. Otherwise, any feat means MINOR. Otherwise, any fix (teams often count perf too) means PATCH. If there are only docs, chore or test commits, there is nothing to release. Tools such as semantic-release and release-please do this in CI, then tag, publish and write the changelog.

Last tag: v2.4.1
  fix(cart): keep coupon after login        → patch
  feat(orders): add "Order again" button    → minor
  docs: update README                       → no release
Highest wins: MINOR → next version v2.5.0

Common mistakes and how to fix them

• Releasing a breaking change as a MINOR version: users with ^ ranges get it automatically and their builds break. If unsure, check whether old code calling your API still works unchanged.
• Moving or reusing a tag after it was published. Never change what v1.2.0 points to; release v1.2.1 instead.
• Forgetting to push tags, so CI never sees the release. Push the tag explicitly.
• Forgetting to reset lower parts: 1.4.2 with a new feature is 1.5.0, not 1.5.2.