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

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 semver выбирается автоматически:

Инструменты (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.