Устаревание, отключение и удаление

Homebrew использует трёхэтапный жизненный цикл для удаления формул, cask-пакетов и собственного кода (методов Ruby, флагов CLI, переменных среды и команд):

1. Устаревший: больше не следует использовать. Пользователи видят предупреждение, но действие выполняется.
2. Отключённый: использовать нельзя. Пользователи видят ошибку, и действие завершается неудачей.
3. Удалённый: код или пакет удалён полностью.

Элементы, которые больше не соответствуют требованиям или отключены более года, следует удалить. Отключённые формулы в homebrew/core и отключённые cask-пакеты в homebrew/cask автоматически удаляются через год после даты отключения.

Формулы и cask-пакеты

Для перехода формул и cask-пакетов по жизненному циклу используются DSL deprecate! и disable!.

deprecate!

Добавьте вызов deprecate! с датой в формате ISO 8601 и причиной:

deprecate! date: "YYYY-MM-DD", because: :reason

• date: должна быть датой начала периода устаревания (обычно сегодняшним числом). Будущая дата отложит устаревание до указанного дня. Не указывайте прошедшую дату, так как это вызывает путаницу.
• because: может быть предопределённым символом или произвольной строкой (см. Причины устаревания и отключения).
• Необязательная строка replacement_formula: или replacement_cask: предлагает пользователю замену.

deprecate! date: "YYYY-MM-DD", because: :reason, replacement_formula: "foo"

disable!

Добавьте вызов disable! с теми же параметрами:

disable! date: "YYYY-MM-DD", because: :reason

• date: должна быть датой, когда вступила в силу причина отключения. Будущая дата означает, что формула или cask-пакет будет считаться устаревшим до этой даты, а затем будет отключён.
• replacement_formula: и replacement_cask: работают так же, как для deprecate!.

Когда следует объявлять формулы устаревшими

Формулы следует объявлять устаревшими, если выполняется хотя бы одно из следующих условий:

• формула не собирается ни в одной из поддерживаемых версий ОС
• в программном обеспечении есть нерешённые проблемы CVE
• разработка программного обеспечения прекращена или заброшена его основным разработчиком
• у формулы не было установок за последние 90 дней

Формулы, от которых зависят другие пакеты, не следует объявлять устаревшими, если только все зависимые от них пакеты также не объявлены устаревшими. Объявленные устаревшими формулы следует продолжать поддерживать, чтобы их по-прежнему можно было собирать из исходного кода и чтобы их бутылки продолжали работать. Если это невозможно, их следует отключить.

Когда следует объявлять cask-пакеты устаревшими

Cask-пакеты следует объявлять устаревшими, если выполняется хотя бы одно из следующих условий:

• программное обеспечение не проходит проверки macOS Gatekeeper в поддерживаемых версиях ОС
• программное обеспечение нельзя запустить ни в одной из поддерживаемых версий ОС
• в программном обеспечении есть нерешённые проблемы CVE
• разработка программного обеспечения прекращена или заброшена его основным разработчиком
• у cask-пакета не было установок за последние 90 дней

Объявленные устаревшими cask-пакеты следует продолжать поддерживать, если их по-прежнему можно установить. В противном случае их следует немедленно отключить.

Когда следует отключать формулы

Формулы следует отключать, если их невозможно собрать из исходного кода ни в одной поддерживаемой версии ОС, если они давно объявлены устаревшими или не имеют лицензии. Популярные формулы (более 1000 установок за последние 90 дней) не следует отключать без периода устаревания продолжительностью не менее шести месяцев. Непопулярные формулы можно отключить немедленно и удалить вручную через три месяца после даты отключения.

Когда следует отключать cask-пакеты

Cask-пакеты следует отключать, если их невозможно установить ни в одной поддерживаемой версии ОС, если они давно объявлены устаревшими или если их исходный URL удалён. Популярные cask-пакеты (более 300 установок за последние 90 дней) не следует отключать без периода устаревания продолжительностью не менее шести месяцев, если только проблему нельзя исправить. Непопулярные cask-пакеты можно отключить немедленно и удалить вручную через три месяца после даты отключения.

Когда следует удалять формулы

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

Когда следует удалять cask-пакеты

Cask-пакет следует удалить, если он отключён более года, или немедленно — в исключительных обстоятельствах.

Причины устаревания и отключения

При объявлении устаревания или отключении необходимо указать причину. Предпочтительный способ — использовать предопределённый символ из модуля DeprecateDisable. Также допускаются произвольные строки, которые должны подходить для предложения <name> has been deprecated/disabled because it <reason>!.

# Good: "fetches unversioned dependencies at runtime" fits the sentence
deprecate! date: "2020-01-01", because: "fetches unversioned dependencies at runtime"

# Bad: "invalid license" does not fit the sentence
disable! date: "2020-01-01", because: "invalid license"

Причины для формул:

