Maintainers docs: content & formatting updates

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

@@ -1,4 +1,4 @@
-# Brew Test Bot For Core Contributors
+# Brew Test Bot for Maintainers
 
 If a build has run and passed on `brew test-bot` then it can be used to quickly bottle formulae.
 

docs/Common-Issues-for-Core-Contributors.md

@@ -1,4 +1,4 @@
-# Common Issues for Core Contributors
+# Common Issues for Maintainers
 
 ## Overview
 
@@ -15,7 +15,7 @@ Follow these steps to fix this issue:
 
 Alternative instructions using `pr-pull`:
 
-* `git reset --hard <SHA>` in homebrew/core to reset to the commit before before all the commits created by `brew pr-pull`.
+* `git reset --hard <SHA>` in `homebrew/core` to reset to the commit before all the commits created by `brew pr-pull`.
 * `brew pr-pull <options>` to upload the right bottles. Add the `--warn-on-upload-failure` flag if the bottles have been partially uploaded and you're certain that the bottle checksums will match the checksums already present in the `bottle do` block of the formula.
 * `git reset --hard origin/master` to return to the latest commit and discard the commits made by `brew pr-pull`.
 
@@ -23,4 +23,4 @@ Alternative instructions using `pr-pull`:
 
 The exact atom may be different.
 
