Директива retract указывает версию или диапазон версий модуля, определенных go.mod, от которых не следует зависеть. Директива retract полезна, когда версия была опубликована преждевременно или после публикации версии была обнаружена серьезная проблема. Отозванные (Retracted) версии должны оставаться доступными в репозиториях системы контроля версий и на прокси-серверах модулей, чтобы гарантировать, что сборки, зависящие от них, не будут повреждены. Слово retract заимствовано из академической литературы: отозванная (retracted) исследовательская статья все еще доступна, но она имеет проблемы и не должна быть основой для будущей работы.
Когда версия модуля отозвана, пользователи не будут обновляться до нее автоматически с помощью go get, go mod tidy или других команд. Сборки, зависящие от отозванных версий, должны продолжать работать, но пользователи будут уведомлены об отзывах (retractions), когда они проверят наличие обновлений с помощью go list -m -u или обновят связанный модуль с помощью go get.
Чтобы отозвать версию, автор модуля должен добавить директиву retract в go.mod, а затем опубликовать новую версию, содержащую эту директиву. Новая версия должна быть выше, чем другие релизные или предварительные версии; то есть, запрос @latest версии должен разрешить новую версию до рассмотрения отзыва. Команда go загружает и применяет отзывы из версии, показанной go list -m -retracted $modpath@latest (где $modpath - это путь к модулю).
Отозванные версии скрываются из списка версий, выводимого командой go list -m -versions, если не используется флаг -retracted. Отозванные версии исключаются при разрешении запросов о версиях, таких как @>=v1.2.3 или @latest.
Версия, содержащая отзывы, может отозваться сама. Если самый высокий релиз или предварительная версия модуля удаляется, запрос @latest преобразуется в более низкую версию после исключения отозванных версий.
В качестве примера рассмотрим случай, когда автор модуля example.com/m случайно публикует версию v1.0.0. Чтобы предотвратить обновление пользователей до версии 1.0.0, автор может добавить две директивы retract в go.mod, а затем пометить версию 1.0.1 отзывами.
retract (
v1.0.0 // Опубликовано случайно.
v1.0.1 // Содержит только отзывы.
)
Когда пользователь запускает go get example.com/m@latest, команда go считывает отзывы из v1.0.1, которая теперь является самой высокой версией. И v1.0.0, и v1.0.1 отозваны, поэтому команда go обновит (или откатит!) до следующей высшей версии, возможно, v0.9.5.
Директивы retract могут быть написаны либо с одной версией (например, v1.0.0), либо с закрытым интервалом версий с верхней и нижней границами, разделенными символом [ и символом ] (например, [v1.1.0, v1.2.0]). Единая версия эквивалентна интервалу, в котором верхняя и нижняя границы совпадают. Как и другие директивы, несколько директив retract могут быть сгруппированы в блок, разделенный символом ( в конце строки и символом ) на отдельной строке.
В каждой директиве retract должен быть комментарий, объясняющий причину отзыва, хотя это не обязательно. Команда go может отображать комментарии с обоснованием в предупреждениях об отозванных версиях и в выводе go list. Обосновывающий комментарий может быть написан непосредственно над директивой retract (без пустой строки между ними) или после в той же строке. Если комментарий появляется над блоком, он применяется ко всем директивам retract внутри блока, у которых нет собственных комментариев. Комментарий-обоснование может занимать несколько строк.
RetractDirective = "retract" ( RetractSpec | "(" newline { RetractSpec } ")" ) .
RetractSpec = ( Version | "[" Version "," Version "]" ) newline .
Пример:
retract v1.0.0
retract [v1.0.0, v1.9.9]
retract (
v1.0.0
[v1.0.0, v1.9.9]
)
Директива retract была добавлена в Go 1.16. Go 1.15 и ниже будет сообщать об ошибке, если директива retract записана в файле go.mod главного модуля, и игнорирует директивы retract в файлах go.mod зависимостей.
Пример использования rectract - https://github.com/A1esandr/retract
Читайте также:
- Модули в Golang: файл go.mod, грамматика
- Модули в Golang: команды с поддержкой модулей, go get
- Модули в Golang: команды с поддержкой модулей, go list -m
Комментариев нет:
Отправить комментарий