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

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

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

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

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

Когда вы используете внешние пакеты в своем коде, вы можете управлять этими зависимостями с помощью инструментов 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

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