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

Для тегов релизов и совместимости публичного API в проекте принята спецификация Semantic Versioning 2.0.0 (SemVer). Ниже — краткая выжимка; полный и каноничный текст — на semver.org (есть перевод на русский).

Формат версии

Номер версии: MAJOR.MINOR.PATCH (три неотрицательных целых числа без ведущих нулей):

Часть	Когда увеличивать
MAJOR	Несовместимые изменения публичного API (breaking changes).
MINOR	Новая функциональность при сохранении обратной совместимости с предыдущим публичным API.
PATCH	Только обратимо совместимые исправления ошибок.

Предрелизы задаются суффиксом через дефис (например, 1.0.0-alpha, 1.0.0-rc.1). Метаданные сборки — через + (не участвуют в сравнении версий). Подробности — в полной спецификации.

Правила в контексте этого репозитория

Публичный API — SemVer осмыслен, когда формально или по документации зафиксирован публичный контракт (заголовки библиотеки, поведение CMake-пакета, стабильный контракт CLI/JSON). До этого уместна схема 0.y.z: все может меняться в любой момент.
Неизменяемость релиза — для уже выпущенной комбинации MAJOR.MINOR.PATCH нельзя «перезалить» другой артефакт; исправления оформляются новой версией (как правило, PATCH).
Breaking / non-breaking — MAJOR нужен, если потребителям придется менять код, флаги сборки или формат JSON/конфига несовместимым образом.
Устаревание (deprecation) — помечать API устаревшим обычно следует в MINOR с обновлением документации; окончательное удаление — в последующем MAJOR после периода миграции.

Теги и Git

Теги релизов часто именуют как vMAJOR.MINOR.PATCH (префикс v — принятое в Git-обозначениях; семантическая версия при этом остается MAJOR.MINOR.PATCH). Пример: git tag v1.2.3.

Предложение следующей версии (автоматизация)

Скрипт scripts/release/suggest-next-version.sh смотрит коммиты после последнего тега в форме SemVer (vX.Y.Z или X.Y.Z) и выводит предлагаемый тег, опираясь на Conventional Commits (см. CONTRIBUTING.md):

Сигнал в теме / теле коммита	Шаг версии
`BREAKING CHANGE:` / `BREAKING-CHANGE` в теле или `тип!:` (например `feat!:`)	MAJOR
`feat:`	MINOR
`fix:` или `perf:`	PATCH
Прочие типы (`docs:`, `ci:`, `chore:` и т.д.)	По умолчанию без bump; флаг `--any-patch` принудительно дает PATCH, если коммиты есть

bash scripts/release/suggest-next-version.sh
bash scripts/release/suggest-next-version.sh --verbose
bash scripts/release/suggest-next-version.sh --any-patch

Если ни один сигнал не подошел и --any-patch не задан, скрипт печатает текущую версию и завершается с кодом 2. Merge-коммиты не учитываются (--no-merges).

См. также

CHANGELOG.md — журнал изменений по релизам (English)
Semantic Versioning 2.0.0 — полная спецификация и FAQ
CONTRIBUTING.md — соглашения о сообщениях коммитов (дополняют, но не заменяют номера релизов)

English: Versioning