diff --git a/Library/Homebrew/cask/cask.rbi b/Library/Homebrew/cask/cask.rbi index 9ffa1b2428119..e1135bf85c81c 100644 --- a/Library/Homebrew/cask/cask.rbi +++ b/Library/Homebrew/cask/cask.rbi @@ -26,6 +26,8 @@ module Cask def deprecation_reason; end + def deprecation_period; end + def disabled?; end def disable_date; end diff --git a/Library/Homebrew/cask/dsl.rb b/Library/Homebrew/cask/dsl.rb index bb5d36cf7ec44..12867879d8b58 100644 --- a/Library/Homebrew/cask/dsl.rb +++ b/Library/Homebrew/cask/dsl.rb @@ -87,6 +87,7 @@ class DSL :deprecated?, :deprecation_date, :deprecation_reason, + :deprecation_period, :disable!, :disabled?, :disable_date, @@ -105,7 +106,13 @@ class DSL extend Attrable include OnSystem::MacOSOnly - attr_reader :cask, :token, :deprecation_date, :deprecation_reason, :disable_date, :disable_reason, + attr_reader :cask, + :token, + :deprecation_date, + :deprecation_reason, + :disable_date, + :disable_reason, + :deprecation_period, :on_system_block_min_os attr_predicate :deprecated?, :disabled?, :livecheckable?, :on_system_blocks_exist?, :depends_on_set_in_block? @@ -442,10 +449,11 @@ def livecheck(&block) # NOTE: A warning will be shown when trying to install this cask. # # @api public - def deprecate!(date:, because:) + def deprecate!(date:, because:, deprecation_period: :long) @deprecation_date = Date.parse(date) return if @deprecation_date > Date.today + @deprecation_period = deprecation_period @deprecation_reason = because @deprecated = true end diff --git a/Library/Homebrew/deprecate_disable.rb b/Library/Homebrew/deprecate_disable.rb index c83f26ee74c3b..a227e084c6d1d 100644 --- a/Library/Homebrew/deprecate_disable.rb +++ b/Library/Homebrew/deprecate_disable.rb @@ -30,9 +30,13 @@ module DeprecateDisable unsigned: "is unsigned or does not meet signature requirements", }.freeze + DEPRECATE_PERIOD_MONTHS = { + short: 1, + long: 6, + }.freeze + # One year when << or >> to Date.today. REMOVE_DISABLED_TIME_WINDOW = 12 - REMOVE_DISABLED_BEFORE = (Date.today << REMOVE_DISABLED_TIME_WINDOW).freeze def type(formula_or_cask) return :deprecated if formula_or_cask.deprecated? @@ -65,7 +69,8 @@ def message(formula_or_cask) disable_date = formula_or_cask.disable_date if !disable_date && formula_or_cask.deprecation_date - disable_date = formula_or_cask.deprecation_date >> REMOVE_DISABLED_TIME_WINDOW + period = DEPRECATE_PERIOD_MONTHS[formula_or_cask.deprecation_period] + disable_date = formula_or_cask.deprecation_date >> period end if disable_date message += if disable_date < Date.today diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index 30072c2298cd7..8493182460d49 100644 --- a/Library/Homebrew/formula.rb +++ b/Library/Homebrew/formula.rb @@ -1536,6 +1536,13 @@ def link_overwrite?(path) # @see .deprecate! delegate deprecation_reason: :"self.class" + # The time before the {Formula} becomes disabled + # Returns `nil` if no date is specified. + # @!method deprecation_period + # @return [String, Symbol] + # @see .deprecate! + delegate deprecation_period: :"self.class" + # Whether this {Formula} is disabled (i.e. cannot be installed). # Defaults to false. # @!method disabled? @@ -4225,10 +4232,11 @@ def pour_bottle?(only_if: nil, &block) # @see https://docs.brew.sh/Deprecating-Disabling-and-Removing-Formulae # @see DeprecateDisable::FORMULA_DEPRECATE_DISABLE_REASONS # @api public - def deprecate!(date:, because:) + def deprecate!(date:, because:, deprecation_period: :long) @deprecation_date = Date.parse(date) return if @deprecation_date > Date.today + @deprecation_period = deprecation_period @deprecation_reason = because @deprecated = true end @@ -4255,6 +4263,13 @@ def deprecated? # @see .deprecate! attr_reader :deprecation_reason + # The time before the {Formula} becomes disabled. + # + # @return [nil] if no reason was provided or the formula is not deprecated. + # @return [String, Symbol] + # @see .deprecate! + attr_reader :deprecation_period + # Disables a {Formula} (on the given date) so it cannot be # installed. If the date has not yet passed the formula # will be deprecated instead of disabled. diff --git a/docs/Deprecating-Disabling-and-Removing-Formulae.md b/docs/Deprecating-Disabling-and-Removing-Formulae.md index 5282a6ecbf8b6..dcb4e0a887573 100644 --- a/docs/Deprecating-Disabling-and-Removing-Formulae.md +++ b/docs/Deprecating-Disabling-and-Removing-Formulae.md @@ -30,13 +30,15 @@ Formulae with dependents should not be deprecated until or when all dependents a To deprecate a formula, add a `deprecate!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason: ```ruby -deprecate! date: "YYYY-MM-DD", because: :reason +deprecate! date: "YYYY-MM-DD", because: :reason, deprecation_period: :short ``` The `date` parameter should be set to the date that the deprecation period should begin, which is usually today's date. If the `date` parameter is set to a date in the future, the formula will not become deprecated until that date. This can be useful if the upstream developers have indicated a date when the project or version will stop being supported. Do not backdate the `date` parameter as it causes confusion for users and maintainers. The `because` parameter can be a preset reason (using a symbol) or a custom reason. See the [Deprecate and Disable Reasons](#deprecate-and-disable-reasons) section below for more details about the `because` parameter. +The `deprecation_period:` can be either :short or :long (1 or 6 months). After this period a formula should be disabled. + ## Disabling If a user attempts to install a disabled formula, they will be shown an error message and the install will fail. @@ -49,10 +51,9 @@ The most common reasons for disabling a formula are: - it has been deprecated for a long time - the project has no license -Popular formulae (e.g. have more than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) should not be disabled without a deprecation period of at least six months even if e.g. they do not build from source and do not have a license. +Popular formulae (e.g. have more than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) should not be disabled without a deprecation period of six months even if e.g. they do not build from source and do not have a license. -Unpopular formulae (e.g. have fewer than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) can be disabled immediately for any of the reasons above e.g. they cannot be built from source on any supported macOS version or Linux. -They can be manually removed three months after their disable date. +Unpopular formulae (e.g. have fewer than 1000 [analytics installs in the last 90 days](https://formulae.brew.sh/analytics/install/90d/)) can be disabled after one month for any of the reasons above e.g. they cannot be built from source on any supported macOS version or Linux. To disable a formula, add a `disable!` call. This call should include a deprecation date in the ISO 8601 format and a deprecation reason: