Что такое семантическое версионирование (SemVer)
Семантическое версионирование — это стандарт, обозначающий правила для определения номера версии при выходе новых выпусков программного обеспечения. Оно позволяет пользователям и участникам разработки понять, какие изменения произошли с продуктом.
Стоит отметить, что не каждый проект следует этому стандарту, так как это не строгое правило нумерования пакетов, а лишь способ структурировать обновления.
Номер версии в соответствии со стандартом устанавливается в формате X.Y.Z, где:
- X — это основной номер (major, мажор);
- Y — это дополнительный номер (minor, минор);
- Z — это номер исправления (patch, патч).
Эти числа характеризуют изменения и степень совместимости пакета с предыдущими обновлениями.
Другие правила SemVer:
- проект, использующий стандарт, должен предоставить публичный API — он может быть описан в документации или представлен непосредственно в коде;
- нумерация не может быть отрицательной или начинаться с нуля (например, 1.02.4);
- после выхода пакета его содержимое изменять нельзя — если обнаружены баги, то они должны быть исправлены в новой версии.
Основные правила SemVer: мажор, минор, патч
Мажор — это первое число в нумеровании каждой версии, оно изменяется, когда обновление может нарушить обратную совместимость. Это могут быть:
- серьезные изменения в API, которые влекут неработоспособность старого кода;
- удаление устаревших функций или методов;
- существенное изменение логики работы или введение новых функций.
Когда обновляется мажор, минор и патч должны быть обнулены, например, 1.4.2 -> 2.0.0. Во время разработки проекта (мажор равен 0) любое обновление может нарушить совместимость. Например, 0.2.2 может быть несовместима с 0.3.0. Начиная с 1.0.0 номера могут изменяться только в соответствии с обновлениями API — 1.2.2 должна быть совместима с 1.3.0. Если нововведения несовместимы с предыдущей версией, они должны быть обозначены как 2.0.0.
Минор — второе число в нумеровании — изменяется, когда проект добавляет новую функциональность, при этом не нарушающие обратную совместимость. Это могут быть:
- внедрение новых функций без существенного изменения уже имеющихся;
- отметка какой-либо функции API как устаревшей (deprecated);
- добавление улучшений.
Когда минор увеличивается, патч должен быть обнулен, например, 1.4.2 -> 1.5.0.
Патч — третье число в нумеровании — обновляется при исправлении багов, которые не влияют на обратную совместимость пакета. То есть патч должен изменяться, когда разработчики корректируют внутренние проблемы, например неправильную работу функции, не добавляя новой функциональности. Обновление патча не затрагивает мажор и минор: 1.4.2 -> 1.4.3.
Семантическое версионирование также позволяет обозначать предрелизные версии — те, что могут не гарантировать совместимость и стабильность. Для их указания используются идентификаторы, следующие после дефиса: например, 1.0.0-alpha. Данные идентификаторы могут содержать буквы, цифры и дефис, но не должны начинаться с нуля.
Для определения новизны или, напротив, устарелости обновления, SemVer предлагает приоритеты. Порядок их сравнения следующий:
- Сопоставляются сначала мажор, затем минор, в последнюю очередь патч. Например: 3.0.0 < 4.0.0 < 4.1.0 < 4.1.1.
- Предрелизные версии имеют меньший приоритет при равных мажорах, минорах и патчах: 1.0.0-alpha < 1.0.0.
- Если нужно сравнить несколько предрелизных версий с равными мажорами, минорами и патчами, идентификаторы сопоставляются слева направо, пока не будет найдено различие, например, 1.0.0-alpha < 1.0.0-alpha.1. Числовые идентификаторы имеют меньший приоритет, чем символьные: 1.0.0-alpha.1 < 1.0.0-alpha.beta. Символьные идентификаторы сравниваются в соответствии с ASCII-кодами символов: 1.0.0-beta.11 < 1.0.0-rc.1 (r — 114, b — 98 по таблице ASCII, 114 > 98).
Примеры использования SemVer в проектах
Семантического версионирования придерживаются многие известные проекты, среди которых:
- Node.js — среда выполнения для программ на языке JavaScript;
- Docker — ПО для разработки, доставки и запуска приложений с поддержкой контейнеризации;
- множество Python-библиотек, например requests;
- Angular — фреймворк для разработки веб-приложений.
Преимущества семантического версионирования
SemVer имеет несколько плюсов как для разработчиков, так и для пользователей:
- семантическое версионирование позволяет избежать путаницы в версиях — оно структурирует их понятным для всех образом;
- устаревшие функции можно удалять постепенно, используя пометку deprecated;
- стандарт сразу объясняет степень серьезности изменений: пользователи понимают, что обновления минора и патча не нарушает обратную совместимость;
- поддержка стандарта инструментами управления зависимости, например, pip и Maven.
Советы по управлению версиями пакетов
Чтобы версионирование пакетов оставалось помогающим компонентом, можно следовать этим рекомендациям:
- публичный API должен быть задокументирован, а при его изменении документацию лучше также обновлять;
- менять номер версии без фактических обновлений не стоит;
- номер пакета должен отражать характер изменений: патч обновляется при исправлении багов, минор — при добавлении новых функций, мажор — если обновление несовместимо с предыдущим;
- каждое обновление должно выходить с описанием;
- изменения, нарушающие совместимость, лучше выпускать редко, совмещая несколько обновлений в релизе.