Нумерация версий модуля

Разработчик модуля использует каждую часть номера версии модуля, чтобы сигнализировать о стабильности версии и обратной совместимости. Для каждого нового релиза номер версии модуля отражает характер изменений модуля с момента предыдущего релиза.

Когда вы разрабатываете код, который использует внешние модули, вы можете использовать номера версий, чтобы понять стабильность внешнего модуля при рассмотрении вопроса об обновлении. Когда вы разрабатываете свои собственные модули, номера версий будут сигнализировать другим разработчикам о стабильности и обратной совместимости ваших модулей.

В этом посте описывается, что означают номера версий модулей.

Смотрите также:

Когда вы используете внешние пакеты в своем коде, вы можете управлять этими зависимостями с помощью инструментов Go.

Если вы разрабатываете модули для использования другими, вы применяете номер версии при публикации модуля, отмечая (присваивая тег) модуль в его репозитории.

Выпущенный модуль публикуется с номером версии в семантической модели управления версиями, как показано на следующем рисунке:

Далее описано, как части номера версии обозначают стабильность и обратную совместимость модуля.

• • Модуль в разработке
  • Автоматический номер псевдоверсии, v0.x.x
  • Сигнализирует о том, что модуль все еще находится в разработке и нестабилен. Этот релиз не дает никаких гарантий обратной совместимости или стабильности.
• • Основная (major) версия
  • v1.x.x
  • Сообщает об изменениях общедоступного API, несовместимых с предыдущими версиями. Этот релиз не дает никаких гарантий, что он будет обратно совместим с предыдущими основными версиями.
• • Минорная (minor) версия
  • vx.4.x
  • Сообщает об изменениях общедоступного API с обратной совместимостью. Этот релиз гарантирует обратную совместимость и стабильность.
• • Версия (patch) исправлений
  • vx.x.1
  • Сообщает об изменениях, которые не влияют на общедоступный API модуля или его зависимости. Этот релиз гарантирует обратную совместимость и стабильность.
• • Предварительная версия
  • vx.x.x-beta.2
  • Сигнализирует о том, что это предварительная веха, например, альфа или бета. Этот релиз не дает никаких гарантий стабильности.

В разработке

Сигнализирует о том, что модуль все еще находится в разработке и нестабилен. Этот релиз не дает никаких гарантий обратной совместимости или стабильности.

Номер версии может принимать одну из следующих форм:

• Номер псевдоверсии
  v0.0.0-20170915032832-14c0d48ead0c
• Номер v0
  v0.x.x

Номер псевдоверсии

Если модуль не был помечен (не имеет тега) в своем репозитории, инструменты Go сгенерируют номер псевдоверсии для использования в файле go.mod кода, который вызывает функции в модуле.

Примечание. Рекомендуется всегда позволять инструментам Go генерировать номер псевдоверсии, а не создавать свой собственный.

Псевдоверсии полезны, когда разработчику кода, использующего функции модуля, необходимо использовать коммит, который еще не был помечен тегом семантической версии.

Номер псевдоверсии состоит из трех частей, разделенных тире, как показано в следующей форме:

Синтаксис

baseVersionPrefix-timestamp-revisionIdentifier

Части

• baseVersionPrefix (vX.0.0 или vX.Y.Z-0) - значение, полученное либо из тега семантической версии, предшествующего редакции, либо из vX.0.0, если такого тега нет.
• timestamp (yymmddhhmmss) - время создания ревизии в формате UTC. В Git это время коммита, а не время автора.
• revisionIdentifier (abcdefabcdef) - это 12-символьный префикс хэша коммита или, в Subversion, номер версии, дополненный нулями.

Номер v0

Модуль, опубликованный с номером v0, будет иметь формальный семантический номер версии с основной, минорной и патч частью, а также необязательным идентификатором предварительной версии.

Хотя версию v0 можно использовать в производстве, она не дает никаких гарантий стабильности или обратной совместимости. Кроме того, версии v1 и более поздние могут нарушать обратную совместимость для кода, использующего версии v0. По этой причине разработчик функций, использующих код в модуле v0, несет ответственность за адаптацию к несовместимым изменениям, пока не будет выпущена версия v1.

Предварительная версия

Сигнализирует о том, что это предварительная веха, например альфа или бета. Этот релиз не дает никаких гарантий стабильности.

Пример

vx.x.x-beta.2

Разработчик модуля может использовать идентификатор предварительной версии с любой комбинацией major.minor.patch, добавив дефис и идентификатор предварительной версии.

Минорная версия

Сообщает об обратно совместимых изменениях в общедоступном API модуля. Этот релиз гарантирует обратную совместимость и стабильность.

Пример

vx.4.x

Эта версия изменяет общедоступный API модуля, но не таким образом, чтобы нарушать вызывающий код. Это может включать изменения собственных зависимостей модуля или добавление новых функций, методов, полей структур или типов.

Другими словами, эта версия может включать улучшения за счет новых функций, которые может захотеть использовать другой разработчик. Однако разработчику, использующему предыдущие минорные версии, не нужно менять свой код в противном случае.

Версия патча

