Merge pull request #7829 from Rylan12/clarify-maintainer-docs

Clarify docs for how PRs should be completed by maintainers

docs/Bottles.md

@@ -8,7 +8,7 @@ If a bottle is available and usable it will be downloaded and poured automatical
 Bottles will not be used if the user requests it (see above), if the formula requests it (with `pour_bottle?`), if any options are specified during installation (bottles are all compiled with default options), if the bottle is not up to date (e.g. lacking a checksum) or if the bottle's `cellar` is not `:any` nor equal to the current `HOMEBREW_CELLAR`.
 
 ## Creation
-Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mostly when people submit pull requests to Homebrew and the `bottle do` block is updated by maintainers when they `brew pr-publish` or `brew pr-pull` the contents of a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew).
+Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md), usually when people submit pull requests to Homebrew. The `bottle do` block is updated by maintainers when they merge a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew).
 
 By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for (Core 2 for 64-bit OSs). This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimised for something else, you can pass the `--bottle-arch=` option to build for another architecture; for example, `brew install foo --build-bottle --bottle-arch=penryn`. Just remember that if you build for a newer architecture some of your users might get binaries they can't run and that would be sad!
 

docs/Brew-Test-Bot-For-Core-Contributors.md

@@ -8,6 +8,7 @@ If a pull request is correct and doesn't need any modifications to commit messag
 
 1. Ensure the job has already completed successfully.
 2. Run `brew pr-publish 12345` where `12345` is the pull request number (or URL).
+    - Approving a PR for an existing formula will automatically publish the bottles and close the PR, taking care of this step.
 3. Watch the [actions queue](https://github.com/Homebrew/homebrew-core/actions) to ensure your job finishes. BrewTestBot will usually notify you of failures with a ping as well.
 
 If a pull request needs changes to the commit messages:

docs/Homebrew-homebrew-core-Merge-Checklist.md

@@ -54,7 +54,7 @@ Check for:
 - if CI is green and...
   - formula `bottle :unneeded`, you can merge it through GitHub UI
   - bottles need to be pulled, and...
-    - the commits are correct and don't need changes, use: `brew pr-publish $PR_ID`
+    - the commits are correct and don't need changes, approve the PR to trigger an automatic merge (use `brew pr-publish $PR_ID` to trigger manually in case of a new formula)
     - the commits need to be amended, use `brew pr-pull $PR_ID`, make changes, and `git push`
 - don't forget to thank the contributor
   - celebrate the first-time contributors

docs/New-Maintainer-Checklist.md

@@ -33,9 +33,10 @@ A few requests:
 - In Homebrew/brew, close pull requests using GitHub's "Merge pull request"
   button in "Create a merge commit" mode.
 - In Homebrew/homebrew-core, use `brew pr-publish` to close pull requests
-  that require new bottles or change multiple formulae. If commits need to
-  be amended use `brew pr-pull` instead. Let these commands auto-close
-  issues whenever possible (it may take up to 5 minutes). If in doubt,
+  that require new bottles or change multiple formulae. Note that an approving
+  review on a pull request for an existing formula will trigger this automatically.
+  If commits need to be amended use `brew pr-pull` instead. Let these commands
+  auto-close issues whenever possible (it may take up to 5 minutes). If in doubt,
   check with e.g. Fork.app that you've not accidentally added merge commits.
   If bottles are unnecessary, use GitHub's "Merge pull request" button in
   "Squash and merge" mode for a single formula change.