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.

Sign up for GitHub

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

Jump to bottom

Add deprecate! and disable! to cask docs #16354

Merged
merged 1 commit into from
Dec 20, 2023
Merged

Add deprecate! and disable! to cask docs #16354

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/Brew-Livecheck.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,7 +348,7 @@ end

### `skip`

Livecheck automatically skips some formulae/casks for a number of reasons (deprecated, disabled, discontinued, etc.). However, on rare occasions we need to use a `livecheck` block to do a manual skip. The `skip` method takes a string containing a very brief reason for skipping.
Livecheck automatically skips some formulae/casks for a number of reasons (deprecated, disabled, etc.). However, on rare occasions we need to use a `livecheck` block to do a manual skip. The `skip` method takes a string containing a very brief reason for skipping.

```ruby
livecheck do
Expand Down
43 changes: 42 additions & 1 deletion docs/Cask-Cookbook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,9 @@ Having a common order for stanzas makes casks easier to update and parse. Below

livecheck

deprecate!
disable!

auto_updates
conflicts_with
depends_on
Expand Down Expand Up @@ -153,6 +156,8 @@ Each cask must declare one or more *artifacts* (i.e. something to install).
| [`uninstall`](#stanza-uninstall) | yes | Procedures to uninstall a cask. Optional unless the `pkg` stanza is used. |
| [`conflicts_with`](#stanza-conflicts_with) | yes | List of conflicts with this cask (*not yet functional*). |
| [`caveats`](#stanza-caveats) | yes | String or Ruby block providing the user with cask-specific information at install time. |
| [`deprecate!`](#stanza-deprecate--disable) | no | Date as a String in `YYYY-MM-DD` format and a String or Symbol providing a reason. |
| [`disable!`](#stanza-deprecate--disable) | no | Date as a String in `YYYY-MM-DD` format and a String or Symbol providing a reason. |
| `preflight` | yes | Ruby block containing preflight install operations (needed only in very rare cases). |
| [`postflight`](#stanza-flight) | yes | Ruby block containing postflight install operations. |
| `uninstall_preflight` | yes | Ruby block containing preflight uninstall operations (needed only in very rare cases). |
Expand Down Expand Up @@ -280,7 +285,6 @@ The following methods may be called to generate standard warning messages:
| `logout` | Users should log out and log back in to complete installation. |
| `reboot` | Users should reboot to complete installation. |
| `files_in_usr_local` | The cask installs files to `/usr/local`, which may confuse Homebrew. |
| `discontinued` | All software development has been officially discontinued upstream. |
| `kext` | Users may need to enable their kexts in *System Settings → Privacy & Security* (or *System Preferences → Security & Privacy → General* in earlier macOS versions). |
| `unsigned_accessibility` | Users will need to re-enable the app on each update in *System Settings → Privacy & Security* (or *System Preferences → Security & Privacy → Privacy* in earlier macOS versions) as it is unsigned. |
| `license "web_page"` | Users may find the software's usage license at `web_page`. |
Expand All @@ -294,6 +298,43 @@ caveats do
end
```

### Stanza: `deprecate!` / `disable!`

`deprecate!` and `disable!` are used to declare that a cask is no longer functional or supported.
Casks that contain a `deprecate!` stanza can still be installed, but will print a warning message when they are installed or upgraded.
Casks that contain a `disable!` stanza cannot be installed or upgraded and will print an error message.

The syntax for both stanzas is the same:

```ruby
deprecate! date: "YYYY-MM-DD", because: "is ..."
disable! date: "YYYY-MM-DD", because: "is ..."

# Or with a preset reason (see the `because:` argument section below)
deprecate! date: "YYYY-MM-DD", because: :discontinued
disable! date: "YYYY-MM-DD", because: :discontinued
```

#### `date:` argument

The `date:` argument controls when the deprecation or disabling will take effect.
Casks that have a `deprecate!` stanza with a date in the future will not be treated as being deprecated until that date.
Casks that have a `disable!` stanza with a date in the future will be automatically deprecated until that date, at which point they will be disabled.

#### `because:` argument

The `because:` argument accepts a reason for the cask being deprecated or disabled.
The info message will be `<cask> is deprecated because it <reason>!`, so format the reason to fit that sentence.
For example, `because: "is broken"` will result in `<cask> is deprecated because it is broken!`.

The `because:` argument can also accept a symbol that corresponds to a preset reason, for example:

```ruby
deprecate! date: "YYYY-MM-DD", because: :discontinued
```

A complete list of allowable symbols can be found in the [`DeprecateDisable` module](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/deprecate_disable.rb).

### Stanza: `conflicts_with`

`conflicts_with` is used to declare conflicts that keep a cask from installing or working correctly.
Expand Down