• :does_not_build: невозможно собрать из исходного кода ни в одной поддерживаемой версии macOS или Linux
• :no_license: лицензию не удалось определить
• :repo_archived: репозиторий основного разработчика архивирован, пригодной замены нет
• :repo_removed: репозиторий основного разработчика удалён, пригодной замены нет
• :unmaintained: проект заброшен (коммитов не было год, а критические ошибки или проблемы CVE не устранены; примечание: некоторые программы считаются «завершёнными» — одно лишь отсутствие активности не является основанием для удаления)
• :unsupported: основной разработчик не поддерживает компиляцию (например, поддерживаются только версии macOS старше 10.15)
• :deprecated_upstream: основной разработчик объявил проект устаревшим, пригодной замены нет
• :versioned_formula: формула с версией, которая больше не соответствует требованиям
• :checksum_mismatch: контрольная сумма исходного кода изменилась после сборки бутылок без веского обоснования

Причины для cask-пакетов:

• :discontinued: основной разработчик прекратил поддержку
• :moved_to_mas: теперь доступен исключительно в Mac App Store
• :no_longer_available: больше недоступен у основного разработчика
• :no_longer_meets_criteria: больше не соответствует критериям приемлемых cask-пакетов
• :unmaintained: основной разработчик больше не поддерживает
• :fails_gatekeeper_check: не проходит проверки macOS Gatekeeper

Код

Homebrew также объявляет устаревшими, отключает и удаляет собственный код с помощью odeprecated/odisabled, а не DSL deprecate!/disable!.

Классификация API

Классификация API определяет, требуется ли период устаревания.

Публичные API должны пройти полный жизненный цикл устаревания до удаления:

• документированные переменные среды (например, переменные HOMEBREW_* на странице руководства)
• флаги CLI и команды, задокументированные на странице руководства
• методы Ruby с аннотацией @api public (отображаются в документации API Ruby)
• методы DSL, описанные в руководстве по формулам или руководстве по cask-пакетам

Внутренние API не требуют периода устаревания. Это методы в Homebrew/brew, используемые в homebrew/core или homebrew/cask, но не документированные для внешнего использования, либо специально помеченные аннотацией @api internal.

Приватные API не требуют периода устаревания. Это детали реализации в Homebrew/brew, которые никогда не используются за пределами самого Homebrew/brew. Они могут измениться в любой момент без предупреждения.

Когда следует объявлять код устаревшим

Публичные API (см. раздел Классификация API) следует объявлять устаревшими, если выполняется хотя бы одно из следующих условий:

• эта возможность больше не нужна в поддерживаемых версиях macOS или Linux
• существует более удачная замена, а старый API вызывает путаницу или увеличивает нагрузку на поддержку
• для этой возможности нет тестового покрытия Homebrew, и её используют только сторонние taps
• эта возможность приводит к непропорционально большому числу обращений в поддержку или сообщений об ошибках
• поведение небезопасно или поощряет действия, приводящие к неисправным установкам
• согласно аналитике или поиску по репозиторию, эта возможность не используется или используется крайне редко

Внутренние и приватные API (см. раздел Классификация API) можно изменять или удалять в любое время без предварительного объявления устаревшими.

Когда следует отключать код

Отключить устаревший публичный API (переместить из odeprecated в odisabled) следует в следующем минорном или мажорном выпуске после выпуска, в котором он был объявлен устаревшим. Это даёт пользователям как минимум один полный цикл выпуска на переход.

Когда следует удалять код

Отключённый код (odisabled) следует удалить в следующем минорном или мажорном выпуске после выпуска, в котором он был отключён.

Жизненный цикл устаревания

Публичные API проходят четыре этапа. Каждый переход выполняется в минорном или мажорном выпуске (например, 5.0.0 или 5.1.0), но не в исправляющем выпуске. Полный процесс выпуска описан в разделе Выпуски.

1. # odeprecated (закомментированная заглушка) — Добавляется комментарий-напоминание. Для пользователей ничего не меняется.

# odeprecated "ENV.no_weak_imports"
append "LDFLAGS", "-Wl,-no_weak_imports" if no_weak_imports_support?

2. odeprecated (активное устаревание) — Комментарий раскомментируется. Пользователи видят предупреждение; разработчики (HOMEBREW_DEVELOPER=1) видят ошибку. Можно предложить замену.

odeprecated "ENV.no_weak_imports"

3. odisabled (отключён) — Все пользователи видят ошибку.

odisabled "ENV.no_weak_imports"

4. Удаление — Вызов odisabled и весь связанный код удаляются.

Флаги CLI

Метод switch в анализаторе аргументов CLI принимает параметры odeprecated: и odisabled::

switch "--my-flag",
       description: "Do something.",
       odeprecated: true,
       replacement: "--new-flag"

Если задано odeprecated: true, флаг скрывается в --help и списках автодополнения, а при использовании выводится предупреждение. Если задано odisabled: true, при использовании флага возникает ошибка. На этапе удаления удалите определение флага и любой параметр replacement:.

Переменные среды

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

if (old_value = ENV["HOMEBREW_OLD_VAR"].presence)
  opoo "`HOMEBREW_OLD_VAR` is deprecated. Use `HOMEBREW_NEW_VAR` instead."
  # odeprecated "HOMEBREW_OLD_VAR", "HOMEBREW_NEW_VAR"
  ENV["HOMEBREW_NEW_VAR"] = old_value
end

Затем комментарий # odeprecated раскомментируется, заменяется на odisabled и в конце удаляется согласно стандартному жизненному циклу.