-This can be caused by passing the obsolete `-s` flag to the linker and can be fixed like [this](https://github.com/Homebrew/homebrew-core/commit/c4ad981d788b21a406a6efe7748f2922986919a8).
+This can be caused by passing the obsolete `-s` flag to the linker and can be fixed [using `inreplace`](https://github.com/Homebrew/homebrew-core/commit/c4ad981d788b21a406a6efe7748f2922986919a8).

docs/Homebrew-Leadership-Responsibilities.md

@@ -1,4 +1,4 @@
-# Homebrew Governance Responsibilities
+# Homebrew Leadership Responsibilities
 
 ## Project Leadership Committee
 

docs/Homebrew-brew-Maintainer-Guide.md

@@ -14,16 +14,16 @@ When reviewing a PR, use "comment", "approve", or "request changes" when submitt
 
 ## Merging PRs
 
-Merging is done using the standard Merge button in the `Homebrew/brew` repository to preserve history and GPG commit signing. The Squash and Merge and Rebase and Merge buttons are disabled.
+Merging is done using the standard "Merge" button in the `Homebrew/brew` repository to preserve history and GPG commit signing. The "Squash and Merge" and "Rebase and Merge" buttons are disabled.
 
 PRs must meet the following conditions to be merged:
 
-- Have at least one maintainer (or [@BrewTestBot](https://github.com/BrewTestBot)) approval. See the ["Automatic approvals" section below](#automatic-approvals). for more details about how [@BrewTestBot](https://github.com/BrewTestBot) approves PRs.
+- Have at least one maintainer (or [@BrewTestBot](https://github.com/BrewTestBot)) approval. See the [Automatic approvals](#automatic-approvals) section below for more details about how [@BrewTestBot](https://github.com/BrewTestBot) approves PRs.
-- Have passing CI. This is a _mandatory_ step. PRs with failing CI should _never_ be merged. See the ["CI" section below](#ci) for more information about `Homebrew/brew` CI.
+- Have passing CI (continuous integration). This is a _mandatory_ step. PRs with failing CI should _never_ be merged. See the [CI](#ci) section below for more information about `Homebrew/brew` CI.
 
 If possible, PRs should also have GPG-signed commits (see the private `ops` repository for instructions on setting this up).
 
-## Automatic approvals
+### Automatic approvals
 
 To ensure that non-urgent PRs have the opportunity to be seen and reviewed by any other maintainers who wish to take a look, all PRs require an approval before they can be merged. However, not every PR is reviewed by another maintainer, and some PRs are urgent enough that they need to be merged without an approval by another maintainer.
 
@@ -33,20 +33,21 @@ If the PR is urgent enough that it is necessary to bypass that 24 hour window, t
 
 ## CI
 
-Every PR in `Homebrew/brew` runs a series of CI tests to try to prevent bugs from being introduced. **A PR _must_ have passing CI before it can be merged**.
+Every PR in `Homebrew/brew` runs a series of CI tests to try to prevent bugs from being introduced. **A PR _must_ have passing CI before it can be merged.**
 
 There are many checks that run on every PR. The following is a quick list of the various checks and what they represent:
 
+- `Triage / review`: This verifies that the PR has been open for long enough. See the [Automatic approvals](#automatic-approvals) section above for more information about automatic approvals.
 - `Vendor Gems / vendor-gems`: This is skipped except for dependabot PRs. It updates the RBI files to match any new/changed dependencies. See [Type Checking With Sorbet](Typechecking.md) for more information about RBI files and typechecking.
-- `Triage / review`: This verifies that the PR has been open for long enough. See the ["Automatic approvals" section above](#automatic-approvals) for more information about automatic approvals.
+- `Codecov / codecov/patch` and `codecov/project`: These show the Codecov report for the PR. See the [`brew tests` and Codecov](#brew-tests-and-codecov) section below for more info about Codecov.
-- `codecov/patch` and `codecov/project`: These show the Codecov report for the PR. See the ["`brew tests` and Codecov" section below](#brew-tests-and-codecov) for more info about Codecov.
+- `CI / vendored gems`: This checks whether there was a change to the vendored gems on Linux that needs to be committed to the PR branch.
-- `CI / vendored gems (Linux)`: This checks whether there was a change to the vendored gems on Linux that needs to be committed to the PR branch.
 - `CI / test default formula (Linux)`: This runs `brew test-bot` on Linux to ensure it still works as expected.
 - `CI / syntax`: This is run first to check whether the PR passes `brew style` and `brew typecheck`. If this job fails the following jobs will not run.
-- `CI / tap syntax (Linux)`: This runs `brew style` and `brew audit` on all official taps (note that although this has Linux in its name, it does check `Homebrew/homebrew-core` and all cask repos).
+- `CI / tap syntax`: This runs `brew style` and `brew audit` on all official taps (note that although this runs on Linux, it does check all cask repos).
-- `CI / docker`: This builds and deploys a new Homebrew Docker image.
+- `CI / docker`: This builds and deploys a new Homebrew Docker image to GitHub Packages and Docker Hub.
 - `CI / test everything (macOS)`: This runs several checks on macOS including `brew tests`, `brew update-tests`, `brew test-bot --only-formulae --test-default-formula`, `brew readall` and `brew doctor`.
 - `CI / tests (no-compatibility mode)`, `CI / tests (generic OS)` and `CI / tests (Linux)`: These run `brew tests` with various options on Linux.
+- `Documentation CI / linting` and `rubydoc`: These check the prose and formatting of the written documentation, and verify the [rubydoc API documentation](https://rubydoc.brew.sh) can be built without issue.
 
 _Note that this list is non-exhaustive and can change over time._
 
@@ -58,14 +59,14 @@ Codecov should be used as a guide to indicate when more tests are probably neede
 
 ### `brew tests` and BuildPulse
 
-BuildPulse monitors CI jobs for every push to `Homebrew/brew` to detect flaky tests and track them over time. The reports are available to Homebrew maintainers on [buildpulse.io](https://buildpulse.io/installations) and daily summaries are published to [`#buildpulse-health`](https://machomebrew.slack.com/archives/C0268BSJBJ8) in Slack.
+BuildPulse monitors CI jobs for every push to `Homebrew/brew` to detect flaky tests and track them over time. The reports are available to Homebrew maintainers on [buildpulse.io](https://buildpulse.io/@Homebrew) and daily summaries are published to [`#buildpulse-health`](https://machomebrew.slack.com/archives/C0268BSJBJ8) in Slack.
 
 BuildPulse can be used as a guide to identify which flaky tests are causing the most disruption to the CI suite. To make the biggest improvements to the reliability of the build, we can focus on the most disruptive flaky tests first (i.e. the tests causing the most intermittent failures).
 
-To help find the root cause for a particular flaky test, buildpulse.io provides links to the most recent CI job and commit where the test failed and then passed with no change to the underlying code. You may want to check out the code at that commit to attempt to reproduce the failure locally. You can also see the list of recent failures on [buildpulse.io](https://buildpulse.io) to determine if the test always fails the same way.
+To help find the root cause for a particular flaky test, buildpulse.io provides links to the most recent CI job and commit where the test failed and then passed with no change to the underlying code. You may want to check out the code at that commit to attempt to reproduce the failure locally. You can also see the list of recent failures on [buildpulse.io](https://buildpulse.io/@Homebrew) to determine if the test always fails the same way.
 
-## Manpages and shell completions
+## Manpages and Shell Completions
 
 Homebrew's manpages and shell completions are generated automatically by the `brew generate-man-completions` command. Contributors are welcome to run this command and commit the changes in a PR, but they don't have to. If they don't, a follow-up PR to make the necessary changes will be opened automatically by [@BrewTestBot](https://github.com/BrewTestBot) once the original PR is merged. These follow-up PRs can be merged immediately if the changes seem correct.
 
-An update can be requested manually by triggering the workflow from the [Update maintainers, manpage and completions](https://github.com/Homebrew/brew/actions/workflows/update-man-completions.yml) section under the "Actions" tab. Click on the "Run workflow" dropdown and then the "Run workflow" button. A PR will be opened shortly if there are any changes.
+An update can be requested manually by triggering the workflow from the [Update sponsors, maintainers, manpage and completions](https://github.com/Homebrew/brew/actions/workflows/sponsors-maintainers-man-completions.yml) section under the "Actions" tab. Click on the "Run workflow" dropdown and then the "Run workflow" button. A PR will be opened shortly if there are any changes.

docs/Homebrew-homebrew-cask-Maintainer-Guide.md

@@ -25,9 +25,9 @@ Note that unlike formulae, casks do not consider the `sha256` stanza to be a mea
 
 ## Merging
 
-In general, using GitHub's Squash and Merge button is the best way to merge a PR. This can be used when the PR modifies only one cask, regardless of the number of commits or whether the commit message format is correct. When merging using this method, the commit message can be modified if needed. Usually, version bump commit messages follow the form `Update CASK from OLD_VERSION to NEW_VERSION`.
+In general, using GitHub's "Squash and Merge" button is the best way to merge a PR. This can be used when the PR modifies only one cask, regardless of the number of commits or whether the commit message format is correct. When merging using this method, the commit message can be modified if needed. Usually, version bump commit messages follow the form `Update CASK from OLD_VERSION to NEW_VERSION`.
 
-If the PR modifies multiple casks, use the Rebase and Merge button to merge the PR. This will use the commit messages from the PR, so make sure that they are appropriate before merging. If needed, checkout the PR, squash/reword the commits and force-push back to the PR branch to ensure the proper commit format.
+If the PR modifies multiple casks, use the "Rebase and Merge" button to merge the PR. This will use the commit messages from the PR, so make sure that they are appropriate before merging. If needed, checkout the PR, squash/reword the commits and force-push back to the PR branch to ensure the proper commit format.
 
 Finally, make sure to thank the contributor for submitting a PR!
 

docs/Homebrew-homebrew-core-Maintainer-Guide.md

@@ -9,8 +9,8 @@ A detailed checklist can be found [below](#detailed-merge-checklist). This is al
 - Ensure it uses `keg_only :provided_by_macos` if it already comes with macOS.
 - Ensure it is not a library that can be installed with [gem](https://en.wikipedia.org/wiki/RubyGems), [cpan](https://en.wikipedia.org/wiki/Cpan) or [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.
-- 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 the ["How to merge without bottles" section below](#how-to-merge-without-bottles) for more details.
+- 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 the [How to merge without bottles](#how-to-merge-without-bottles) section below 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.
+- Use `brew pr-publish` or `brew pr-pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by Brew Test Bot.
 - Thank people for contributing.
 
 Checking dependencies is important, because they will probably stick around forever. Nobody really checks if they are necessary or not.
@@ -21,7 +21,7 @@ Homebrew is about Unix software. Stuff that builds to an `.app` should be in Hom
 
 ## Merging, rebasing, cherry-picking
 
-For most PRs that make formula modifications, you can simply approve the PR and an automatic merge (with bottles) will be performed by [@BrewTestBot](https://github.com/BrewTestBot). See [Brew Test Bot For Core Contributors](Brew-Test-Bot-For-Core-Contributors.md) for more information.
+For most PRs that make formula modifications, you can simply approve the PR and an automatic merge (with bottles) will be performed by [@BrewTestBot](https://github.com/BrewTestBot). See [Brew Test Bot for Maintainers](Brew-Test-Bot-For-Core-Contributors.md) for more information.
 
 Certain PRs may not be merged automatically by [@BrewTestBot](https://github.com/BrewTestBot), even after they've been approved. This includes PRs with the `new formula`, `automerge-skip`, and `linux-only` labels. To trigger a merge for these PRs, run `brew pr-publish`.
 
@@ -58,15 +58,15 @@ Choose a name that’s the most common name for the project. For example, we ini
 
 Formulae that are also packaged by other package managers (e.g. Debian, Ubuntu) should be named consistently (subject to minor differences due to Homebrew formula naming conventions).
 
-Add other names as aliases as symlinks in `Aliases` in the tap root. Ensure the name referenced on the homepage is one of these, as it may be different and have underscores and hyphens and so on.
+Add other names as aliases using symlinks within `Aliases` in the tap root. Ensure the name referenced on the homepage is one of these, as it may be different and have underscores and hyphens and so on.
 
 We now accept versioned formulae as long as they [meet the requirements](Versions.md).
 
 ## Testing
 
-We need to at least check that it builds. Use the [Brew Test Bot](Brew-Test-Bot.md) for this.
+We need to at least check that it builds. Use [Brew Test Bot](Brew-Test-Bot.md) for this.
 
-Verify the formula works if possible. If you can’t tell (e.g. if it’s a library) trust the original contributor, it worked for them, so chances are it is fine. If you aren’t an expert in the tool in question, you can’t really gauge if the formula installed the program correctly. At some point an expert will come along, cry blue murder that it doesn’t work, and fix it. This is how open source works. Ideally, request a `test do` block to test that functionality is consistently available.
+Verify the formula works if possible. If you can’t tell (e.g. if it’s a library) trust the original contributor; it worked for them, so chances are it is fine. If you aren’t an expert in the tool in question, you can’t really gauge if the formula installed the program correctly. At some point an expert will come along, cry blue murder that it doesn’t work, and fix it. This is how open source works. Ideally, request a `test do` block to test that functionality is consistently available.
 
 If the formula uses a repository, then the `url` parameter should have a tag or revision. `url`s have versions and are stable (not yet implemented!).
 
@@ -87,7 +87,7 @@ Formulae that:
 
 should not be removed from Homebrew. The exception to this rule are [versioned formulae](Versions.md) for which there are higher standards of usage and a maximum number of versions for a given formula.
 
-For more information about deprecating, disabling and removing formulae, see the [Deprecating, Disabling, and Removing Formulae page](Deprecating-Disabling-and-Removing-Formulae.md).
+For more information about deprecating, disabling and removing formulae, see the [Deprecating, Disabling and Removing Formulae](Deprecating-Disabling-and-Removing-Formulae.md) page.
 
 ## Detailed merge checklist
 
@@ -95,16 +95,16 @@ The following checklist is intended to help maintainers decide on whether to mer
 
 - previously opened active PRs, as we would like to be fair to contributors who came first
 - patches/`inreplace` that have been applied to upstream and can be removed
-- comments in formula around `url`, as we do skip some versions (for example [vim](https://github.com/Homebrew/homebrew-core/blob/359dbb190bb3776c4d6a1f603a271dd8f186f077/Formula/vim.rb#L4) or [v8](https://github.com/Homebrew/homebrew-core/blob/359dbb190bb3776c4d6a1f603a271dd8f186f077/Formula/v8.rb#L4))
+- comments in formula around `url`, as we do skip some versions (for example [`vim`](https://github.com/Homebrew/homebrew-core/blob/359dbb190bb3776c4d6a1f603a271dd8f186f077/Formula/vim.rb#L4) or [`v8`](https://github.com/Homebrew/homebrew-core/blob/359dbb190bb3776c4d6a1f603a271dd8f186f077/Formula/v8.rb#L4))
-- vendored resources that need updates (for example [emscripten](https://github.com/Homebrew/homebrew-core/commit/57126ac765c3ac5201ce53bcdebf7a0e19071eba))
+- vendored resources that need updates (for example [`emscripten`](https://github.com/Homebrew/homebrew-core/commit/57126ac765c3ac5201ce53bcdebf7a0e19071eba))
-- vendored dependencies (for example [certbot](https://github.com/Homebrew/homebrew-core/pull/42966/files))
+- vendored dependencies (for example [`certbot`](https://github.com/Homebrew/homebrew-core/pull/42966/files))
-- stable/announced release
+- stable/announced release:
-  - some teams use odd minor release number for tests and even for stable releases
+  - some teams use an odd minor release number for tests and even for stable releases
-  - other teams drop new version with minor release 0 but promote it to stable only after a few minor releases
+  - other teams drop new versions with minor release 0 but promote it to stable only after a few minor releases
   - if the software uses only hosted version control (such as GitHub, GitLab or Bitbucket), the release should be tagged and if upstream marks latest/pre-releases, PR must use latest
-- does changelog mention addition/removal of dependency and is it addressed in the PR
+- does changelog mention addition/removal of a dependency, and is it addressed in the PR?
-  - does formula depend on versioned formula (for example `python@3.7`, `go@1.10`, `erlang@17`) that can be upgraded
+  - does formula depend on versioned formula (for example `python@3.7`, `go@1.10`, `erlang@17`) that can be upgraded?
-- commits
+- commits:
   - contain one formula change per commit
     - ask author to squash
     - rebase during merge
@@ -117,23 +117,23 @@ The following checklist is intended to help maintainers decide on whether to mer
       Please keep bottle block in place; [@BrewTestBot](https://github.com/BrewTestBot) takes care of it.
 
 - is there a test block for other than checking version or printing help? Consider asking to add one
-- if CI failed
+- if CI failed:
   - due to test block - paste relevant lines and add `test failure` label
   - due to build errors - paste relevant lines and add `build failure` label
-  - due to other formulae needing revision bumps - suggest to use the following command:
+  - due to other formulae needing revision bumps - suggest using the following command:
 
         # in this example: PR is for `libuv` formula and `urbit` needs revision bump
         brew bump-revision --message 'for libuv' urbit
 
-    - make sure it is one commit per revision bump
+    - make sure it has one commit per revision bump
 - if CI is green and...
   - bottles need to be pulled, and...
     - the commits are correct, don't need changes, and BrewTestBot can merge it (doesn't have the label `automerge-skip`): 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 are correct and don't need changes, but BrewTestBot can't merge it (has the label `automerge-skip`), use `brew pr-publish $PR_ID`
+    - the commits are correct and don't need changes, but BrewTestBot can't merge it (has the label `automerge-skip`): use `brew pr-publish $PR_ID`
-    - the commits need to be amended, use `brew pr-pull $PR_ID`, make changes, and `git push`
+    - 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
+  - celebrate any first-time contributors
-- suggest to use `brew bump-formula-pr` next time if this was not the case
+- suggest using `brew bump-formula-pr` next time if this was not the case
 
 ## Common build failures and how to handle them
 

docs/Maintainer-Guidelines.md

@@ -23,17 +23,17 @@ Homebrew aims to be the missing package manager for macOS (and Linux). Its prima
 
 1. [Ensure you have set your username and email address properly](https://help.github.com/articles/setting-your-email-in-git/)
 2. Sign off cherry-picks if you amended them (use `git -s`)
-3. If the commit fixes a bug, use “Fixes \#104” syntax to close the bug report and link to the commit
+3. If your commit fixes a bug, use [issue linking syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) (e.g. “Fixes \#104”) to close the bug report and link back to the commit
 
 ### Add comments
 
-It may be enough to refer to an issue ticket, but make sure changes are clear so that if you came to them unaware of the surrounding issues they would make sense to you. Many times on other projects I’ve seen code removed because the new guy didn’t know why it was there. Regressions suck.
+It may be enough to refer to an issue ticket, but make sure changes and context are clear enough so that anyone reading them for the first time can make sense of them. You don't want code you wrote to be removed because the someone new doesn’t understand why it’s there. Regressions suck.
 
 ### Don’t allow bloated diffs
 
 Amend a cherry-pick to remove commits that are only changes in whitespace. They are not acceptable because our history is important and `git blame` should be useful.
 
-Whitespace corrections (to Ruby standard etc.) are allowed (in fact this is a good opportunity to do it) provided the line itself has some kind of modification that is not whitespace in it. But be careful about making changes to inline patches—make sure they still apply.
+Whitespace corrections (to Ruby standard etc.) are allowed (in fact this is a good opportunity to do it) provided the line itself has some kind of modification that is more than just whitespace changes. But be careful about making changes to inline patches—make sure they still apply.
 
 ### Closing issues/PRs
 
@@ -47,13 +47,13 @@ Any maintainer can revert a PR created by another maintainer after a user submit
 
 ### Give time for other maintainers to review
 
-PRs that are an "enhancement" to existing functionality i.e. not a fix to an open user issue/discussion, not a version bump, not a security fix, not a fix for CI failure, a usability improvement, a new feature, refactoring etc. should wait 24h Monday - Friday before being merged. For example,
+PRs that are an "enhancement" to existing functionality, i.e. not a fix to an open user issue/discussion, not a version bump, not a security fix, not a fix for CI failure, a usability improvement, a new feature, refactoring etc. should wait 24h Monday to Friday before being merged. For example,
 
 - a new feature PR submitted at 5pm on Thursday should wait until 5pm on Friday before it is merged
 - a usability fix PR submitted at 5pm on Friday should wait until 5pm on Monday before it is merged
 - a user-reported issue fix PR can be merged immediately after CI is green
 
-If a maintainer is on holiday/vacation/sick during this time and leaves comments after they are back: please treat post-merge PR comments and feedback as you would left within the time period and follow-up with another PR to address their requests (if agreed).
+If a maintainer is on holiday/vacation/sick during this time and leaves comments after they are back: please treat post-merge PR comments and feedback as you would if left within the time period and follow-up with another PR to address their requests (if agreed).
 
 The vast majority of `Homebrew/homebrew-core` PRs are bug fixes or version bumps which can be self-merged once CI has completed.
 

docs/New-Maintainer-Checklist.md

@@ -17,9 +17,9 @@ changes (e.g. version updates), triaging, fixing and debugging user-reported
 issues, or reviewing user pull requests. You should also be making contributions
 to Homebrew at least once per quarter.
 
-You should watch or regularly check Homebrew/brew and/or
+You should watch or regularly check Homebrew/brew and/or Homebrew/homebrew-core
-Homebrew/homebrew-core and/or Homebrew/homebrew-cask. Let us know which so we
+and/or Homebrew/homebrew-cask. Let us know which so we can grant you commit
-can grant you commit access appropriately.
+access appropriately.
 
 If you're no longer able to perform all of these tasks, please continue to
 contribute to Homebrew, but we will ask you to step down as a maintainer.
@@ -35,7 +35,7 @@ A few requests:
     - Homebrew/brew: https://docs.brew.sh/Homebrew-brew-Maintainer-Guide
     - Homebrew/homebrew-core: https://docs.brew.sh/Homebrew-homebrew-core-Maintainer-Guide
     - Homebrew/homebrew-cask: https://docs.brew.sh/Homebrew-homebrew-cask-Maintainer-Guide
-- Still create your branches on your fork rather than in the main repository.
+- Continue to create branches on your fork rather than in the main repository.
   Note GitHub's UI will create edits and reverts on the main repository if you
   make edits or click "Revert" on the Homebrew/brew repository rather than your
   own fork.
@@ -73,7 +73,7 @@ If they are elected to the Homebrew's [Project Leadership Committee](https://doc
 
 If there are problems, ask them to step down as a maintainer and revoke their access to all of the above.
 
-In the interests of loosely verifying maintainer identity and building camaraderie, if you find yourself in the same town (e.g living, visiting or at a conference) as another Homebrew maintainer you should make the effort to meet up. If you do so, you can expense your meal (within [SFC reimbursable expense policies](https://sfconservancy.org/projects/policies/conservancy-travel-policy.html#meals-for-organizational-development)). This is a more relaxed version of similar policies used by other projects, e.g. the Debian system to meet in person to sign keys with legal ID verification.
+In the interests of loosely verifying maintainer identity and building camaraderie, if you find yourself in the same town (e.g living, visiting or at a conference) as another Homebrew maintainer you should make the effort to meet up. If you do so, you can [expense your meal](https://docs.opencollective.com/help/expenses-and-getting-paid/submitting-expenses) (within [Homebrew's reimbursable expense policies](https://opencollective.com/homebrew/expenses)). This is a more relaxed version of similar policies used by other projects, e.g. the Debian system to meet in person to sign keys with legal ID verification.
 
 Now sit back, relax and let the new maintainers handle more of our contributions.
 

docs/Releases.md

@@ -1,19 +1,41 @@
 # Releases
 
-Since Homebrew 1.0.0 most Homebrew users (those who haven't run a `dev-cmd` or set `HOMEBREW_DEVELOPER=1` which is ~99.9% based on analytics data) require tags on the [Homebrew/brew repository](https://github.com/homebrew/brew) in order to get new versions of Homebrew. There are a few steps in making a new Homebrew release:
+Since Homebrew 1.0.0 most Homebrew users (those who haven't run a `dev-cmd` or set `HOMEBREW_DEVELOPER=1` which is ~99.9% based on analytics data) require tags on the [Homebrew/brew repository](https://github.com/homebrew/brew) in order to receive new versions of Homebrew. There are a few steps in making a new Homebrew release:
+
+1. Check if there is anything pressing that needs to be fixed or merged before the next release in:
+   - [`Homebrew/brew` pull requests](https://github.com/homebrew/brew/pulls)
+   - [`Homebrew/brew` issues](https://github.com/homebrew/brew/issues)
+   - [`Homebrew/homebrew-core` issues](https://github.com/homebrew/homebrew-core/issues)
+   - [Homebrew/discussions (forum)](https://github.com/orgs/Homebrew/discussions)
+
+    If so, fix and merge these changes.
+
+2. Ensure that:
+   - no code changes have happened for at least a couple of hours (ideally 4 hours),
+   - at least one Homebrew/homebrew-core pull request CI job has completed successfully,
+   - the state of the Homebrew/brew `master` CI job is clear (i.e. main jobs green or green after rerunning)
+   - you are confident there are no major regressions on the current `master` branch.
 
-1. Check the [Homebrew/brew pull requests](https://github.com/homebrew/brew/pulls), [issues](https://github.com/homebrew/brew/issues), [Homebrew/homebrew-core issues](https://github.com/homebrew/homebrew-core/issues) and [Homebrew/discussions (forum)](https://github.com/homebrew/discussions/discussions) to see if there is anything pressing that needs to be fixed or merged before the next release. If so, fix and merge these changes.
-2. Ensure that no code changes have happened for at least a couple of hours (ideally 4 hours), at least one Homebrew/homebrew-core pull request CI job has completed successfully, checked the state of the Homebrew/brew `master` CI job (i.e. main jobs green or green after rerunning), and that you are confident there are no major regressions on the current `master`, branch.
 3. Run `brew release` to create a new draft release. For major or minor version bumps, pass `--major` or `--minor`, respectively.
+
 4. Publish the draft release on [GitHub](https://github.com/Homebrew/brew/releases).
 
 If this is a major or minor release (e.g. X.0.0 or X.Y.0) then there are a few more steps:
 
-1. Before creating the tag you should delete any `odisabled` code, make any `odeprecated` code `odisabled`, uncomment any `# odeprecated` code and add any new `odeprecations` that are desired. Also delete any command argument definitions that pass `replacement: ...`.
+1. Before creating the tag you should:
-2. Write up a release notes blog post to <https://brew.sh> e.g. [brew.sh#319](https://github.com/Homebrew/brew.sh/pull/319). This should use the output from `brew release [--major|--minor]` as input but have the wording adjusted to be more human readable and explain not just what has changed but why.
+   - delete any `odisabled` code,
+   - make any `odeprecated` code `odisabled`,
+   - uncomment any `# odeprecated` code
+   - add any new `odeprecations` that are desired.
+
+   Also delete any command argument definitions that pass `replacement: ...`.
+
+2. Write up a release notes blog post for <https://brew.sh> (e.g. [brew.sh#319](https://github.com/Homebrew/brew.sh/pull/319)). This should use the output from `brew release [--major|--minor]` as input but have the wording adjusted to be more human readable and explain not just what has changed but why.
+
 3. When the release has shipped and the blog post has been merged, tweet the blog post as the [@MacHomebrew Twitter account](https://twitter.com/MacHomebrew) or tweet it yourself and retweet it with the @MacHomebrew Twitter account (credentials are in 1Password).
-4. Consider whether to submit it to other sources e.g. Hacker News, Reddit.
+
+4. Consider whether to submit it to other sources, e.g. Hacker News, Reddit.
    - Pros: gets a wider reach and user feedback
    - Cons: negative comments are common and people take this as a chance to complain about Homebrew (regardless of their usage)
 
-Please do not manually create a release based on older commits on the `master` branch. It's very hard to judge whether these have been sufficiently tested by users or if they will cause negative side-effects with the current state of Homebrew/homebrew-core. If a new branch is needed ASAP but there are things on `master` that cannot be released yet (e.g. new deprecations and you want to make a patch release) then revert the relevant PRs, follow the process above and then revert the reverted PRs to reapply them on `master`.
+Please do not manually create a release based on older commits on the `master` branch. It's very hard to judge whether these have been sufficiently tested by users or if they will cause negative side effects with the current state of Homebrew/homebrew-core. If a new branch is needed ASAP but there are things on `master` that cannot be released yet (e.g. new deprecations and you want to make a patch release) then revert the relevant PRs, follow the process above and then revert the reverted PRs to reapply them on `master`.

docs/governance/2019-moss-track-iii-grant-nomination.md

@@ -83,7 +83,7 @@ The other maintainers reviewed this application and have expressed their support
 
 According to anonymous analytics data collected per our policy (<https://docs.brew.sh/Analytics>), Homebrew on macOS has approximately 1.24 million instances that have been active in the past month. This is an increase of 19.3% over the same period last year, with 1.04 million active instances.
 
-Hoomebrew on Linux has approximately 15 thousand active instances, an increase of 75% over last year with 8.6 thousand instances.
+Homebrew on Linux has approximately 15 thousand active instances, an increase of 75% over last year with 8.6 thousand instances.
 
 Each installed instance of Homebrew is quite active: over the last year we recorded approximately 166 million installation events; meaning on average, a instance will install software about 1.7 times per day.