При разработке модулей для использования другими разработчиками вы можете следовать рабочему процессу, который помогает обеспечить надежную и единообразную работу разработчиков, использующих модуль. В этом посте описаны высокоуровневые шаги этого рабочего процесса.
Обзор разработки модулей смотрите в посте Разработка и публикация модулей.
Если вы просто хотите использовать внешние пакеты в своем коде, обязательно ознакомьтесь с постом Управление зависимостями.
С каждой новой версией вы сигнализируете об изменениях в вашем модуле его номером версии.
Общие шаги рабочего процесса
Следующая последовательность иллюстрирует шаги рабочего процесса выпуска и управления версиями для примера нового модуля.
- Начните модуль и организуйте его исходный код, чтобы разработчикам было проще его использовать, а вам - поддерживать.
Если вы новичок в разработке модулей, ознакомьтесь с Созданием модуля Go. - Настройте для написания кода локального клиента, который вызывает функции в неопубликованном модуле.
Перед публикацией модуля он недоступен для обычного рабочего процесса управления зависимостями с использованием таких команд, как go get. Хороший способ протестировать код вашего модуля на этом этапе - это попробовать его, пока он находится в каталоге, локальном для вашего вызывающего кода. - Когда код модуля будет готов для других разработчиков, начните публиковать предварительные версии v0, такие как альфа- и бета-версии.
- Выпустите версию v0, стабильность которой не гарантируется, но пользователи могут попробовать ее.
- После публикации вашей версии v0 вы можете (и следует) продолжать выпускать ее новые версии.
Эти новые версии могут включать исправления ошибок (релизы патчей), дополнения к общедоступному API модуля (минорные релизы) и даже критические изменения. Поскольку релиз v0 не дает никаких гарантий стабильности или обратной совместимости, вы можете вносить критические изменения в его версии. - Когда вы готовите стабильную версию, готовую к релизу, вы публикуете предварительные релизы как альфа- и бета-версии.
- Выпустите v1 как первый стабильный релиз.
Это первый релиз, в котором говорится о стабильности модуля. - В версии v1 продолжайте исправлять ошибки и, при необходимости, вносить дополнения в общедоступный API модуля.
- Если этого невозможно избежать, опубликуйте ломающие изменения в новой основной версии.
Обновление основной версии - например, с v1.x.x до v2.x.x - может сильно помешать пользователям вашего модуля. Это должно быть последнее средство.
Кодирование неопубликованного модуля
Когда вы начинаете разрабатывать модуль или новую версию модуля, вы еще не опубликовали его. Перед публикацией модуля вы не сможете использовать команды Go для добавления модуля в качестве зависимости. Вместо этого сначала при написании клиентского кода в другом модуле, который вызывает функции в неопубликованном модуле, вам нужно будет ссылаться на копию модуля в локальной файловой системе.
Вы можете ссылаться на модуль локально из файла go.mod клиентского модуля, используя директиву replace в файле go.mod клиентского модуля.
Публикация предварительных версий
Вы можете опубликовать предварительные версии, чтобы сделать модуль доступным для других, чтобы опробовать его и оставить отзыв. Предварительная версия не дает никаких гарантий стабильности.
К номерам предварительной версии добавляется идентификатор предварительной версии.
Вот два примера:
- v0.2.1-beta.1
- v1.2.3-alpha
Делая предварительную версию доступной, имейте в виду, что разработчики, использующие предварительную версию, должны будут явно указать ее по версии с помощью команды go get. Это потому, что по умолчанию команда go отдает предпочтение релизным версиям перед предварительными версиями при поиске запрашиваемого модуля. Поэтому разработчики должны получить предварительную версию, явно указав ее, как в следующем примере:
go get example.com/theirmodule@v1.2.3-alpha
Вы публикуете предварительную версию, помечая код модуля в своем репозитории, указывая идентификатор предварительной версии в теге.
Публикация первой (нестабильной) версии
Как и при публикации предварительной версии, вы можете публиковать релизные версии, которые не гарантируют стабильность или обратную совместимость, но дают вашим пользователям возможность опробовать модуль и оставить отзыв.
Нестабильные релизы - это те, номера версий которых находятся в диапазоне v0.x.x. Версия v0 не дает никаких гарантий стабильности или обратной совместимости. Но это дает вам возможность получить обратную связь и усовершенствовать свой API, прежде чем брать на себя обязательства по стабильности с v1 и более поздними версиями.
Как и в случае с другими опубликованными версиями, вы можете увеличивать минорную часть и патч часть номера версии v0 по мере внесения изменений в выпуск стабильной версии v1. Например, после выпуска v0.0.0 вы можете выпустить v0.0.1 с первым набором исправлений ошибок.
Вот пример номера версии:
v0.1.3
Вы публикуете нестабильный релиз, отмечая код модуля в своем репозитории, указывая в теге номер версии v0.
Публикация первой стабильной версии
Ваш первый стабильный релиз будет иметь номер версии v1.x.x. Первый стабильный релиз следует за предварительным релизом и релизом v0, благодаря которым вы получили отзывы, исправили ошибки и стабилизировали модуль для пользователей.
С выпуском v1 вы берете на себя следующие обязательства перед разработчиками, использующими ваш модуль:
- Они могут перейти на последующие второстепенные (минорные) релизы и релизы исправлений (патч) основной версии, не нарушая собственный код.
- Вы не будете вносить дальнейшие изменения в общедоступный API модуля, включая его функции и сигнатуры методов, которые нарушают обратную совместимость.
- Вы не будете удалять экспортированные типы, так как это нарушит обратную совместимость.
- Будущие изменения в вашем API (например, добавление нового поля в структуру) будут обратно совместимы и будут включены в новый минорный релиз.
- Исправления ошибок (например, исправления безопасности) будут включены в релиз исправлений или как часть минорного релиза.
Примечание. Хотя ваша первая основная версия может быть релизом v0, версия v0 не дает никаких гарантий стабильности или обратной совместимости. В результате при увеличении от v0 до v1 вам не нужно помнить о нарушении обратной совместимости, потому что релиз v0 не считался стабильным.
Вот пример номера стабильной версии:
v1.0.0
Вы публикуете первый стабильный релиз, помечая код модуля в своем репозитории, указывая номер версии v1 в теге.
Публикация исправлений ошибок
Вы можете опубликовать релиз, в котором изменения ограничиваются исправлением ошибок. Это известно как релиз исправлений (патч релиз).
Релиз исправлений включает только незначительные изменения. В частности, он не содержит изменений в общедоступном API модуля. Разработчики потребляющего кода могут обновиться до этой версии безопасно и без необходимости изменять свой код.
Примечание. В вашем релизе исправлений не следует пытаться обновлять какие-либо собственные транзитивные зависимости этого модуля более чем на релиз исправлений. В противном случае кто-то, обновившийся до патча вашего модуля, может случайно внести более агрессивное изменение в используемую им транзитивную зависимость.
Релиз исправлений увеличивает часть исправления номера версии модуля.
В следующем примере v1.0.1 - это релиз исправлений.
Старая версия: v1.0.0
Новая версия: v1.0.1
Вы публикуете релиз исправлений, отмечая код модуля в своем репозитории, увеличивая номер версии исправления в теге.
Публикация не-ломающих изменений API
Вы можете внести не-ломающие изменения в общедоступный API вашего модуля и опубликовать эти изменения в релизе минорной версии.
Эта версия изменяет API, но не таким образом, чтобы нарушать вызывающий код. Это может включать изменения собственных зависимостей модуля или добавление новых функций, методов, полей структур или типов. Даже с внесенными в него изменениями этот вид релиза гарантирует обратную совместимость и стабильность для существующего кода, который вызывает функции модуля.
Минорный релиз увеличивает минорную часть номера версии модуля.
В следующем примере v1.1.0 является минорным релизом.
Старая версия: v1.0.1
Новая версия: v1.1.0
Вы публикуете минорный релиз, отмечая код модуля в своем репозитории, увеличивая минорный номер версии в теге.
Публикация ломающих изменений API
Вы можете опубликовать версию, которая нарушает обратную совместимость, опубликовав релиз основной версии.
Релиз основной версии не гарантирует обратной совместимости, как правило, потому, что он включает изменения в общедоступном API модуля, которые нарушили бы код, использующий предыдущие версии модуля.
Учитывая разрушительный эффект, который обновление основной версии может оказать на код, зависящий от модуля, вам следует по возможности избегать обновления основной версии.
Если для публикации других типов версий требуется по существу пометить код модуля номером версии, публикация обновления основной версии требует дополнительных шагов.
- Перед началом разработки новой основной версии создайте в своем репозитории место для исходного кода новой версии.
Один из способов сделать это - создать новую ветку в вашем репозитории, специально предназначенную для новой основной версии и ее последующих минорных версий и версий исправлений. -
В файле модуля go.mod измените путь к модулю, чтобы добавить новый основной номер версии, как в следующем примере:
Учитывая, что путь к модулю является идентификатором модуля, это изменение фактически создает новый модуль. Он также изменяет путь к пакету, гарантируя, что разработчики не будут непреднамеренно импортировать версию, нарушающую их код. Вместо этого те, кто хочет обновить, будут явно заменять вхождения старого пути новым.example.com/mymodule/v2
- В своем коде измените все пути к пакетам, в которые вы импортируете пакеты в обновляемом модуле, включая пакеты в модуле, который вы обновляете. Вам нужно сделать это, потому что вы изменили путь к модулю.
- Как и в случае с любым новым выпуском, перед публикацией официального выпуска вам следует публиковать предварительные версии, чтобы получать отзывы и отчеты об ошибках.
- Опубликуйте новую основную версию, пометив код модуля в своем репозитории, увеличив номер основной версии в теге - например, с v1.5.2 до v2.0.0.
Читайте также:
- Создание модуля в Golang
- Новые изменения модулей в Go 1.16
- Управление зависимостями в Golang
- Разработка и публикация модулей в Golang
Комментариев нет:
Отправить комментарий