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

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

Примечание: Каждый тип релиза – мажорный, минорный, патч или предрелиз – имеет разное значение для пользователей модуля. Эти пользователи полагаются на эти различия, чтобы понимать уровень риска, связанный с конкретным релизом, для их собственного кода. Иными словами, при подготовке релиза убедитесь, что номер версии точно отражает характер изменений по сравнению с предыдущим релизом. Более подробную информацию о номерах версий см. в разделе Нумерация версий модулей.

См. также

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

Рассмотрение вопросов при обновлении до мажорной версии

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

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

  Устарели ли предыдущие версии? Поддерживаются ли они так же, как раньше? Будете ли вы поддерживать предыдущие версии, включая исправления ошибок?

• Будьте готовы к тому, что вам придётся поддерживать две версии: старую и новую. Например, если вы исправляете ошибки в одной версии, часто вам придётся переносить эти исправления в другую.

• Убедитесь, что ваша команда готова к тому, чтобы поддерживать несколько версий одновременно. Это может включать в себя выпуск исправлений, тестирование и документирование.

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

  Это связано с тем, что новый мажорный релиз имеет другой путь модуля по сравнению с предыдущим мажорным релизом. Например, для модуля, чей путь модуля — example.com/mymodule, версия v2 будет иметь путь модуля example.com/mymodule/v2.

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

Ветвление для мажорного релиза

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

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

<code>$ cd mymodule
$ git checkout -b v2
Switched to a new branch "v2"
</code>

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

• В файле go.mod новой версии добавьте номер нового мажорного релиза к пути модуля, как показано в следующем примере:

  • Текущая версия: example.com/mymodule
  • Новая версия: example.com/mymodule/v2

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

  • Старая инструкция импорта: import "example.com/mymodule/package1"
  • Новая инструкция импорта: import "example.com/mymodule/v2/package1"

Для шагов публикации см. Publishing a module.