Сообщает об изменениях, которые не влияют на общедоступный API модуля или его зависимости. Этот релиз гарантирует обратную совместимость и стабильность.

Пример

vx.x.1

Обновление, увеличивающее это число, предназначено только для незначительных изменений, таких как исправления ошибок. Разработчики потребляющего кода могут безопасно перейти на эту версию без необходимости изменять свой код.

Основная версия

Сообщает о несовместимых изменениях в общедоступном API модуля. Этот релиз не дает никаких гарантий, что он будет обратно совместим с предыдущими основными версиями.

Пример

v1.x.x

Номер версии v1 или выше означает, что модуль стабилен для использования (за исключением его предварительных версий).

Обратите внимание: поскольку версия 0 не дает никаких гарантий стабильности или обратной совместимости, разработчик, обновляющий модуль с v0 до v1, несет ответственность за адаптацию к изменениям, нарушающим обратную совместимость.

Разработчик модуля должен увеличивать это число после v1 только при необходимости, потому что обновление версии представляет собой серьезное нарушение работы разработчиков, код которых использует функцию в обновленном модуле. Это нарушение включает обратно несовместимые изменения в общедоступном API, а также необходимость для разработчиков, использующих модуль, обновлять путь к пакету везде, где они импортируют пакеты из модуля.

Обновление основной версии до номера выше v1 также будет иметь новый путь к модулю. Это потому, что к пути к модулю будет добавлен основной номер версии, как в следующем примере:

module example.com/mymodule/v2 v2.0.0

Обновление основной версии делает этот модуль новым с историей, отдельной от предыдущей версии модуля.

---

Читайте также:

• Разработка и публикация модулей в Golang
• Выпуск модуля и рабочий процесс управления версиями
• Управление исходным кодом модуля
• Разработка обновления основной версии
• Публикация модуля в Golang

Канал в Телеграм

Разработка обновления основной версии

Вы должны выполнить обновление основной версии, если изменения, которые вы вносите в потенциальную новую версию, не могут гарантировать обратную совместимость для пользователей модуля. Например, вы внесете такое изменение, если измените общедоступный API вашего модуля так, чтобы он нарушал работу клиентского кода, использующего предыдущие версии модуля.

Примечание. Каждый тип релиза - основной, минорный, патч (релиз исправлений) или предварительный релиз - имеет разное значение для пользователей модуля. Эти пользователи полагаются на эти различия, чтобы понять уровень риска, который релиз представляет для их собственного кода. Другими словами, при подготовке релиза убедитесь, что номер его версии точно отражает характер изменений с момента предыдущего релиза.

Рекомендации по обновлению основной версии

Вы должны обновляться до новой основной версии только тогда, когда это абсолютно необходимо. Обновление основной версии означает значительный переворот как для вас, так и для пользователей вашего модуля. Когда вы думаете об обновлении основной версии, подумайте о следующем:

• Сообщите своим пользователям, что выпуск новой основной версии означает для вас поддержку предыдущих основных версий.
• Предыдущие версии устарели? Поддерживаются как раньше? Будете ли вы поддерживать предыдущие версии, в том числе с исправлениями ошибок?
• Будьте готовы взять на себя обслуживание двух версий: старой и новой. Например, если вы исправляете ошибки в одной, вы часто будете переносить эти исправления в другой.
• Помните, что новая основная версия - это новый модуль с точки зрения управления зависимостями. Вашим пользователям необходимо будет выполнить обновление, чтобы использовать новый модуль после выпуска, а не просто выполнить обновление.
  Это потому, что в новой основной версии путь к модулю отличается от пути к предыдущей основной версии. Например, для модуля, чей путь к модулю - example.com/mymodule, версия v2 будет иметь путь к модулю example.com/mymodule/v2.
• При разработке новой основной версии вы также должны обновить пути импорта везде, где код импортирует пакеты из нового модуля. Пользователи вашего модуля также должны обновить свои пути импорта, если они хотят перейти на новую основную версию.

Разветвление для основного релиза

Самый простой подход к работе с исходным кодом при подготовке к разработке новой основной версии - это разветвление репозитория на последней версии предыдущей основной версии.

Например, в командной строке вы можете перейти в корневой каталог вашего модуля, а затем создать там новую ветку v2.

$ cd mymodule
$ git checkout -b v2
Switched to a new branch "v2"

Схема, показывающая репозиторий, ответвленный от master к v2:

После разветвления исходного кода вам необходимо внести следующие изменения в исходные файлы для вашей новой версии:

• В файле go.mod новой версии добавьте номер новой основной версии к пути к модулю, как в следующем примере:
  • Существующая версия: example.com/mymodule
  • Новая версия: example.com/mymodule/v2
• В коде Go обновите каждый импортированный путь к пакету, в который вы импортируете пакет из модуля, добавив номер основной версии к части пути к модулю.
  • Старый оператор импорта: import "example.com/mymodule/package1"
  • Новый оператор импорта: import "example.com/mymodule/v2/package1"

---

Читайте также:

• Создание модуля в Golang
• Управление зависимостями в Golang
• Разработка и публикация модулей в Golang
• Выпуск модуля и рабочий процесс управления версиями
• Управление исходным кодом модуля

Канал в Телеграм