admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Contributors docs: adjust line breaks

Browse Source
This commit is contained in:
EricFromCanada 2022-04-19 21:28:17 -04:00
parent efa04015a1
commit 034bf72235
No known key found for this signature in database
GPG Key ID: 179D9CDDDB814168
9 changed files with 161 additions and 240 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/Acceptable-Casks.md
View File

@ -1,8 +1,6 @@
# Acceptable Casks
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](Taps.md)!
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)!
## 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)
for details.
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.
### 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)
for details.
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.
## Apps that bundle malware

57
docs/Acceptable-Formulae.md
View File

@ -1,49 +1,43 @@
# Acceptable Formulae
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!
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!
### 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).
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.
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.
### 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
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).
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).
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
due to upstream changes and we can’t provide [bottles](Bottles.md) for them.
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 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
get maintained and partly because we have to draw the line somewhere.
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.
We frown on authors submitting their own work unless it is very popular.
Don’t forget Homebrew is all Git underneath!
[Maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) if you have to!
Don’t forget Homebrew is all Git underneath! [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
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.
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.
### 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
rejections may seem arbitrary or strange they are based on years of
experience making Homebrew work acceptably for our users.
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.

17
docs/Brew-Test-Bot.md
View File

@ -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
by [our Kickstarter in 2013](https://www.kickstarter.com/projects/homebrew/brew-test-bot).
`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).
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.
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.
## Pull Requests
The bot automatically builds pull requests and updates their status depending
on the result of the job.
The bot automatically builds pull requests and updates their status depending on the result of the job.
For example, a job which has been queued but not yet completed will have a
section in the pull request that looks like this:
For example, a job which has been queued but not yet completed will have a 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
in GitHub Actions.
On failed or passed builds you can click the "Details" link to view the result in GitHub Actions.

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

@ -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.
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.
* 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 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!

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

@ -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
can be created by anyone to provide their own formulae, casks and/or external commands
to any Homebrew user.
[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.
## Creating a tap
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.
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.
The `brew tap-new` command can be used to create a new tap along with some
template files.
The `brew tap-new` command can be used to create a new tap along with some template files.
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.
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.
See [homebrew/core](https://github.com/Homebrew/homebrew-core) for an example of
a tap with a `Formula` subdirectory.
See [homebrew/core](https://github.com/Homebrew/homebrew-core) for an example of 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
`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 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.
If they want to get your tap without installing any formula at the same time,
users can add it with the [`brew tap` command](Taps.md).
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.
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 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.
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
making modifications, apart from committing and pushing your changes.
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.
### Updating
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.
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.
## Casks
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 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.
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.
This can be achieved by e.g. prepending the cask name with your github username: `username-formula-name`.
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`.
## External commands
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).
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).
See [homebrew/aliases](https://github.com/Homebrew/homebrew-aliases) for an
example of a tap with external commands.
See [homebrew/aliases](https://github.com/Homebrew/homebrew-aliases) for an example of a tap with external commands.
## Official Vendor Taps

3
docs/Prose-Style-Guidelines.md
View File

@ -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.

3
docs/Rename-A-Formula.md
View File

@ -1,7 +1,6 @@
# Renaming a Formula
Sometimes software and formulae need to be renamed. To rename a formula
you need to:
Sometimes software and formulae need to be renamed. To rename a formula 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).

100
docs/Typechecking.md
View File

@ -1,20 +1,14 @@
# Type Checking With Sorbet
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.
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.
The [Sorbet Documentation] is a good place
to get started if you want to dive deeper into Sorbet and it's abilities.
The [Sorbet Documentation] is a good place 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
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:
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:
```ruby
class MyClass
@ -27,31 +21,20 @@ class MyClass
end
```
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`.
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`.
For more information on how to express more complex types, refer to the
official documentation:
For more information on how to express more complex types, refer to the official documentation:
- [Method Signatures](https://sorbet.org/docs/sigs)
- [Class Types](https://sorbet.org/docs/class-types)
- [Nilable Types](https://sorbet.org/docs/nilable-types)
- [Union Types](https://sorbet.org/docs/union-types)
- [Method Signatures](https://sorbet.org/docs/sigs)
- [Class Types](https://sorbet.org/docs/class-types)
- [Nilable Types](https://sorbet.org/docs/nilable-types)
- [Union Types](https://sorbet.org/docs/union-types)
### Ruby Interface Files (`.rbi`)
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.
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.
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.
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.
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
auto-generated by running `brew typecheck --update`:
- The `rbi` directory contains all Ruby Interface (`.rbi`) files auto-generated by running `brew typecheck --update`:
- RBI files for all gems are generated using
[Tapioca](https://github.com/Shopify/tapioca#tapioca).
- Definitions for dynamic code (i.e. meta-programming) are generated using
`srb rbi hidden-definitions`.
- RBI files for all gems are generated using [Tapioca](https://github.com/Shopify/tapioca#tapioca).
- 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
`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.
- 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.
- 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.
- 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.
[Sorbet's strictness levels]: https://sorbet.org/docs/static#file-level-granularity-strictness-levels
[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
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`.
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`.
## Resolving Type Errors
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:
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:
- 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.
- 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.
- 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).
- 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 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.
- 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.
- 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).
- 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).
[Sorbet Documentation]: https://sorbet.org/docs/overview

1
docs/Versions.md
View File

@ -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.