SemVer, conventional commits и автоматические changelog

SemVer — обещание о том, что может сломаться

Зачем вообще нужен номер версии? Потому что потребители автоматизируют обновления: ^2.0.0 молча подтягивает каждый MINOR и PATCH. Если ты пометишь слом неверно, он уедет ко всем, кто тебе доверял. Этот контракт и есть весь смысл раздела.

Версия MAJOR.MINOR.PATCH — это не журнал затраченных усилий, а контракт совместимости, направленный на потребителя. SemVer 2.0.0 фиксирует смысл каждого поля точно:

• MAJOR — ты внёс обратно несовместимое изменение. Любой наблюдаемый потребителем слом считается: удалённая функция, переименованное поле, суженный диапазон входа, изменённое значение по умолчанию или — как в хуке — изменённое поведение, на которое опирался их код. Если корректное прежде использование теперь может сломаться, это MAJOR.
• MINOR — ты добавил функциональность обратно совместимым образом. Новый эндпоинт, новый необязательный аргумент, новое поле в ответе. Старый код продолжает работать нетронутым.
• PATCH — только обратно совместимое исправление бага. Контракт не меняется; ты заставил код честно выполнять то, что уже обещал.

Тонкий, сеньорский момент: «слом» означает контракт, наблюдаемый потребителем, а не «удалённый код». Ужесточение валидации, смена типа ошибки, изменение порядка вывода, который потребитель парсил, — всё это может быть ломающим, хотя ничего не удалено. Автор, говорящий «я ничего не удалял», держит в голове неверную модель.

Два угла важны на практике. 0.y.z — это начальная разработка: по SemVer публичный API явно не стабилен, поэтому что угодно МОЖЕТ измениться в любом релизе — до 1.0 нельзя опираться на то, что MINOR/PATCH вообще что-то значат, поэтому «0ver»-проекты (версии, которые никогда не доходят до 1.0.0 именно чтобы увернуться от обещания MAJOR) раздражают потребителей. А pre-release / build-метаданные расширяют формат: 1.4.0-rc.1 (release candidate, сортируется перед 1.4.0) и 1.4.0+build.42 (build-метаданные, игнорируются при сравнении старшинства) позволяют публиковать превью, не тратя настоящий номер.

Conventional commits: машиночитаемый сигнал

Разрыв между «я знаю, что это ломающее» и «инструмент это знает» закрывают Conventional Commits — крошечная грамматика на заголовке и футере коммита, которую умеет читать парсер. Контракт:

fix: a bug fix                          → PATCH
feat: a new feature                     → MINOR
feat!: a feature that breaks the API    → MAJOR   (! помечает слом)

# или тот же слом, выраженный в футере:
refactor: drop the legacy code path

BREAKING CHANGE: parse() now returns null instead of throwing.
                 Wrap callers that relied on the throw.

Два способа подать сигнал MAJOR, и оба должны присутствовать в сообщении, чтобы инструмент их увидел: ! после типа/скоупа (feat!:, fix(api)!:) или футер BREAKING CHANGE: (заметь буквальный токен {BREAKING CHANGE} с пробелом, а не дефисом). Типы, не затрагивающие отгружаемое поведение — docs:, chore:, test:, style:, ci: — не дают bump вовсе. Это несущая конвенция всего юнита: bump вычисляется из типа коммита, поэтому непомеченный слом невидим для машины и уезжает не на том уровне.

Два инструмента, две философии: декларировать vs выводить

Когда коммиты несут намерение, инструмент превращает историю в релиз. Два доминирующих варианта стоят на противоположных концах оси «явно vs автоматически».

changesets делает намерение явным и пер-PR. Закончив работу, ты запускаешь changeset add, выбираешь затронутые пакеты, выбираешь bump и пишешь человеческое summary; он кладёт markdown-файл в .changeset/, который едет с твоей веткой и проходит код-ревью. На релизе changeset version поглощает все ожидающие файлы, вычисляет новую версию каждого пакета и пишет changelog; changeset publish отгружает их. Поскольку контрибьютор декларирует bump в проверяемом файле, это отлично для монорепо — он понимает межпакетные bump’ы зависимостей — и ему никогда не приходится угадывать по тексту коммита.

---
"@acme/parser": major
"@acme/cli": patch
---

parse() now returns null on bad input instead of throwing.
Callers that relied on the throw must add an explicit null check.

release-please делает намерение выводимым и автоматическим. Бот парсит твои conventional commits на main, вычисляет следующую версию и поддерживает постоянный «release PR», чей diff — это обновлённые файлы версии плюс сгенерированный CHANGELOG.md. PR непрерывно актуализируется по мере новых коммитов; когда ты его мёржишь, release-please ставит тег релиза и публикует. Ты не пишешь файлов намерения — коммит и есть намерение, — что бесшовно, пока коммит не помечен неверно, потому что бот верит коммиту, а не твоим намерениям.

Режим отказа: непомеченный слом уезжает как MINOR

Всё выше существует, чтобы предотвратить один конкретный инцидент, и он самый частый в автоматизации релизов. Контрибьютор делает ломающее изменение, но пишет feat: improve parse() — без !, без футера. Инструмент послушно вычисляет MINOR, потому что именно это коммит говорит. Новая версия уезжает, и каждый потребитель, запиненный на caret-диапазон (^2.0.0, дефолт npm), автоматически подтягивается в слом без единого человеческого решения. Номер версии соврал, а контракт, которому потребители доверяли как воротам против ломающих изменений, не сработал.

Squash-merge — усилитель. Если слом был просигналлен только в футере BREAKING CHANGE: (в теле коммита), а PR squash-мёржится, оставляя лишь строку заголовка, футер испаряется, и инструмент видит обычный feat: — снова MINOR. Защиты конкретны: насаждай конвенцию через commitlint в CI, чтобы непарсимый или нетипизированный коммит проваливал проверку; требуй маркер в заголовке стиля feat!: (а не только футер) для сломов, чтобы squash его сохранил; или используй changesets, где bump живёт в ревьюируемом файле, который squash не срежет. И генерируй changelog из того же сигнала — рукописный CHANGELOG.md дрейфует от реальности в тот момент, когда кто-то забыл его обновить; сгенерированный по построению ровно то, что коммиты сказали отгрузить.