Семантическое управление версиями (или семвер) – это формальное соглашение для определения номера версии новых выпусков программного обеспечения. Стандарт помогает пользователям программного обеспечения понять серьезность изменений в каждом новом дистрибутиве.
Проект, использующий семантическое управление версиями, объявляет основной номер версии (major), дополнительный номер версии (minor) и номер исправления (patch) для каждого выпуска. Строка версии 1.2.3 указывает на основную версию под номером 1, дополнительную версию под номером 2 и исправление под номером 3.
Номера версий такого формата широко используются как программными пакетами, так и исполняемыми файлами конечных пользователей, такими как приложения и игры. Однако не каждый проект точно следует стандарту, установленному semver.org.
Спецификация была создана для решения проблем, вызванных несовместимостью методов управления версиями между программными пакетами, используемыми в качестве зависимостей. Под «пакетом» и «зависимостью» мы подразумеваем библиотеку кода, предназначенную для использования в другом программном проекте и распространяемую диспетчером пакетов, таким как npm, composer или nuget. Это именно то применение семантического управления версиями, которое мы рассматриваем в этой статье.
Major, Minor и Patch
Важно понимать значение трех задействованных компонентов. Вместе они намечают путь разработки проекта и соотносят влияние каждого нового выпуска на конечных пользователей.
- Major number (основной номер версии) – основной номер указывает на текущую версию общедоступного интерфейса пакета. Он увеличивается каждый раз, когда вы вносите изменения, которые требуют от существующих пользователей вашего пакета обновления их собственной работы.
- Minor number (дополнительный номер версии) – дополнительный номер указывает на текущую функциональную версию вашего программного обеспечения. Он увеличивается всякий раз, когда вы добавляете новую функцию, но не меняете интерфейс вашего пакета. Он сообщает пользователям о том, что были внесены значительные изменения, но пакет полностью совместимым с предыдущими версиями с предыдущим дополнительным номером.
- Patch number (номер исправления) – номер исправления увеличивается каждый раз, когда вы вносите какое-то незначительное изменение, которое не влияет на общедоступный интерфейс или общую функциональность вашего пакета. Его чаще всего используют для исправления ошибок. Потребители всегда должны иметь возможность не задумываясь установить последнюю версию исправлений.
Семантическая структура версии выпуска лучше всего моделируется в виде дерева. Наверху у вас изменения общедоступного интерфейса, каждое из которых отображается на основном номере. Каждая основная версия имеет свой собственный набор дополнительных версий, в которые добавляются новые функции без нарушения совместимости с предыдущими версиями. И наконец, дополнительные версии могут время от времени отлаживаться путем исправления некоторых ошибок.
Откуда начинать?
Большинство проектов должны начинаться с версии 1.0.0. Вы публикуете свой первый общедоступный интерфейс и первоначальный неизмененный набор функций. И поскольку вам еще не приходилось вносить никаких исправления, то и версия исправления – 0.
Теперь давайте посмотрим, что же происходит, когда вы вносите изменения в свой пакет. После вашего первоначального выпуска вы получаете отчет об ошибке от пользователя. Когда вы выпустите исправление, то правильный номер версии уже будет 1.0.1. Если бы вы затем выпустили еще одну версию с исправлением ошибок, то вы бы увеличили номер исправления до 2, т.е. номер версии уже был бы 1.0.2.
Тем временем вы также работали над новой интересной функцией. Это совершенно необязательно, поэтому пользователям не нужно ничего делать для обновления. Вы выпускаете эту версию как 1.1.0. – создана новая функциональная среда, но ее еще ни разу не исправляли. К сожалению, скоро приходят отчеты об ошибках, и среди ваших пользователей начинает распространяться версия 1.1.1.
Несколько месяцев спустя вы решили провести реорганизацию кода всего проекта. Некоторые функции были удалены или теперь доступны через объединенный интерфейс. Если вы выпустите эту работу, то люди, использующие текущую версию вашего пакета, должны будут внести серьезные изменения в свой проект. Пришло время опубликовать 2.0.0. в вашем репозитории пакетов.
Поддержание старых веток
Увеличение какого-либо номера в вашей строке версий не создает точку невозврата. После публикации 1.1.1 вы могли обнаружить ошибку, присутствующую в 1.0.2. Используя ветки в вашей системе контроля версий, вы можете произвести исправления в обеих версиях. В итоге вы получите 1.1.2 и 1.0.3.
Точно также вы можете поддерживать ветку 1.х вашего проекта, несмотря на выпуск 2.0.0. Может показаться странным публиковать 1.1.2 после 2.0.1, но это вполне нормальная практика. Семантическое управление версиями не создает линейный постоянно увеличивающийся номер версии; наоборот, оно предназначено для использования в качестве части модели разработки ветвления, которое использует простоту установки исправлений, предлагаемую системами управления исходным кодом, такими как Git.
Опубликованные версии должны быть неизменяемыми. После того, как вы создали версию 2.4.3, вы не можете «обновить» его, просто добавив дополнительный код в ту же строку версии. Вы должны присваивать новый номер версии каждому выпуску, чтобы пользователи всегда могли получить доступ к каждой конкретной версии вашего пакета.
Обработка пакетов, находящихся в стадии разработки
Как правило, вы всегда обновляете основную версию своего пакета всякий раз, когда вносятся изменения, несовместимые с предыдущими версиями. Когда вы находитесь в стадии разработки, то ваша кодовая база может дорабатываться очень быстро, что приводит к публикации множества основных версий.
Вы можете этого избежать, рекламируя свой проект как 0.y.z. Значение 0 в качестве основной версии означает, что ваш пакет неустойчив. Обычные правила в отношении совместимости с предыдущими версиями тут не применяются, поэтому вы можете выпускать новые версии, увеличивая только дополнительный номер и номер исправления. Это значит, что вы можете использовать 1.0.0 для обозначения первой «завершенной» версии вашего программного обеспечения.
Вы также можете добавить дополнительные «идентификаторы» в конец строки версии, используя дефис в качестве разделителя: 1.0.0-alpha.1. Вы можете использовать такой вариант для того, чтобы четко обозначить альфа- и бета-версии. Точно также вы можете включить метаданные сборки, добавив символ +: 1.1.0-alpha.1+linux_x86.
Заключение
Согласованное использование семантического управления версиями помогает пользователям быть уверенными в вашем проекте. Они могут четко видеть, как развивается ваша кодовая база и нужно ли им самим провести какую-то работу, чтобы идти в ногу со временем.
Объявление строки семантической версии необходимо при публикации в диспетчере наиболее популярных пакетов. Тем не менее, в конечном счете, вам решать, какие номера вы устанавливаете для каждого нового выпуска. Соблюдение стандарта четко сообщает о ваших намерениях пользователям и сводит к минимуму риск непреднамеренного нарушения чужой работы.
