# Семантическое версионирование (SemVer)

_Ежедневная работа · GitLab Knowledge Base_

**TL;DR:** Конвенция версионирования `MAJOR.MINOR.PATCH`. PATCH - обратно-
совместимые баг-фиксы, MINOR - новая совместимая функциональность,
MAJOR - ломающие изменения. Принят большинством библиотек.


Semver - Semantic Versioning, спецификация от Tom Preston-Werner
(соавтор GitHub). Формат версии: `MAJOR.MINOR.PATCH`.

## Что значит каждая цифра

  - **PATCH** (1.4.**2**) - обратно-совместимые баг-фиксы. Обновился
  с 1.4.1 на 1.4.2 - ничего не сломалось, баг ушёл.
  - **MINOR** (1.**4**.0) - новая функциональность, обратно-
  совместимая. Старое продолжает работать, появилось новое
  опциональное.
  - **MAJOR** (**1**.0.0) - ломающие изменения. Что-то поменялось
  несовместимо, обновление требует миграции кода.

При увеличении старшего разряда младшие обнуляются:

```
1.4.2 → 1.4.3   (patch)
1.4.2 → 1.5.0   (minor)
1.4.2 → 2.0.0   (major)
```

## Дополнительные ярлыки

  - `1.4.2-beta.1`, `1.4.2-rc.3` - pre-release. Сортируются
  до `1.4.2` без суффикса.
  - `1.4.2+20260527.git7c8a1` - build-метаданные. Игнорируются при
  сравнении.

Сортировка: `1.4.2-alpha.1` < `1.4.2-beta.1` < `1.4.2-rc.1` <
`1.4.2` < `1.4.3`.

## Версии 0.x.y

Пока major = 0, semver не действует строго. Версия считается
«нестабильной», ломающие изменения могут быть и в minor.
Это «обещание не давать обещаний». Многие проекты годами сидят
на `0.x` именно по этой причине - не хотят брать на себя
semver-обязательства.

Переход на `1.0.0` означает: «API публичный, обещаю semver».
Это не «продакшен-готовый», а «теперь обратная совместимость - 
политика».

## Связь с Conventional Commits

С [conventional-commits](/courses/git/kb/conventional-commits.md) semver выбирается автоматически:

| Тип коммитов с последнего релиза | Новая версия |
|---|---|
| Только `fix:` / `chore:` / `docs:` | PATCH |
| Хотя бы один `feat:` (без BREAKING) | MINOR |
| Хотя бы один `BREAKING CHANGE:` или `!` | MAJOR |

Инструменты (`semantic-release`, `release-please`,
`standard-version`) делают это сами: смотрят коммиты, считают
следующую версию, создают git-tag, обновляют CHANGELOG.md.

## Распространённые ошибки

- **«У меня патч сломал чужой код».** Если patch ломает что-то у
  пользователя - это не patch, это major. Patch обязан быть
  обратно-совместимым.
- **«Я внутри переписал, версия PATCH».** Если поведение снаружи
  не поменялось - да, PATCH. Если поменялось - minor или major.
  Внутренние правки сами по себе не определяют уровень.
- **«Версия с `^` в package.json».** `^1.4.2` означает «любая
  `1.x.y` ≥ 1.4.2». Это работает, потому что semver обещает
  совместимость в пределах major. Если автор библиотеки нарушит
  semver - `^` подведёт.

## Подводные камни

- **Pre-1.0 неудобно для пользователей.** Если ты делаешь
  библиотеку и кто-то её уже использует - переход на 1.0 даёт
  им гарантии. Сидеть в 0.x десятилетиями - антипаттерн.
- **Major-bumpы дорого.** Пользователям нужно мигрировать. Если
  делаешь библиотеку с активной экосистемой - продумывай
  deprecation-периоды, давай год на переход.
  - **CalVer - альтернатива semver.** `2026.05.0` (год.месяц.релиз).
  Используется в Ubuntu, в pip, в JetBrains. Без обещаний
  совместимости, просто временная метка. Не путать с semver.


## Команды

```bash
git tag -a v1.4.2 -m "release 1.4.2"
```
Создать annotated tag для релиза 1.4.2 (без -a получится lightweight)

```bash
git describe --tags
```
Показать ближайший тег и количество коммитов после него

```bash
npx semantic-release
```
Автоматически определить версию, создать тег, обновить CHANGELOG


## См. также

- [Tag](/courses/git/kb/tag.md)
- [Conventional Commits](/courses/git/kb/conventional-commits.md)
- [git commit](/courses/git/kb/commit-cmd.md)