В мире разработки программного обеспечения есть страшное место под названием «ад зависимостей».
Чем больше ваша система, тем больше вероятность того, что однажды вы попадете в эту ловушку.
В системе с большим количеством зависимостей выпуск новых пакетов может быстро превратиться в кошмар.
Если зависимости слишком сильны, вы не сможете обновить пакет, не обновив также версии всех зависимых пакетов.
Если зависимости слишком свободны, у вас возникнут проблемы со свободными версиями.
«Ад зависимостей» — это когда слишком сильные или, наоборот, слишком слабые зависимости мешают вам легко и безопасно развивать свой проект. В качестве решения этой проблемы я предлагаю простой набор правил, определяющих, как назначаются и увеличиваются номера версий.
Чтобы система работала, сначала нужно объявить открытый API. Это должен быть простой и понятный документ. Рассмотрим номер версии в формате X.Y.Z (Major.Minor.Patch).
При исправлении ошибок, не затрагивающих API, версия Патча увеличивается.
При добавлении или изменении API с сохранением обратной совместимости Minor-версия увеличивается.
Если API изменяется без сохранения обратной совместимости, основная версия увеличивается.
Я называю эту систему семантическим управлением версиями.
Согласно этой схеме номера версий и то, как они изменяются, передают значение базового кода и того, как он менялся от версии к версии.
Спецификация семантического управления версиями
Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «СЛЕДУЕТ», «НЕ ДОЛЖЕН», «МОЖЕТ» в этом документе интерпретироваться в соответствии с RFC 2119.- Программный продукт, использующий семантическое управление версиями, ДОЛЖЕН иметь открытый API. Этот API должен быть объявлен в коде или в документации приложения.
API должен быть точным и всеобъемлющим.
- Номер версии ДОЛЖЕН состоять из X.Y.Z, где X, Y и Z — положительные числа.
X — основная версия, Y — дополнительная версия и Z — версия исправления.
Каждый элемент ДОЛЖЕН увеличиваться с шагом в единицу.
Например: 1.9.0 -> 1.10.0 -> 1.11.0.
- При увеличении основной версии версии Minor и Patch ДОЛЖНЫ быть сброшены.
При увеличении минорной версии необходимо сбросить версию патча.
Например: 1.1.3 -> 2.0.0 и 2.1.7 -> 2.2.0.
- После выпуска версии пакета в этот пакет НЕ ДОЛЖНО вноситься никакие изменения.
Все изменения ДОЛЖНЫ быть выпущены вместе с новой версией.
- В начале основной разработки версия равна нулю (0.y.z).
В этот период все может измениться в любой момент. Открытый API НЕ ДОЛЖЕН считаться стабильным.
- Версия 1.0.0 определяет открытый API. Изменение номера версии зависит от этого общедоступного API.
- Версия патча Z (x.y.Z | x > 0) СЛЕДУЕТ увеличивать только в том случае, если исправления ошибок обратно совместимы с предыдущими версиями.
Исправление ошибок устраняет неправильное поведение.
- Младшая версия Y (x.Y.z | x > 0) ДОЛЖНА быть увеличена, если сделаны исправления, совместимые с предыдущими версиями.
Второстепенную версию ДОЛЖНО увеличить, если какой-либо элемент API помечен как «Устаревший».
Второстепенная версия МОЖЕТ быть расширена, если доступны значительные новые функции или улучшения.
Второстепенная версия МОЖЕТ включать изменения по сравнению с версией исправления.
Версия исправления должна быть сброшена при изменении дополнительной версии.
- Основная версия X (X.y.z | X > 0) ДОЛЖНА быть увеличена, если внесены исправления, несовместимые с предыдущими версиями.
Основная версия МОЖЕТ включать изменения по сравнению с версиями Minor и Patch. Исправления и второстепенные версии необходимо сбрасывать при изменении основной версии.
- Предварительные версии МОГУТ обозначаться тире и точечным идентификатором сразу после версии исправления.
Идентификатор ДОЛЖЕН содержать символы [0-9A-Za-z-].
Предварительная версия имеет более низкий приоритет, чем та же самая обычная версия.
Примеры: 1.0.0-альфа, 1.0.0-альфа.
1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
- Версия сборки МОЖЕТ обозначаться знаком плюса и точечным идентификатором сразу после версии исправления или предварительной версии.
Идентификатор ДОЛЖЕН содержать символы [0-9A-Za-z-].
Версия сборки имеет более высокий приоритет, чем та же самая обычная версия.
Примеры: 1.0.0+build.1, 1.3.7+build.11.e0f985a.
- Приоритет ДОЛЖЕН рассчитываться путем деления на основные, второстепенные, исправленные, предварительные версии и сборки.
Версии Major, Minor и Patch всегда содержат цифры.
Предварительные версии и версии сборки ДОЛЖНЫ быть отсортированы путем сравнения каждого идентификатора, разделенного точкой, в следующем порядке: Идентификаторы, содержащие только цифры, сравниваются численно, а идентификаторы, содержащие буквы, - в указанном порядке.
в ASCII. Числовые идентификаторы всегда имеют более низкий приоритет, чем буквенные.
Примеры: 1.0.0-альфа < 1.0.0-alpha.1 < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0-rc.1+build. 1 < 1.0.0 < 1.0.0+0.3.7 < 1.3.7+build < 1.3.7+build.2.b8f12d7 < 1.3.7+build.11.e0f985a.
Зачем использовать семантическое управление версиями?
Это не новая или революционная идея.На самом деле, вы, вероятно, уже делали что-то подобное.
Проблема в том, что «похожий» недостаточно хорош.
Без соответствия какой-либо формальной спецификации номера версий по сути бесполезны для управления зависимостями.
Предоставляя четкие и в меру гибкие определения, вы облегчаете пользователям взаимодействие с вашим продуктом.
Простой пример, показывающий, как семантическое управление версиями может помочь вам избежать ада зависимостей.
Рассмотрим библиотеку под названием «Firetruck».
Это зависит от пакета под названием «Лестница».
На момент создания Firetruck версия Ladder была 3.1.0. Поскольку Firetruck использует другие методы, представленные в версии 3.1.0, вы можете безопасно обновить Ladder до версии выше 3.1.0, но ниже 4.0.0. Теперь, когда версии 3.1.1 и 3.2.0 Ladder становятся доступными, вы можете перейти на них и быть уверенными, что они будут совместимы с существующим у вас программным обеспечением.
Как ответственный разработчик, вы, конечно, захотите проверить совместимость пакетов.
Реальность может быть жестокой, и мы ничего не можем с этим поделать.
Что мы можем сделать, так это позволить семантическому управлению версиями предоставить вам простой способ обновления пакетов.
Это сэкономит ваше время и нервы.
Если вам нравится идея семантического управления версиями, вам просто нужно следовать изложенным здесь правилам.
Вы можете разместить ссылку на эту документацию в файле README вашего проекта, чтобы ваши коллеги, а также люди, использующие ваш продукт, также следовали семантическому управлению версиями.
Часто задаваемые вопросы
Как мне изменить номер версии на начальном этапе 0.yz?
Самый простой способ — начать с версии 0.1.0, а затем увеличивать номер версии для каждого последующего выпуска.
Как узнать, что пора обновляться до версии 1.0.0?
Если ваш продукт используется конечными пользователями, это должна быть версия 1.0.0. Если у вас есть стабильный открытый API, вам следует перейти на версию 1.0.0. Если вас беспокоит обратная совместимость, вам следует обновиться до 1.0.0.Не мешает ли это быстрой разработке и быстрым итерациям?
Версия Zero Major — это все, что вам нужно.Если ваш общедоступный API меняется каждый день, вы должны использовать версию 0.x.x или работать над следующей основной версией.
Если даже самые незначительные изменения не имеют обратной совместимости, не скоро ли я перейду на версию 42.0.0?
Это вопрос ответственного развития и дальновидности.Несовместимые изменения не следует вносить небольшими порциями в код, имеющий множество зависимостей.
Затраты на обновление могут быть непомерно высокими.
Документация по API — это слишком много работы!
Вы как профессиональный разработчик несете ответственность за создание продукта, предназначенного для использования другими людьми.Управление программным обеспечением — сложная и чрезвычайно важная часть поддержания эффективности проекта.
Что делать, если я случайно указал Minor версию вместо Major?
Как только вы поймете, что у вас нарушено семантическое управление версиями, вам следует устранить проблему и выпустить новую версию, которая исправит проблемы и восстановит обратную совместимость.
Что мне делать, если я обновлю свою внутреннюю зависимость, не меняя общедоступный API?
Это приемлемо, если не влияет на открытый API. Продукт, который явно зависит от вашего пакета, должен иметь собственную спецификацию зависимостей, и автор заметит конфликт.Как отметить функциональность как устаревшую?
Устаревший функционал — это нормально, и к нему часто приходится прибегать, чтобы двигаться вперед. Когда вы объявляете устаревшей часть вашего общедоступного API, вы должны сделать две вещи: (1) обновить документацию, (2) выпустить хотя бы одну версию, которая поддерживает как новые, так и устаревшие функции, чтобы у пользователей было время для плавного перехода.
Об авторе
Авторское семантическое управление версиями Том Престон-Вернер , создатель Gravatars и соучредитель GitHub. Для того, чтобы высказать свои вопросы и пожелания создать проблему на GitHub .
Этот перевод на GitHub
Лицензия
Creative Commons — CC BY 3.0 http://creativecommons.org/licenses/by/3.0/ Теги: #семантическое управление версиями #Major #Minor #patch #зависимости #контроль версий #миграция версий #версии #ад зависимости #semver #semver #разработка веб-сайтов-
Реальные Управленческие Мифы О Devops
19 Oct, 24 -
Инструменты Vcloud: Опыт Ит-Град
19 Oct, 24 -
Опыт Разработки Android Wear
19 Oct, 24
