Объясните формат семантического версионирования MAJOR.MINOR.PATCH: когда нужно увеличивать каждую из частей?

Короткий ответ

MAJOR увеличивается при несовместимых изменениях API, MINOR — при добавлении новой функциональности с сохранением обратной совместимости, PATCH — при исправлении багов без изменения публичного интерфейса.

Как это работает подробнее

semver (semver.org) задаёт соглашение, по которому номер версии сам по себе сообщает потребителям библиотеки или сервиса, насколько рискованно обновляться. Например, переход с `2.3.1` на `2.4.0` должен быть безопасен, а переход на `3.0.0` может сломать существующий код.

Пример кода

example.txtКопировать

1.4.2 -> 1.4.3   (исправлен баг, API не менялся)              -> PATCH
1.4.3 -> 1.5.0   (добавлен новый необязательный параметр)      -> MINOR
1.5.0 -> 2.0.0   (удалён старый эндпоинт /v1/users)             -> MAJOR

Что использовать на практике

• На практике. semver особенно важен для библиотек, SDK и публичных API, от которых зависят другие команды или внешние клиенты; для внутренних монолитных приложений без внешних потребителей строгая семантика иногда менее критична, но дисциплина версионирования всё равно помогает в коммуникации между командами.
• Пример. Ожидаемое поведение: клиент, зависящий от `^1.4.2` в package.json, безопасно получит `1.5.0`, но не получит `2.0.0` без явного изменения ограничения версии.

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

• Частые ошибки. увеличивают только PATCH при добавлении нового, пусть и обратно совместимого, публичного метода (должен быть MINOR); меняют поведение существующего эндпоинта как «багфикс» (PATCH), хотя по факту это ломающее изменение для части клиентов, которые зависели от старого поведения.