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

Существует множество причин, по которым формулы могут быть устаревшими, отключенными или удалёнными. Этот документ объясняет различия между каждым методом, а также объясняет, когда следует использовать один метод вместо другого.

Обзор

Можно следовать этому общему правилу:

• deprecate! следует использовать для формул, которые больше не должны использоваться.
• disable! следует использовать для формул, которые нельзя использовать.
• Формулы, которые больше не допускаются в homebrew/core или были отключены более года, должны быть удалены.

Устаревание

Если пользователь пытается установить устаревшую формулу, ему будет показано предупреждающее сообщение, но установка продолжится.

Формула должна быть устаревшей, чтобы сообщить пользователям, что её не следует использовать и что она будет отключена в будущем. Устаревшие формулы должны поддерживаться разработчиками Homebrew, чтобы они могли по-прежнему компилироваться из исходного кода, и их бутылки продолжали работать (даже если upstream не поддерживается). Если это невозможно, они должны быть отключены.

Наиболее распространёнными причинами устаревания являются устаревание, отсутствие поддержки или архивирование проекта upstream.

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

• все её зависимые формулы также устарели
• формула не компилируется ни на одной из поддерживаемых нами версий macOS и Linux
• формула имеет открытые CVE

Чтобы устареть формулу, добавьте вызов deprecate!. Этот вызов должен включать дату устаревания (в формате ISO 8601) и причину устаревания:

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

Параметр date должен быть установлен на дату, когда проект или версия стали (или станут) устаревшими. Если нет ясной даты, но формула должна быть устаревшей, используйте сегодняшнюю дату. Если параметр date установлен на будущую дату, формула не станет устаревшей до этой даты. Это может быть полезно, если разработчики upstream указали дату, когда проект или версия перестанут поддерживаться.

Параметр because может быть предопределённой причиной (используя символ) или пользовательской причиной. См. раздел Причины устаревания и отключения ниже для получения дополнительной информации о параметре because.

Отключение

Если пользователь пытается установить отключённую формулу, ему будет показано сообщение об ошибке, и установка завершится неудачей.

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

Наиболее распространёнными причинами отключения формулы являются:

• она не может быть скомпилирована из исходного кода (что означает, что бутылки не могут быть созданы)
• она была устаревшей в течение длительного времени
• репозиторий upstream был удалён
• у проекта нет лицензии

Формулы не должны отключаться без периода устаревания не менее трёх месяцев, если обстоятельства не являются исключительными (например, формула не компилируется ни на одной из поддерживаемых версий macOS или Linux). У популярных формул должны быть более длительные периоды устаревания. Популярность формулы должна основываться на наших аналитических данных.

Примечание: отключённые формулы в homebrew/core будут автоматически удалены через год после даты их отключения

Чтобы отключить формулу, добавьте вызов disable!. Этот вызов должен включать дату устаревания (в формате ISO 8601) и причину устаревания:

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

Параметр date должен быть установлен на дату, когда причина отключения вступила в силу. Если нет ясной даты, но формула должна быть отключена, используйте сегодняшнюю дату. Если параметр date установлен на будущую дату, формула будет устаревать до этой даты (в которую формула будет отключена).

Параметр because может быть предопределённой причиной (используя символ) или пользовательской причиной. См. раздел Причины устаревания и отключения ниже для получения дополнительной информации о параметре because.

Удаление

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

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

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

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

• :does_not_build: формула не может быть скомпилирована из исходного кода
• :no_license: у формулы нет лицензии
• :repo_archived: репозиторий upstream был архивирован
• :repo_removed: репозиторий upstream был удалён
• :unmaintained: проект, похоже, заброшен
• :unsupported: применение программного обеспечения Homebrew не поддерживается разработчиками upstream (например, upstream поддерживает только версии macOS до 10.14)
• :deprecated_upstream: проект устарел в upstream
• :versioned_formula: формула является формулой с версиями

Эти причины можно указать по их символам (в комментариях показано сообщение, которое будет отображено пользователям):

# Warning: <formula> has been deprecated because it is deprecated upstream!
deprecate! date: "2020-01-01", because: :deprecated_upstream

# Error: <formula> has been disabled because it does not build!
disable! date: "2020-01-01", because: :does_not_build

Если эти существующие причины не подходят, можно указать пользовательскую причину. Эти причины должны быть написаны для соответствия предложению <formula> has been deprecated/disabled because it <reason>!.

Хороший пример пользовательской причины:

# Warning: <formula> has been deprecated because it fetches unversioned dependencies at runtime!
deprecate! date: "2020-01-01", because: "fetches unversioned dependencies at runtime"

Плохой пример пользовательской причины:

# Error: <formula> has been disabled because it invalid license!
disable! date: "2020-01-01", because: "invalid license"