Clarify docs for how PRs should be completed by maintainers

[Rylan12]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

Clarify some of the wording in the maintainer docs. The main thing that was missing was that pr-publish wasn't necessary for existing formulae because an approving review automatically triggers the bottles to be published.

Of course, suggestions to improve working are welcome 😄

[SMillerDev]

@iMichka @jonchang since you wrote this flow a check would be appreciated

[jonchang]

If the goal is to describe what maintainers should do, then the docs in the Maintainers section of https://docs.brew.sh should be updated. The Bottles page is in the Users section and should be providing a general overview of how the process works for users, and not get into the weeds about the details of the maintainers' workflow. I would almost prefer something simpler like:

Bottles are created using the Brew Test Bot, 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.

From the user's point of view, I don't see why making the distinction between a maintainer running brew pr-publish versus BrewTestBot doing the same is relevant, since their goal (getting the pull request merged) happens regardless.

[Rylan12]

I think that makes sense. I'd still like to update the files that are in the Maintainers section. The reason I'm making this is that it wasn't clear to me so I think it's worthwhile to clarify for future maintainers.

I like your suggestion. I think saying "updated by maintainers" is totally reasonable even if it's automatic (it was automatically triggered by an approving review from a maintainer after all)

[jonchang]

I think that makes sense. I'd still like to update the files that are in the Maintainers section. The reason I'm making this is that it wasn't clear to me so I think it's worthwhile to clarify for future maintainers.

Oops, didn't see that the other files were updated. 👍 on any updates to those docs since you have a better perspective as new maintainer on what's lacking.

[SMillerDev]

LGTM 👍

[Rylan12]

The only real misconception I had was that pr-publish was always necessary. Otherwise, it was more a matter of connecting the dots.

In general, I'd say just making sure to talk through the procedure with a new maintainer (like @SMillerDev did with me) should be enough to clarify for them.

[Rylan12]

@SMillerDev okay to merge this without an official approval?

[MikeMcQuaid]

Thanks @Rylan12!