Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

info: change disabled dates #18551

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions Library/Homebrew/cask/cask.rbi
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ module Cask

def deprecation_reason; end

def deprecation_period; end

def disabled?; end

def disable_date; end
Expand Down
12 changes: 10 additions & 2 deletions Library/Homebrew/cask/dsl.rb
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ class DSL
:deprecated?,
:deprecation_date,
:deprecation_reason,
:deprecation_period,
:disable!,
:disabled?,
:disable_date,
Expand All @@ -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?
Expand Down Expand Up @@ -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
Expand Down
9 changes: 7 additions & 2 deletions Library/Homebrew/deprecate_disable.rb
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,13 @@
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?
Expand Down Expand Up @@ -65,7 +69,8 @@

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

Check warning on line 73 in Library/Homebrew/deprecate_disable.rb

View check run for this annotation

Codecov / codecov/patch

Library/Homebrew/deprecate_disable.rb#L73

Added line #L73 was not covered by tests
end
if disable_date
message += if disable_date < Date.today
Expand Down
17 changes: 16 additions & 1 deletion Library/Homebrew/formula.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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?
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down
9 changes: 5 additions & 4 deletions docs/Deprecating-Disabling-and-Removing-Formulae.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:

Expand Down
Loading