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

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

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

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

См. также

Если вы используете внешние пакеты в своём коде, вы можете управлять этими зависимостями с помощью инструментов Go. Подробнее см. Управление зависимостями.
Если вы разрабатываете модули для использования другими разработчиками, вы применяете номер версии при публикации модуля, помечая модуль в его репозитории. Подробнее см. Публикация модуля.

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

Diagram illustrating a semantic version number showing major version 1, minor version 4, patch version 0, and pre-release version beta 2

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

Этап версии	Пример	Сообщение для разработчиков
В разработке	Автоматический псевдономер версии v0.x.x	Сигнализирует, что модуль всё ещё в разработке и нестабилен. Этот выпуск не даёт гарантий обратной совместимости или стабильности.
Основная версия	v1.x.x	Сигнализирует об несовместимых с предыдущими версиями публичных изменениях API. Этот выпуск не гарантирует обратную совместимость с предыдущими основными версиями.
Дополнительная версия	vx.4.x	Сигнализирует о совместимых с предыдущими версиями публичных изменениях API. Этот выпуск гарантирует обратную совместимость и стабильность.
Патч-версия	vx.x.1	Сигнализирует о изменениях, не affecting публичного 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.

Предрелизная версия

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

Пример

<code>vx.x.x-beta.2
</code>

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

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

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

Пример

<code>vx.4.x
</code>

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

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

Патч-версия

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

Пример

<code>vx.x.1
</code>

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

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

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

Пример

v1.x.x

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

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

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

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

<code>module example.com/mymodule/v2 v2.0.0
</code>

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

Более подробную информацию о директиве module см. в Справочнике по go.mod.