From 5f7c369bc8b66ee3a107741d4ed8ec9bbea340d4 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Tue, 29 Dec 2020 13:01:58 -0500 Subject: [PATCH 1/6] docs: fix wording on manpage for cask options --- Library/Homebrew/dev-cmd/man.rb | 2 +- docs/Manpage.md | 2 +- manpages/brew.1 | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index 9beaef7139ab7..ae3dc6facecae 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -218,7 +218,7 @@ def cmd_comment_manpage_lines(cmd_path) 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/Manpage.md b/docs/Manpage.md index 946d3c0a154ec..98f72beb18815 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -1396,7 +1396,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 0284bb679f84b..d66500d3504b4 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -1945,7 +1945,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 From 07ffa7dda713b019a3d8b8bd46094bf39a7e6ddb Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Tue, 29 Dec 2020 13:02:14 -0500 Subject: [PATCH 2/6] docs: clarify squash/merge vs rebase/merge --- docs/Maintainer-Guidelines.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index 93b1c219e6dd7..2e4462d451461 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. +- Use the GitHub squash & merge or rebase & merge workflows where bottles aren't required. - 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. @@ -62,7 +62,7 @@ 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 +and squash/merge or rebase/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. Otherwise, you should use `brew pr-pull` (or `rebase`/`cherry-pick` contributions). @@ -80,6 +80,13 @@ 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) +Here are guidelines about when to use squash & merge versus rebase & merge. These options should only be used when bottles are not needed. + +| | 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. From ac3ce218e3560713c44e856b2906be7e53a164e0 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Wed, 30 Dec 2020 15:09:00 -0500 Subject: [PATCH 3/6] man: fix style issue --- Library/Homebrew/dev-cmd/man.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index ae3dc6facecae..06372647eae4a 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -218,7 +218,8 @@ def cmd_comment_manpage_lines(cmd_path) sig { returns(String) } def global_cask_options_manpage - lines = ["These options are applicable to the `install`, `reinstall`, and `upgrade` subcommands with the `--cask` flag.\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 From bca13a49262e6b375de5dd2996884ce34aeb2fc5 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Wed, 30 Dec 2020 16:22:46 -0500 Subject: [PATCH 4/6] docs: clarify GitHub merge workflow usage Co-Authored-By: Sam Ford <1584702+samford@users.noreply.github.com> --- docs/Maintainer-Guidelines.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index 2e4462d451461..b619aa30d264e 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 or rebase & merge workflows 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. @@ -80,7 +80,9 @@ 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) -Here are guidelines about when to use squash & merge versus rebase & merge. These options should only be used when bottles are not needed. +#### 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 | |---|---|---| From b605b3ebe54d94f39782f70d2a1a53a2e6435daa Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Wed, 30 Dec 2020 21:12:45 -0500 Subject: [PATCH 5/6] docs: further clarify merging workflows Co-Authored-By: Sam Ford <1584702+samford@users.noreply.github.com> --- docs/Maintainer-Guidelines.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index b619aa30d264e..6643c6a5d8c5e 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -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 or rebase/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 & 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 From 6133c6602a2c40e788d7698c29019707aa17bbc5 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Thu, 31 Dec 2020 10:44:00 -0500 Subject: [PATCH 6/6] docs: use and instead of & Co-authored-by: Sam Ford <1584702+samford@users.noreply.github.com> --- docs/Maintainer-Guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index 6643c6a5d8c5e..6e1c58185bde8 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -61,7 +61,7 @@ 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. +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.