diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index 9beaef7139..06372647ea 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -218,7 +218,8 @@ module Homebrew sig { returns(String) } def global_cask_options_manpage - lines = ["These options are applicable to subcommands accepting a `--cask` flag and all `cask` commands.\n"] + lines = ["These options are applicable to the `install`, `reinstall`, and `upgrade` " \ + "subcommands with the `--cask` flag.\n"] lines += Homebrew::CLI::Parser.global_cask_options.map do |_, long, description:, **| generate_option_doc(nil, long.chomp("="), description) end diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index 93b1c219e6..6e1c58185b 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -26,7 +26,7 @@ This is all that really matters: [pip](https://pip.pypa.io/en/stable/). - Ensure that any dependencies are accurate and minimal. We don't need to support every possible optional feature for the software. -- Use the GitHub squash & merge workflow where bottles aren't required. +- When bottles aren't required or affected, use the GitHub squash & merge workflow for a single-formula PR or rebase & merge workflow for a multiple-formulae PR. See [below](#how-to-merge-without-bottles) for more details. - Use `brew pr-publish` or `brew pr-pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by the Brew Test Bot. - Thank people for contributing. @@ -61,9 +61,12 @@ We now accept versioned formulae as long as they [meet the requirements](Version ### Merging, rebasing, cherry-picking -Merging should be done in the `Homebrew/brew` repository to preserve history & GPG commit signing, -and squash/merge via GitHub should be used for formulae where those formulae -don't need bottles or the change does not require new bottles to be pulled. +Merging should be done in the `Homebrew/brew` repository to preserve history and GPG commit signing. + +PRs modifying formulae that don't need bottles or making changes that don't +require new bottles to be pulled should use GitHub's squash & merge or rebase & merge workflows. +See the [table below](#how-to-merge-without-bottles) for more details. + Otherwise, you should use `brew pr-pull` (or `rebase`/`cherry-pick` contributions). Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t @@ -80,6 +83,15 @@ Here’s a flowchart for managing a PR which is ready to merge: ![Flowchart for managing pull requests](assets/img/docs/managing-pull-requests.drawio.svg) +#### How to merge without bottles + +Here are guidelines about when to use squash & merge versus rebase & merge. These options should only be used with PRs where bottles are not needed or affected. + +| | PR modified a single formula | PR modifies multiple formulae | +|---|---|---| +| **Commits look good** | rebase & merge _or_ squash & merge | rebase & merge | +| **Commits need work** | squash & merge | manually merge using the command line | + ### Testing We need to at least check that it builds. Use the [Brew Test Bot](Brew-Test-Bot.md) for this. diff --git a/docs/Manpage.md b/docs/Manpage.md index 8a3eba64bf..fdfbea2e7c 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -1400,7 +1400,7 @@ Install and commit Homebrew's vendored gems. ## GLOBAL CASK OPTIONS -These options are applicable to subcommands accepting a `--cask` flag and all `cask` commands. +These options are applicable to the `install`, `reinstall`, and `upgrade` subcommands with the `--cask` flag. * `--appdir`: Target location for Applications (default: `/Applications`). diff --git a/manpages/brew.1 b/manpages/brew.1 index d1d643bc87..6831554b21 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -1948,7 +1948,7 @@ Install and commit Homebrew\'s vendored gems\. Update all vendored Gems to the latest version\. . .SH "GLOBAL CASK OPTIONS" -These options are applicable to subcommands accepting a \fB\-\-cask\fR flag and all \fBcask\fR commands\. +These options are applicable to the \fBinstall\fR, \fBreinstall\fR, and \fBupgrade\fR subcommands with the \fB\-\-cask\fR flag\. . .TP \fB\-\-appdir\fR