Contributors docs: adjust line breaks

docs/Acceptable-Casks.md

@@ -1,8 +1,6 @@
 # Acceptable Casks
 
-Some casks should not go in
+Some casks should not go in [homebrew/cask](https://github.com/Homebrew/homebrew-cask). But there are additional [Interesting Taps and Forks](Interesting-Taps-and-Forks.md) and anyone can [start their own](How-to-Create-and-Maintain-a-Tap.md)!
-[homebrew/cask](https://github.com/Homebrew/homebrew-cask). But there are
-additional [Interesting Taps and Forks](Interesting-Taps-and-Forks.md) and anyone can [start their own](Taps.md)!
 
 ## Finding a Home For Your Cask
 
@@ -57,13 +55,11 @@ We do not accept these casks since they offer a higher-than-normal security risk
 
 ### Fonts
 
-Font Casks live in the [Homebrew/homebrew-cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts) repository. See the font repo [CONTRIBUTING.md](https://github.com/Homebrew/homebrew-cask-fonts/blob/HEAD/CONTRIBUTING.md)
+Font casks live in the [Homebrew/homebrew-cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts) repository. See the fonts repo [CONTRIBUTING.md](https://github.com/Homebrew/homebrew-cask-fonts/blob/HEAD/CONTRIBUTING.md) for details.
-for details.
 
 ### Drivers
 
-Driver Casks live in the [Homebrew/homebrew-cask-drivers](https://github.com/Homebrew/homebrew-cask-drivers) repository. See the drivers repo [CONTRIBUTING.md](https://github.com/Homebrew/homebrew-cask-drivers/blob/master/CONTRIBUTING.md)
+Driver casks live in the [Homebrew/homebrew-cask-drivers](https://github.com/Homebrew/homebrew-cask-drivers) repository. See the drivers repo [CONTRIBUTING.md](https://github.com/Homebrew/homebrew-cask-drivers/blob/master/CONTRIBUTING.md) for details.
-for details.
 
 ## Apps that bundle malware
 

docs/Acceptable-Formulae.md

@@ -1,49 +1,43 @@
 # Acceptable Formulae
 
-Some formulae should not go in
+Some formulae should not go in [homebrew/core](https://github.com/Homebrew/homebrew-core). But there are additional [Interesting Taps and Forks](Interesting-Taps-and-Forks.md) and anyone can start their own!
-[homebrew/core](https://github.com/Homebrew/homebrew-core). But there are
-additional [Interesting Taps and Forks](Interesting-Taps-and-Forks.md) and anyone can start their
-own!
 
 ### Supported platforms in `homebrew/core`
 
-The formula needs to build and pass tests on the latest 3 supported macOS versions ([x86_64 and Apple Silicon/ARM](Installation.md#macos-requirements)) and on x86_64 [Linux](Linux-CI.md).
+The formula needs to build and pass tests on the latest 3 supported macOS versions ([x86_64 and Apple Silicon/ARM](Installation.md#macos-requirements)) and on x86_64 [Linux](Linux-CI.md). Please have a look at the continuous integration jobs on a pull request in `homebrew/core` to see the full list of OSs. If upstream does not support one of these platforms, an exception can be made and the formula can be disabled for that platform.
-Please have a look at the continuous integration jobs on a pull request in `homebrew/core` to see the full list of OSs.
-If upstream does not support one of these platforms, an exception can be made and the formula can be disabled for that platform.
 
 ### Dupes in `homebrew/core`
+
 We now accept stuff that comes with macOS as long as it uses `keg_only :provided_by_macos` to be keg-only by default.
 
 ### Versioned formulae in `homebrew/core`
+
 We now accept versioned formulae as long as they [meet the requirements](Versions.md).
 
 ### We don’t like tools that upgrade themselves
-Software that can upgrade itself does not integrate well with Homebrew's own
+
-upgrade functionality. The self-update functionality should be disabled (while minimising complication to the formula).
+Software that can upgrade itself does not integrate well with Homebrew's own upgrade functionality. The self-update functionality should be disabled (while minimising complication to the formula).
 
 ### We don’t like install scripts that download unversioned things
+
 We don't like install scripts that are pulling from the `master` branch of Git repositories or unversioned, unchecksummed tarballs. These should use `resource` blocks with specific revisions or checksummed tarballs instead. Note that we now allow tools like `cargo`, `gem` and `pip` to download specifically versioned libraries during installation.
 
 ### We don’t like binary formulae
-Our policy is that formulae in the core tap
+
-([homebrew/core](https://github.com/Homebrew/homebrew-core)) must be open-source
+Our policy is that formulae in the core tap ([homebrew/core](https://github.com/Homebrew/homebrew-core)) must be open-source with an [Debian Free Software Guidelines license](https://wiki.debian.org/DFSGLicenses) and either built from source or produce cross-platform binaries (e.g. Java, Mono). Binary-only formulae should go to [homebrew/cask](https://github.com/Homebrew/homebrew-cask).
-with an [Debian Free Software Guidelines license](https://wiki.debian.org/DFSGLicenses) and either built
-from source or produce cross-platform binaries (e.g. Java, Mono). Binary-only
-formulae should go to [homebrew/cask](https://github.com/Homebrew/homebrew-cask).
 
 Additionally, [homebrew/core](https://github.com/Homebrew/homebrew-core) formulae must also not depend on casks or any other proprietary software.
 
 This includes automatic installation of casks at runtime.
 
 ### Stable versions
-Formulae in the core repository must have a stable version tagged by
-the upstream project. Tarballs are preferred to Git checkouts, and
-tarballs should include the version in the filename whenever possible.
 
-We don’t accept software without a tagged version because they regularly break
+Formulae in the core repository must have a stable version tagged by the upstream project. Tarballs are preferred to Git checkouts, and tarballs should include the version in the filename whenever possible.
-due to upstream changes and we can’t provide [bottles](Bottles.md) for them.
+
+We don’t accept software without a tagged version because they regularly break due to upstream changes and we can’t provide [bottles](Bottles.md) for them.
 
 ### Niche (or self-submitted) stuff
+
 The software in question must:
 
 * be maintained (i.e. the last release wasn't ages ago, it works without patching on all Homebrew-supported OS versions and has no outstanding, unpatched security vulnerabilities)
@@ -52,40 +46,37 @@ The software in question must:
 * be used
 * have a homepage
 
-We will reject formulae that seem too obscure, partly because they won’t
+We will reject formulae that seem too obscure, partly because they won’t get maintained and partly because we have to draw the line somewhere.
-get maintained and partly because we have to draw the line somewhere.
 
 We frown on authors submitting their own work unless it is very popular.
 
-Don’t forget Homebrew is all Git underneath!
+Don’t forget Homebrew is all Git underneath! [Maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) if you have to!
-[Maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) if you have to!
 
-There may be exceptions to these rules in the main repository; we may
+There may be exceptions to these rules in the main repository; we may include things that don't meet these criteria or reject things that do. Please trust that we need to use our discretion based on our experience running a package manager.
-include things that don't meet these criteria or reject things that do.
-Please trust that we need to use our discretion based on our experience
-running a package manager.
 
 ### Stuff that builds an `.app`
-Don’t make your formula build an `.app` (native macOS Application); we
+
-don’t want those things in Homebrew. Encourage upstream projects to build and support a `.app` that can be distributed by [homebrew/cask](https://github.com/Homebrew/homebrew-cask) (and used without it, too).
+Don’t make your formula build an `.app` (native macOS Application); we don’t want those things in Homebrew. Encourage upstream projects to build and support a `.app` that can be distributed by [homebrew/cask](https://github.com/Homebrew/homebrew-cask) (and used without it, too).
 
 ### Stuff that builds a GUI by default (but doesn't have to)
+
 Make it build a command-line tool or a library by default and, if the GUI is useful and would be widely used, also build the GUI. Don’t build X11/XQuartz GUIs as they are a bad user experience on macOS.
 
 ### Stuff that doesn't build with the latest, stable Xcode Clang
+
 Clang is the default C/C++ compiler on macOS (and has been for a long time). Software that doesn't build with it hasn't been adequately ported to macOS.
 
 ### Stuff that requires heavy manual pre/post-install intervention
+
 We're a package manager so we want to do things like resolve dependencies and set up applications for our users. If things require too much manual intervention then they aren't useful in a package manager.
 
 ## Stuff that requires vendored versions of Homebrew formulae
+
 Homebrew formulae should avoid having multiple, separate, upstream projects bundled together in a single package to avoid shipping outdated/insecure versions of software that is already a formula. Veracode's [State of Software Security report](https://www.veracode.com/blog/research/announcing-state-software-security-v11-open-source-edition) concludes
 > In fact, 79% of the time, developers never update third-party libraries after including them in a codebase.
 
 For more info see [Debian's](https://www.debian.org/doc/debian-policy/ch-source.html#s-embeddedfiles) and [Fedora's](https://docs.fedoraproject.org/en-US/packaging-guidelines/#bundling) stances on this.
 
 ### Sometimes there are exceptions
-Even if all criteria are met we may not accept the formula.
+
-Documentation tends to lag behind current decision-making. Although some
+Even if all criteria are met we may not accept the formula. Documentation tends to lag behind current decision-making. Although some rejections may seem arbitrary or strange they are based on years of experience making Homebrew work acceptably for our users.
-rejections may seem arbitrary or strange they are based on years of
-experience making Homebrew work acceptably for our users.

docs/Brew-Test-Bot.md

@@ -5,21 +5,15 @@ image: https://brew.sh/assets/img/brewtestbot.png
 
 # Brew Test Bot
 
-`brew test-bot` is the name for the automated review and testing system funded
+`brew test-bot` is the name for the automated review and testing system funded by [our Kickstarter in 2013](https://www.kickstarter.com/projects/homebrew/brew-test-bot).
-by [our Kickstarter in 2013](https://www.kickstarter.com/projects/homebrew/brew-test-bot).
 
-It comprises three Mac Pros hosting virtual machines that run the
+It comprises three Mac Pros hosting virtual machines that run the [`test-bot.rb`](https://github.com/Homebrew/homebrew-test-bot/) external command to perform automated testing of commits to the master branch, pull requests and custom builds requested by maintainers.
-[`test-bot.rb`](https://github.com/Homebrew/homebrew-test-bot/) external
-command to perform automated testing of commits to the master branch, pull
-requests and custom builds requested by maintainers.
 
 ## Pull Requests
 
-The bot automatically builds pull requests and updates their status depending
+The bot automatically builds pull requests and updates their status depending on the result of the job.
-on the result of the job.
 
-For example, a job which has been queued but not yet completed will have a
+For example, a job which has been queued but not yet completed will have a section in the pull request that looks like this:
-section in the pull request that looks like this:
 
 ![Triggered Pull Request](assets/img/docs/brew-test-bot-triggered-pr.png)
 
@@ -37,6 +31,5 @@ A passed build looks like this:
 
 ---
 
-On failed or passed builds you can click the "Details" link to view the result
+On failed or passed builds you can click the "Details" link to view the result in GitHub Actions.
-in GitHub Actions.
 

docs/How-To-Open-a-Homebrew-Pull-Request.md

@@ -5,9 +5,11 @@ The following commands are used by Homebrew contributors to set up a fork of Hom
 Depending on the change you want to make, you need to send the pull request to the appropriate one of Homebrew's main repositories. If you want to submit a change to Homebrew core code (the `brew` implementation), you should open the pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open the pull request on the [homebrew/core](https://github.com/Homebrew/homebrew-core) tap, for casks you should open the pull request on the [homebrew/cask](https://github.com/Homebrew/homebrew-cask) tap or another [official tap](https://github.com/Homebrew), based on the formula type.
 
 ## Submit a new version of an existing formula
+
 1. Use `brew bump-formula-pr` to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-formula-pr --help` to learn more.
 
 ## Submit a new version of an existing cask
+
 1. Use `brew bump-cask-pr` to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-cask-pr --help` to learn more.
 
 ## Set up your own fork of the Homebrew repository
@@ -17,13 +19,17 @@ Depending on the change you want to make, you need to send the pull request to t
 1. [Fork the Homebrew/brew repository on GitHub](https://github.com/Homebrew/brew/fork).
    * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.
 2. Change to the directory containing your Homebrew installation:
+
    ```sh
    cd "$(brew --repository)"
    ```
+
 3. Add your pushable forked repository as a new remote:
+
    ```sh
    git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/brew.git
    ```
+
    * `<YOUR_USERNAME>` is your GitHub username, not your local machine username.
 
 ### Formulae related pull request
@@ -31,13 +37,17 @@ Depending on the change you want to make, you need to send the pull request to t
 1. [Fork the Homebrew/homebrew-core repository on GitHub](https://github.com/Homebrew/homebrew-core/fork).
    * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.
 2. Change to the directory containing Homebrew formulae:
+
    ```sh
    cd "$(brew --repository homebrew/core)"
    ```
+
 3. Add your pushable forked repository as a new remote:
+
    ```sh
    git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/homebrew-core.git
    ```
+
    * `<YOUR_USERNAME>` is your GitHub username, not your local machine username.
 
 ### Cask related pull request
@@ -45,13 +55,17 @@ Depending on the change you want to make, you need to send the pull request to t
 1. [Fork the Homebrew/homebrew-cask repository on GitHub](https://github.com/Homebrew/homebrew-cask/fork).
    * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.
 2. Change to the directory containing Homebrew casks:
+
    ```sh
    cd "$(brew --repository homebrew/cask)"
    ```
+
 3. Add your pushable forked repository as a new remote:
+
    ```sh
    git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/homebrew-cask.git
    ```
+
    * `<YOUR_USERNAME>` is your GitHub username, not your local machine username.
 
 ## Create your pull request from a new branch
@@ -59,33 +73,43 @@ Depending on the change you want to make, you need to send the pull request to t
 To make a new branch and submit it for review, create a GitHub pull request with the following steps:
 
 1. Check out the `master` branch:
+
    ```sh
    git checkout master
    ```
+
 2. Retrieve new changes to the `master` branch:
+
    ```sh
    brew update
    ```
+
 3. Create a new branch from the latest `master` branch:
+
    ```sh
    git checkout -b <YOUR_BRANCH_NAME> origin/master
    ```
+
 4. Make your changes. For formulae or casks, use `brew edit` or your favourite text editor, following all the guidelines in the [Formula Cookbook](Formula-Cookbook.md) or [Cask Cookbook](Cask-Cookbook.md).
-  * If there's a `bottle do` block in the formula, don't remove or change it; we'll update it when we pull your PR.
+   * If there's a `bottle do` block in the formula, don't remove or change it; we'll update it when we merge your PR.
-5. Test your changes by running the following, and ensure they all pass without issue. For changed formulae and casks, make sure you do the `brew audit` step while your changed formula/cask is installed.
+5. Test your changes by running the following, and ensure they all pass without issue. For changed formulae and casks, make sure you do the `brew audit` step after your changed formula/cask has been installed.
+
    ```sh
    brew tests
    brew install --build-from-source <CHANGED_FORMULA|CHANGED_CASK>
    brew test <CHANGED_FORMULA|CHANGED_CASK>
    brew audit --strict --online <CHANGED_FORMULA|CHANGED_CASK>
    ```
+
 6. [Make a separate commit](Formula-Cookbook.md#commit) for each changed formula with `git add` and `git commit`.
    * Please note that our preferred commit message format for simple version updates is "`<FORMULA_NAME> <NEW_VERSION>`", e.g. "`source-highlight 3.1.8`".
 7. Upload your branch of new commits to your fork:
+
    ```sh
    git push --set-upstream <YOUR_USERNAME> <YOUR_BRANCH_NAME>
    ```
-8. Go to the relevant repository (e.g. <https://github.com/Homebrew/brew>, <https://github.com/Homebrew/homebrew-core>, etc.) and create a pull request to request review and merging of the commits in your pushed branch. Explain why the change is needed and, if fixing a bug, how to reproduce the bug. Make sure you have done each step in the checklist that appears in your new PR.
+
+8. Go to the relevant repository (e.g. <https://github.com/Homebrew/brew>, <https://github.com/Homebrew/homebrew-core>, etc.) and create a pull request to request review and merging of the commits from your pushed branch. Explain why the change is needed and, if fixing a bug, how to reproduce the bug. Make sure you have done each step in the checklist that appears in your new PR.
 9. Await feedback or a merge from Homebrew's maintainers. We typically respond to all PRs within a couple days, but it may take up to a week, depending on the maintainers' workload.
 
 Thank you!
@@ -104,20 +128,25 @@ To respond well to feedback:
 To make changes based on feedback:
 
 1. Check out your branch again:
+
    ```sh
    git checkout <YOUR_BRANCH_NAME>
    ```
+
 2. Make any requested changes and commit them with `git add` and `git commit`.
 3. Squash new commits into one commit per formula:
+
    ```sh
    git rebase --interactive origin/master
    ```
+
    * If you are working on a PR for a single formula, `git commit --amend` is a convenient way of keeping your commits squashed as you go.
 4. Push to your remote fork's branch and the pull request:
+
    ```sh
    git push --force
    ```
 
-Once all feedback has been addressed and if it's a change we want to include (we include most changes), then we'll add your commit to Homebrew. Note that the PR status may show up as "Closed" instead of "Merged" because of the way we merge contributions. Don't worry: you will still get author credit in the actual merged commit.
+Once all feedback has been addressed and if it's a change we want to include (we include most changes), then we'll add your changes to Homebrew. Note that the PR status may show up as "Closed" instead of "Merged" because of the way we merge contributions. Don't worry: you will still get author credit in the actual merged commit.
 
 Well done, you are now a Homebrew contributor!

docs/How-to-Create-and-Maintain-a-Tap.md

@@ -1,29 +1,16 @@
 # How to Create and Maintain a Tap
 
-[Taps](Taps.md) are external sources of Homebrew formulae, casks  and/or external commands. They
+[Taps](Taps.md) are external sources of Homebrew formulae, casks and/or external commands. They can be created by anyone to provide their own formulae, casks and/or external commands to any Homebrew user.
-can be created by anyone to provide their own formulae, casks  and/or external commands
-to any Homebrew user.
 
 ## Creating a tap
 
-A tap is usually a Git repository available online, but you can use anything as
+A tap is usually a Git repository available online, but you can use anything as long as it’s a protocol that Git understands, or even just a directory with files in it. If hosted on GitHub, we recommend that the repository’s name start with `homebrew-` so the short `brew tap` command can be used. See the [manpage](Manpage.md) for more information on repository naming.
-long as it’s a protocol that Git understands, or even just a directory with
-files in it.
-If hosted on GitHub, we recommend that the repository’s name start with
-`homebrew-` so the short `brew tap` command can be used.
-See the [manpage](Manpage.md) for more information on repository naming.
 
-The `brew tap-new` command can be used to create a new tap along with some
+The `brew tap-new` command can be used to create a new tap along with some template files.
-template files.
 
-Tap formulae follow the same format as the core’s ones, and can be added under
+Tap formulae follow the same format as the core’s ones, and can be added under either the `Formula` subdirectory, the `HomebrewFormula` subdirectory or the repository’s root. The first available directory is used, other locations will be ignored. We recommend use of subdirectories because it makes the repository organisation easier to grasp, and top-level files are not mixed with formulae.
-either the `Formula` subdirectory, the `HomebrewFormula` subdirectory or the
-repository’s root. The first available directory is used, other locations will
-be ignored. We recommend use of subdirectories because it makes the repository
-organisation easier to grasp, and top-level files are not mixed with formulae.
 
-See [homebrew/core](https://github.com/Homebrew/homebrew-core) for an example of
+See [homebrew/core](https://github.com/Homebrew/homebrew-core) for an example of a tap with a `Formula` subdirectory.
-a tap with a `Formula` subdirectory.
 
 ## Naming your formulae to avoid clashes
 
@@ -31,57 +18,35 @@ If your formulae have the same name as Homebrew/homebrew-core formulae they cann
 
 ### Installing
 
-If it’s on GitHub, users can install any of your formulae with
+If it’s on GitHub, users can install any of your formulae with `brew install user/repo/formula`. Homebrew will automatically add your `github.com/user/homebrew-repo` tap before installing the formula. `user/repo/formula` points to the `github.com/user/homebrew-repo/**/formula.rb` file here.
-`brew install user/repo/formula`. Homebrew will automatically add your
-`github.com/user/homebrew-repo` tap before installing the formula.
-`user/repo/formula` points to the `github.com/user/homebrew-repo/**/formula.rb`
-file here.
 
-If they want to get your tap without installing any formula at the same time,
+To install your tap without installing any formula at the same time, users can add it with the [`brew tap` command](Taps.md). If it’s on GitHub, they can use `brew tap user/repo`, where `user` is your GitHub username and `homebrew-repo` is your repository. If it’s hosted outside of GitHub, they have to use `brew tap user/repo <URL>`, where `user` and `repo` will be used to refer to your tap and `<URL>` is your Git clone URL.
-users can add it with the [`brew tap` command](Taps.md).
 
-If it’s on GitHub, they can use `brew tap user/repo`, where `user` is your
+Users can then install your formulae either with `brew install foo` if there’s no core formula with the same name, or with `brew install user/repo/foo` to avoid conflicts.
-GitHub username and `homebrew-repo` is your repository.
-
-If it’s hosted outside of GitHub, they have to use `brew tap user/repo <URL>`,
-where `user` and `repo` will be used to refer to your tap and `<URL>` is your
-Git clone URL.
-
-Users can then install your formulae either with `brew install foo` if there’s
-no core formula with the same name, or with `brew install user/repo/foo` to
-avoid conflicts.
 
 ## Maintaining a tap
 
-A tap is just a Git repository so you don’t have to do anything specific when
+A tap is just a Git repository so you don’t have to do anything specific when making modifications, apart from committing and pushing your changes.
-making modifications, apart from committing and pushing your changes.
 
 ### Updating
 
-Once your tap is installed, Homebrew will update it each time a user runs
+Once your tap is installed, Homebrew will update it each time a user runs `brew update`. Outdated formulae will be upgraded when a user runs `brew upgrade`, like core formulae.
-`brew update`. Outdated formulae will be upgraded when a user runs
-`brew upgrade`, like core formulae.
 
 ## Casks
 
-Casks can also be installed from a tap.
+Casks can also be installed from a tap. Casks can be included in taps with formulae, or in a tap with just casks. Place any cask files you wish to make available in a `Casks` directory at the top level of your tap.
-Casks can be included in taps with formulae, or in a tap with just casks.
-Place any cask files you wish to make available in a `Casks` directory at the top level of your tap.
 
 See [homebrew/cask](https://github.com/Homebrew/homebrew-cask) for an example of a tap with a `Casks` subdirectory.
 
 ### Naming
 
-Unlike formulae, casks must have globally unique names to avoid clashes.
+Unlike formulae, casks must have globally unique names to avoid clashes. This can be achieved by e.g. prepending the cask name with your github username: `username-formula-name`.
-This can be achieved by e.g. prepending the cask name with your github username: `username-formula-name`.
 
 ## External commands
 
-You can provide your tap users with custom `brew` commands by adding them in a
+You can provide your tap users with custom `brew` commands by adding them in a `cmd` subdirectory. [Read more on external commands](External-Commands.md).
-`cmd` subdirectory. [Read more on external commands](External-Commands.md).
 
-See [homebrew/aliases](https://github.com/Homebrew/homebrew-aliases) for an
+See [homebrew/aliases](https://github.com/Homebrew/homebrew-aliases) for an example of a tap with external commands.
-example of a tap with external commands.
 
 ## Official Vendor Taps
 

docs/Prose-Style-Guidelines.md

@@ -1,6 +1,7 @@
+# Prose Style Guidelines
+
 <!-- vale off -->
 <!-- Disable vale linting for the whole of the style guide, because it contains deliberately bad examples. -->
-# Prose Style Guidelines
 
 This is a set of style and usage guidelines for Homebrew's prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in `docs` in the `Homebrew/brew` repository, announcement emails, and other communications with the Homebrew community.
 

docs/Rename-A-Formula.md

@@ -1,7 +1,6 @@
 # Renaming a Formula
 
-Sometimes software and formulae need to be renamed. To rename a formula
+Sometimes software and formulae need to be renamed. To rename a formula you need to:
-you need to:
 
 1. Rename the formula file and its class to a new formula. The new name must meet all the usual rules of formula naming. Fix any test failures that may occur due to the stricter requirements for new formulae than existing formulae (i.e. `brew audit --online --new-formula` must pass for that formula).
 

docs/Typechecking.md

@@ -1,20 +1,14 @@
 # Type Checking With Sorbet
 
-The majority of the code in Homebrew is written in Ruby which is a dynamic
+The majority of the code in Homebrew is written in Ruby which is a dynamic language. To avail the benefits of static type checking, we have set up Sorbet in our codebase which provides the benefits of static type checking to dynamic languages like Ruby.
-language. To avail the benefits of static type checking, we have set up
-Sorbet in our codebase which provides the benefits of static type checking
-to dynamic languages like Ruby.
 
-The [Sorbet Documentation] is a good place
+The [Sorbet Documentation] is a good place to get started if you want to dive deeper into Sorbet and it's abilities.
-to get started if you want to dive deeper into Sorbet and it's abilities.
 
 ## Sorbet in the Homebrew Codebase
 
 ### Inline Type Annotations
 
-To add type annotations to a class or module, we need to first extend it with
+To add type annotations to a class or module, we need to first extend it with the `T::Sig` module (read this as `Type::Signature`). This adds the `sig` method which is used to annotate method signatures. Here's a simple example:
-the `T::Sig` module (read this as `Type::Signature`). This adds the `sig`
-method which is used to annotate method signatures. Here's a simple example:
 
 ```ruby
 class MyClass
@@ -27,12 +21,9 @@ class MyClass
 end
 ```
 
-With `params`, we specify that we have a parameter `name` which must be a
+With `params`, we specify that we have a parameter `name` which must be a `String` and with `returns`, we specify that this method always returns a `String`.
-`String` and with `returns`, we specify that this method always returns
-a `String`.
 
-For more information on how to express more complex types, refer to the
+For more information on how to express more complex types, refer to the official documentation:
-official documentation:
 
 - [Method Signatures](https://sorbet.org/docs/sigs)
 - [Class Types](https://sorbet.org/docs/class-types)
@@ -41,17 +32,9 @@ official documentation:
 
 ### Ruby Interface Files (`.rbi`)
 
-RBI files help Sorbet learn about constants, ancestors and methods
+RBI files help Sorbet learn about constants, ancestors and methods defined in ways it doesn’t understand natively. We can also create a RBI file to help Sorbet understand dynamic definitions.
-defined in ways it doesn’t understand natively. We can also create a
-RBI file to help Sorbet understand dynamic definitions.
 
-Sometimes it is necessary to explicitly include the `Kernel` module in
+Sometimes it is necessary to explicitly include the `Kernel` module in order for Sorbet to know that methods such as `puts` are available in a given context. This is mostly necessary for modules since they can be used in both `BasicObject`s (which don't include `Kernel`) and `Object`s (which include `Kernel` by default). In this case, it is necessary to create an `.rbi` file ([example]) since re-including the `Kernel` module in actual code can break things.
-order for Sorbet to know that methods such as `puts` are available in
-a given context. This is mostly necessary for modules since they can
-be used in both `BasicObject`s (which don't include `Kernel`) and
-`Object`s (which include `Kernel` by default). In this case, it is
-necessary to create an `.rbi` file ([example]) since re-including the
-`Kernel` module in actual code can break things.
 
 Read more about RBI files [here](https://sorbet.org/docs/rbi).
 
@@ -61,69 +44,32 @@ Read more about RBI files [here](https://sorbet.org/docs/rbi).
 
 [`Library/Homebrew/sorbet`]: https://github.com/Homebrew/brew/tree/master/Library/Homebrew/sorbet
 
-- The `rbi` directory contains all Ruby Interface (`.rbi`) files
+- The `rbi` directory contains all Ruby Interface (`.rbi`) files auto-generated by running `brew typecheck --update`:
-  auto-generated by running `brew typecheck --update`:
 
-  - RBI files for all gems are generated using
+  - RBI files for all gems are generated using [Tapioca](https://github.com/Shopify/tapioca#tapioca).
-    [Tapioca](https://github.com/Shopify/tapioca#tapioca).
+  - Definitions for dynamic code (i.e. meta-programming) are generated using `srb rbi hidden-definitions`.
-  - Definitions for dynamic code (i.e. meta-programming) are generated using
-    `srb rbi hidden-definitions`.
   - Definitions for missing constants are generated using `srb rbi todo`.
 
-- The `config` file is a newline-separated list of arguments to pass to
+- The `config` file is a newline-separated list of arguments to pass to `srb tc`, the same as if they’d been passed at the command-line. Arguments in the config file are always passed first, followed by arguments provided on the command-line. We use it to ignore Gem directories which we do not wish to type check.
-  `srb tc`, the same as if they’d been passed at the command-line. Arguments
-  in the config file are always passed first, followed by arguments provided
-  on the command-line. We use it to ignore Gem directories which we do not
-  wish to type check.
 
-- Every Ruby file in the codebase has a magic `# typed: <level>` comment at the
+- Every Ruby file in the codebase has a magic `# typed: <level>` comment at the top, where `<level>` is one of [Sorbet's strictness levels], usually `false`, `true` or `strict`. The `false` files only report errors related to the syntax, constant resolution and correctness of the method signatures, but no type errors. Our long-term goal is to move all `false` files to `true` and start reporting type errors on those files as well. Therefore, when adding new files, you should ideally mark it with `# typed: true` and work out any resulting type errors.
-  top, where `<level>` is one of [Sorbet's strictness levels], usually `false`,
-  `true` or `strict`. The `false` files only report errors related to the
-  syntax, constant resolution and correctness of the method signatures, but no
-  type errors. Our long-term goal is to move all `false` files to `true` and
-  start reporting type errors on those files as well. Therefore, when adding
-  new files, you should ideally mark it with `# typed: true` and work out any
-  resulting type errors.
 
 [Sorbet's strictness levels]: https://sorbet.org/docs/static#file-level-granularity-strictness-levels
 
 ## Using `brew typecheck`
 
-When run without any arguments, `brew typecheck`, will run considering the strictness levels
+When run without any arguments, `brew typecheck`, will run considering the strictness levels set in each of the individual Ruby files in the core Homebrew codebase. However, when it is run on a specific file or directory, more errors may show up since Sorbet cannot resolve constants defined outside the scope of the specified file. These problems can be solved with RBI files. Currently `brew typecheck` provides `--quiet`, `--file`, `--dir` and `--ignore` options but you can explore more options with `srb tc --help` and passing them with `srb tc`.
-set in each of the individual Ruby files in the core Homebrew codebase. However, when
-it is run on a specific file or directory, more errors may show up since Sorbet
-cannot resolve constants defined outside the scope of the specified file. These
-problems can be solved with RBI files. Currently `brew typecheck` provides `--quiet`, `--file`,
-`--dir` and `--ignore` options but you can explore more options with `srb tc --help` and
-passing them with `srb tc`.
 
 ## Resolving Type Errors
 
-Sorbet reports type errors along with an error reference code, which can be used
+Sorbet reports type errors along with an error reference code, which can be used to look up more information on how to debug the error, or what causes the error in the [Sorbet Documentation]. Here is how to debug some common type errors:
-to look up more information on how to debug the error, or what causes the error in
-the [Sorbet Documentation]. Here is how to debug some common type errors:
 
-- Using `T.reveal_type`. In files which are `true` or higher, if we wrap a variable
+- Using `T.reveal_type`. In files which are `true` or higher, if we wrap a variable or method call in `T.reveal_type`, Sorbet will show us what type it thinks that variable has in the output of `srb tc`. This is particularly useful when writing [method signatures](https://sorbet.org/docs/sigs) and debugging. Make sure to remove this line from your code before committing your changes, since this is just a debugging tool.
-  or method call in `T.reveal_type`, Sorbet will show us what type it thinks that
-  variable has in the output of `srb tc`. This is particularly useful when writing
-  [method signatures](https://sorbet.org/docs/sigs) and debugging. Make sure to
-  remove this line from your code before committing your changes, since this is
-  just a debugging tool.
 
-- One of the most frequent errors that we've encountered is: `7003: Method does not exist.`
+- One of the most frequent errors that we've encountered is: `7003: Method does not exist.` Since Ruby is a very dynamic language, methods can be defined in ways Sorbet cannot see statically. In such cases, check if the method exists at runtime, if not, then Sorbet has caught a future bug! But, it is also possible that even though a method exists at runtime, Sorbet cannot see it. In such cases, we use [`.rbi` files](#ruby-interface-files-rbi).
-  Since Ruby is a very dynamic language, methods can be defined in ways Sorbet cannot
-  see statically. In such cases, check if the method exists at runtime, if not, then
-  Sorbet has caught a future bug! But, it is also possible that even though a method
-  exists at runtime, Sorbet cannot see it. In such cases, we use
-  [`.rbi` files](#ruby-interface-files-rbi).
 
-- Since Sorbet does not automatically assume that Kernel is to be included in Modules,
+- Since Sorbet does not automatically assume that Kernel is to be included in Modules, we may encounter many errors while trying to use methods like `puts`, `ohai`, `odebug` et cetera. A simple workaround for this would be to add an extra `include Kernel` line in the respective RBI file.
-  we may encounter many errors while trying to use methods like `puts`, `ohai`, `odebug` et cetera.
-  A simple workaround for this would be to add an extra `include Kernel` line in the
-  respective RBI file.
 
-- The tips above are very generic and apply to lots of cases. For some common gotchas
+- The tips above are very generic and apply to lots of cases. For some common gotchas when using Sorbet, refer to the [Sorbet Error Reference](https://sorbet.org/docs/error-reference) and [FAQ](https://sorbet.org/docs/faq).
-  when using Sorbet, refer to the [Sorbet Error Reference](https://sorbet.org/docs/error-reference)
-  and [FAQ](https://sorbet.org/docs/faq).
 
 [Sorbet Documentation]: https://sorbet.org/docs/overview

docs/Versions.md

@@ -3,6 +3,7 @@
 [homebrew/core](https://github.com/homebrew/homebrew-core) supports multiple versions of formulae with a special naming format. For example, the formula for GCC 6 is named `gcc@6.rb` and begins with `class GccAT6 < Formula`.
 
 ## Acceptable versioned formulae
+
 Versioned formulae we include in [homebrew/core](https://github.com/homebrew/homebrew-core) must meet the following standards:
 
 * Versioned software should build on all Homebrew's supported versions of macOS.