Рабочий процесс выпуска и версионирования модулей

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

Обзор разработки модулей см. в разделе Разработка и публикация модулей.

См. также

Если вы просто хотите использовать внешние пакеты в своем коде, обязательно ознакомьтесь с Управление зависимостями.
С каждой новой версией вы сигнализируете о изменениях в модуле с помощью его номера версии. Подробнее см. в разделе Нумерация версий модулей.

Общие шаги рабочего процесса

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

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

Если вы впервые разрабатываете модули, ознакомьтесь с Руководство: Создание Go-модуля.

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

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

См. Разработка кода против непубликуемого модуля для получения дополнительной информации о локальной разработке.
Когда код модуля будет готов для того, чтобы другие разработчики могли его протестировать, начните публиковать предварительные версии v0, такие как альфа- и бета-версии. Подробнее см. в разделе Публикация предварительных версий.
Выпустите v0, который не гарантирует стабильность, но может быть протестирован пользователями. Подробнее см. в разделе Публикация первой (нестабильной) версии.
После публикации версии v0 вы можете (и должны!) продолжать выпускать новые версии этого модуля.

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

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

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

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

Обновление мажорной версии — например, с v1.x.x на v2.x.x — может быть очень разрушительным обновлением для пользователей вашего модуля. Оно должно быть крайней мерой. Подробнее см. в разделе Публикация ломающих изменений API.

Разработка модуля до его публикации

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

Вы можете ссылаться на модуль локально из файла go.mod клиентского модуля, используя директиву replace в файле go.mod клиентского модуля. За дополнительной информацией обращайтесь к разделу Требование кода модуля из локального каталога.

Публикация предварительных версий

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

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

Вот два примера:

<code>v0.2.1-beta.1
v1.2.3-alpha
</code>

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

<code>go get example.com/theirmodule@v1.2.3-alpha
</code>

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

Публикация первой (нестабильной) версии

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

Нестабильные релизы — это те, номера версий которых находятся в диапазоне v0.x.x. Версия v0 не даёт никаких гарантий стабильности или обратной совместимости. Однако она даёт возможность получить обратную связь и улучшить ваш API до того, как вы дадите гарантии стабильности с версии v1 и выше. За дополнительной информацией обращайтесь к разделу Нумерация версий модулей.

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

Вот пример номера версии:

<code>v0.1.3
</code>

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

Публикация первой стабильной версии

Ваша первая стабильная версия будет иметь номер версии v1.x.x. Первая стабильная версия следует за предварительными релизами и версиями v0, через которые вы получали обратную связь, исправляли ошибки и стабилизировали модуль для пользователей.

С выходом версии v1 вы делаете следующие обязательства перед разработчиками, использующими ваш модуль:

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

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

Более подробно о номерах версий можно узнать в разделе Нумерация версий модулей.

Пример стабильного номера версии:

<code>v1.0.0
</code>

Вы публикуете первую стабильную версию, добавляя тег к коду модуля в вашем репозитории, указывая номер версии v1 в теге. Более подробно см. Публикация модуля.

Публикация исправлений ошибок

Вы можете опубликовать релиз, в котором изменения ограничены только исправлениями ошибок. Это называется патч-релизом.

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

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

Патч-релиз увеличивает патч-часть номера версии модуля. Подробнее см. Нумерация версий модулей.

В следующем примере v1.0.1 — это патч-релиз.

Старая версия: v1.0.0

Новая версия: v1.0.1

Вы публикуете патч-релиз, добавляя тег к коду модуля в вашем репозитории, увеличивая номер патч-версии в теге. Подробнее см. Публикация модуля.

Публикация непрерывающих изменений API

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

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

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

В следующем примере показан мажорный выпуск: v1.1.0.

Старая версия: v1.0.1

Новая версия: v1.1.0

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

Публикация изменений, нарушающих обратную совместимость

Вы можете опубликовать версию, нарушающую обратную совместимость, опубликовав мажорный выпуск версии.

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

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

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

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

Один из способов — создать новую ветку в репозитории, специально предназначенную для новой мажорной версии и последующих мажорных и патч-версий. За дополнительной информацией обращайтесь к разделу Управление исходным кодом модуля.
В файле go.mod модуля измените путь модуля, добавив номер новой мажорной версии, как показано в следующем примере:
```
<code>example.com/mymodule/v2
</code>
```
Поскольку путь модуля является его идентификатором, это изменение фактически создаёт новый модуль. Оно также изменяет путь пакета, гарантируя, что разработчики случайно не импортируют версию, которая нарушает их код. Вместо этого те, кто хочет обновиться, явно заменят старый путь на новый.
В вашем коде измените пути пакетов, где вы импортируете пакеты из модуля, который вы обновляете, включая пакеты внутри самого обновляемого модуля. Это необходимо, потому что вы изменили путь модуля.
Как и в случае с любым новым выпуском, вы должны публиковать предварительные версии, чтобы получить отзывы и сообщения об ошибках до публикации официального выпуска.
Опубликуйте новую мажорную версию, добавив тег к коду модуля в вашем репозитории, увеличив номер мажорной версии в теге — например, с v1.5.2 на v2.0.0.

За дополнительной информацией обращайтесь к разделу Публикация модуля.