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

Merge pull request #14202 from EricFromCanada/docs-maintainers-fixes

Browse Source 
docs: update Maintainers section
This commit is contained in:
Eric Knibbe 2022-12-06 13:22:53 -05:00 committed by GitHub
commit 6cf955c830
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
19 changed files with 157 additions and 290 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/Adding-Software-to-Homebrew.md
View File

@ -24,7 +24,7 @@ If everything checks out, you're ready to get started on a new formula!
1. Try installing your formula using `brew install --build-from-source <formula>`, where \<formula> is the name of your formula. If any errors occur, correct your formula and attempt to install it again. The formula installation should finish without errors by the end of this step.
If you're stuck, ask for help on GitHub or [Homebrew/discussions](https://github.com/homebrew/discussions/discussions). The maintainers are very happy to help but we also like to see that you've put effort into trying to find a solution first.
If you're stuck, ask for help on GitHub or the [Homebrew discussion forum](https://github.com/orgs/Homebrew/discussions). The maintainers are very happy to help but we also like to see that you've put effort into trying to find a solution first.
### Testing and auditing the formula

2
docs/Brew-Test-Bot-For-Core-Contributors.md
View File

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

6
docs/Common-Issues-for-Core-Contributors.md
View File

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

6
docs/Common-Issues.md
View File

@ -34,7 +34,7 @@ cd "$(brew --repository)/Library"
git clean -fd
```
### `launchctl` refuses to load launchd plist files
### `launchctl` refuses to load `launchd` plist files
When trying to load a plist file with `launchctl`, you receive an error that resembles either:
@ -108,7 +108,7 @@ When installing Homebrew, if the initial download fails with something like:
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'
Or:
or:
fatal: the remote end hung up unexpectedly
fatal: early EOF
@ -176,7 +176,7 @@ In this case, it’s likely your user account has no admin rights and therefore
If `--appdir` doesn’t fix the issue or you do have write permissions to `/Applications`, verify you’re the owner of the `Caskroom` directory by running `ls -dl "$(brew --prefix)/Caskroom"` and checking the third field. If you are not the owner, fix it with `sudo chown -R "$(whoami)" "$(brew --prefix)/Caskroom"`. If you are, the problem may lie in the app bundle itself.
Some app bundles don’t have certain permissions that are necessary for us to move them to the appropriate location. You may check such permissions with `ls -ls <path_to_app_bundle>`. If you see something like `dr-xr-xr-x` at the start of the output, that may be the cause. To fix it, we need to change the app bundle’s permission to allow us to move it, and then set it back to what it was (in case the developer set those permissions deliberately). See [`litecoin`](https://github.com/Homebrew/homebrew-cask/blob/0cde71f1fea8ad62d6ec4732fcf35ac0c52d8792/Casks/litecoin.rb#L14L20) for an example of such a cask.
Some app bundles don’t have certain permissions that are necessary for us to move them to the appropriate location. You may check such permissions with `ls -ls '/path/to/application.app'`. If you see something like `dr-xr-xr-x` at the start of the output, that may be the cause. To fix it, we need to change the app bundle’s permission to allow us to move it, and then set it back to what it was (in case the developer set those permissions deliberately). See [litecoin.rb](https://github.com/Homebrew/homebrew-cask/blob/9549316eb8bfe88d4c43d13524f42b3f519c33e7/Casks/litecoin.rb#L17-L27) for an example of such a cask.
Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.

16
docs/External-Commands.md
View File

@ -26,17 +26,17 @@ The command may `Kernel.exit` with a status code if it needs to; if it doesn't e
An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments.
| Variable | Description |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `HOMEBREW_CACHE` | Where Homebrew caches downloaded tarballs to, by default `~/Library/Caches/Homebrew`. |
| `HOMEBREW_PREFIX` | Where Homebrew installs software. `/usr/local` by default for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux. |
| `HOMEBREW_CELLAR` | The location of the Homebrew Cellar, where software is staged. This will be `HOMEBREW_PREFIX/Cellar` if that directory exists, or `HOMEBREW_REPOSITORY/Cellar` otherwise. |
| `HOMEBREW_LIBRARY_PATH`| The directory containing Homebrew’s own application code. |
| `HOMEBREW_REPOSITORY` | The Git repository directory (i.e. where Homebrew’s `.git` directory lives). Usually either the same as `HOMEBREW_PREFIX` or a `Homebrew` subdirectory. |
| variable | description |
| ---------------------- | ----------- |
| `HOMEBREW_CACHE` | Where Homebrew caches downloaded tarballs to, by default `~/Library/Caches/Homebrew`.
| `HOMEBREW_PREFIX` | Where Homebrew installs software. `/usr/local` by default for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux.
| `HOMEBREW_CELLAR` | The location of the Homebrew Cellar, where software is staged. This will be `HOMEBREW_PREFIX/Cellar` if that directory exists, or `HOMEBREW_REPOSITORY/Cellar` otherwise.
| `HOMEBREW_LIBRARY_PATH`| The directory containing Homebrew’s own application code.
| `HOMEBREW_REPOSITORY` | The Git repository directory (i.e. where Homebrew’s `.git` directory lives). Usually either the same as `HOMEBREW_PREFIX` or a `Homebrew` subdirectory.
## Providing `--help`
All internal and external Homebrew commands can provide styled `--help` output by using Homebrew’s [argument parser](https://rubydoc.brew.sh/Homebrew/CLI/Parser.html), as seen in the [`brew services` command](https://github.com/Homebrew/homebrew-services/blob/HEAD/cmd/services.rb); or by including lines starting with `#:` (a comment then `:` character in both Bash and Ruby), as seen in the [header of `update.sh`](https://github.com/Homebrew/brew/blob/cf7def0c68903814c6b4e04a55fe8f3cb3f5605e/Library/Homebrew/cmd/update.sh#L1-L10), which is printed with `brew update --help`.
All internal and external Homebrew commands can provide styled `--help` output by using Homebrew’s [argument parser](https://rubydoc.brew.sh/Homebrew/CLI/Parser), as seen in the [`brew services` command](https://github.com/Homebrew/homebrew-services/blob/HEAD/cmd/services.rb); or by including lines starting with `#:` (a comment then `:` character in both Bash and Ruby), as seen in the [header of `update.sh`](https://github.com/Homebrew/brew/blob/cf7def0c68903814c6b4e04a55fe8f3cb3f5605e/Library/Homebrew/cmd/update.sh#L1-L10), which is printed with `brew update --help`.
## Unofficial external commands

4
docs/Formula-Cookbook.md
View File

@ -1015,11 +1015,11 @@ In summary, any environment variables intended for use by a formula need to conf
### Deprecating and disabling a formula
See our [Deprecating, Disabling, and Removing Formulae](Deprecating-Disabling-and-Removing-Formulae.md) documentation for more information about how and when to deprecate or disable a formula.
See our [Deprecating, Disabling and Removing Formulae](Deprecating-Disabling-and-Removing-Formulae.md) documentation for more information about how and when to deprecate or disable a formula.
## Updating formulae
When a new version of the software is released, use `brew bump-formula-pr` to automatically update the [`url`](https://rubydoc.brew.sh/Formula#url-class_method) and [`sha256`](https://rubydoc.brew.sh/Formula#sha256%3D-class_method), remove any [`revision`](https://rubydoc.brew.sh/Formula#revision%3D-class_method) lines, and submit a pull request. See our [How To Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation for more information.
When a new version of the software is released, use `brew bump-formula-pr` to automatically update the [`url`](https://rubydoc.brew.sh/Formula#url-class_method) and [`sha256`](https://rubydoc.brew.sh/Formula#sha256%3D-class_method), remove any [`revision`](https://rubydoc.brew.sh/Formula#revision%3D-class_method) lines, and submit a pull request. See our [How to Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation for more information.
## Troubleshooting for new formulae

2
docs/Homebrew-Leadership-Responsibilities.md
View File

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

107
docs/Homebrew-brew-Maintainer-Guide.md
View File

@ -1,7 +1,6 @@
# Homebrew/brew Maintainer Guide
This document describes a few components of the `Homebrew/brew` repository that are useful for maintainers to
be aware of, but don't necessarily need to appear in documentation for most users and contributors.
This document describes a few components of the `Homebrew/brew` repository that are useful for maintainers to be aware of, but don't necessarily need to appear in documentation for most users and contributors.
## Reviewing PRs
@ -10,110 +9,64 @@ Using `gh pr checkout NUMBER` is a super easy way to check out a PR branch using
When reviewing a PR, use "comment", "approve", or "request changes" when submitting based on the following guidelines:
- Comment: if the PR isn't quite ready to be merged
- Approve: if you feel that the PR is in a good state to be merged, even if there are
non-blocking changes you'd like to be made
- Request changes: if you feel strongly that the PR is likely to cause a problem for users or
have another reason to oppose the PR.
- Approve: if you feel that the PR is in a good state to be merged, even if there are non-blocking changes you'd like to be made
- Request changes: if you feel strongly that the PR is likely to cause a problem for users or have another reason to oppose the PR.
## 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 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 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 (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).
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.
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.
As a compromise between always needing a review and allowing maintainers to merge PRs they deem ready,
the `Triage` CI job will ensure that PRs cannot be merged until they've been open for 24 hours
(only counting hours that occur Monday to Friday). After the triage period has expired, the
CI job will show up as "passed" and [@BrewTestBot](https://github.com/BrewTestBot) will approve the PR,
allowing it to be merged. This gives all maintainers a reasonable opportunity to review every PR,
but won't block any PR for lack of reviews.
As a compromise between always needing a review and allowing maintainers to merge PRs they deem ready, the `Triage` CI job will ensure that PRs cannot be merged until they've been open for 24 hours (only counting hours that occur Monday to Friday). After the triage period has expired, the CI job will show up as "passed" and [@BrewTestBot](https://github.com/BrewTestBot) will approve the PR, allowing it to be merged. This gives all maintainers a reasonable opportunity to review every PR, but won't block any PR for lack of reviews.
If the PR is urgent enough that it is necessary to bypass that 24 hour window, the `critical` label
should be applied to the PR. When this label is applied, the `Triage` CI job will immediately be
successful and [@BrewTestBot](https://github.com/BrewTestBot) will approve the PR.
If the PR is urgent enough that it is necessary to bypass that 24 hour window, the `critical` label should be applied to the PR. When this label is applied, the `Triage` CI job will immediately be successful and [@BrewTestBot](https://github.com/BrewTestBot) will approve the PR.
## 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:
- `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/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 (Linux)`: This checks whether there was a change to the vendored gems on Linux that needs to be
committed to the PR branch.
- `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.
- `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.
- `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 / 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 / docker`: This builds and deploys a new Homebrew Docker image.
- `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.
- `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`: 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 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._
### `brew tests` and Codecov
A coverage report is generated by Codecov for every PR, and its results are shown as CI jobs.
These reports are publicly viewable on [Homebrew/brew's Codecov page](https://app.codecov.io/gh/Homebrew/brew).
Additionally, annotations will appear in the PR's "Files changed" tab where lines of code have been
added that aren't being hit by `brew tests`. If the Codecov job fails, that's a sign that some
more tests should be added to test the functionality being added in the PR.
A coverage report is generated by Codecov for every PR, and its results are shown as CI jobs. These reports are publicly viewable on [Homebrew/brew's Codecov page](https://app.codecov.io/gh/Homebrew/brew). Additionally, annotations will appear in the PR's "Files changed" tab where lines of code have been added that aren't being hit by `brew tests`. If the Codecov job fails, that's a sign that some more tests should be added to test the functionality being added in the PR.
Codecov should be used as a guide to indicate when more tests are probably needed, but it's unrealistic for
every line of code to have a test associated with it, especially when testing would require a slow
integration test. For this reason, it's okay to merge PRs that fail the Codecov check if necessary,
but this should be avoided if possible.
Codecov should be used as a guide to indicate when more tests are probably needed, but it's unrealistic for every line of code to have a test associated with it, especially when testing would require a slow integration test. For this reason, it's okay to merge PRs that fail the Codecov check if necessary, but this should be avoided if possible.
### `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).
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.
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.

32
docs/Homebrew-homebrew-cask-Maintainer-Guide.md
View File

@ -1,50 +1,36 @@
# Homebrew/homebrew-cask Maintainer Guide
This guide is intended to help maintainers effectively maintain the cask repositories.
It is meant to be used in conjunction with the more generic [Maintainer Guidelines](Maintainer-Guidelines.md).
This guide is intended to help maintainers effectively maintain the cask repositories. It is meant to be used in conjunction with the more generic [Maintainer Guidelines](Maintainer-Guidelines.md).
This guide applies to all four of the cask repositories:
- [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask): The main cask repository
- [Homebrew/homebrew-cask-drivers](https://github.com/Homebrew/homebrew-cask-drivers): Casks of drivers
- [Homebrew/homebrew-cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts): Casks of fonts
- [Homebrew/homebrew-cask-versions](https://github.com/Homebrew/homebrew-cask-versions): Alternate versions of Casks
- [Homebrew/homebrew-cask-versions](https://github.com/Homebrew/homebrew-cask-versions): Alternate versions of casks
## Common Situations
Here is a list of the most common situations that arise in cask PRs and how to handle them:
- The `version` and `sha256` both change (keeping the same format): Merge.
- Only the `sha256` changes: Merge unless the version needs to be updated as well.
It’s not uncommon for upstream vendors to update versions in-place.
However, be wary for times when e.g. upstream could have been hacked.
- `livecheck` is updated: Use your best judgement and try to make sure that the changes
follow the [`livecheck` guidelines](Brew-Livecheck.md).
- Only the `version` changes or the `version` format changes: Use your best judgement and
merge if it seems correct (this is relatively rare).
- Only the `sha256` changes: Merge unless the version needs to be updated as well. It’s not uncommon for upstream vendors to update versions in-place. However, be wary for times when e.g. upstream could have been hacked.
- `livecheck` is updated: Use your best judgement and try to make sure that the changes follow the [`livecheck` guidelines](Brew-Livecheck.md).
- Only the `version` changes or the `version` format changes: Use your best judgement and merge if it seems correct (this is relatively rare).
- Other changes (including adding new casks): Use the [Cask Cookbook](Cask-Cookbook.md) to determine what's correct.
If in doubt, ask another cask maintainer on GitHub or Slack.
Note that unlike formulae, casks do not consider the `sha256` stanza to be a meaningful security measure
as maintainers cannot realistically check them for authenticity. Casks download from upstream; if a malicious
actor compromised a URL, they could potentially compromise a version and make it look like an update.
Note that unlike formulae, casks do not consider the `sha256` stanza to be a meaningful security measure as maintainers cannot realistically check them for authenticity. Casks download from upstream; if a malicious actor compromised a URL, they could potentially compromise a version and make it look like an update.
## 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!
## Other Tips
A maintainer can easily rebase a PR onto the latest `master` branch by adding a `/rebase` comment.
`BrewTestBot` will automatically rebase the PR and add a reaction to
the comment once the rebase is in progress and complete.
A maintainer can easily rebase a PR onto the latest `master` branch by adding a `/rebase` comment. `BrewTestBot` will automatically rebase the PR and add a reaction to the comment once the rebase is in progress and complete.

117
docs/Homebrew-homebrew-core-Maintainer-Guide.md
View File

@ -7,50 +7,33 @@ A detailed checklist can be found [below](#detailed-merge-checklist). This is al
- Ensure the name seems reasonable.
- Add aliases.
- 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.
- 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.
- 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](#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 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.
Checking dependencies is important, because they will probably stick around forever. Nobody really checks if they are necessary or not.
Depend on as little stuff as possible. Disable X11 functionality if possible.
For example, we build Wireshark, but not the heavy GUI.
Depend on as little stuff as possible. Disable X11 functionality if possible. For example, we build Wireshark, but not the heavy GUI.
Homebrew is about Unix software. Stuff that builds to an `.app` should
be in Homebrew Cask instead.
Homebrew is about Unix software. Stuff that builds to an `.app` should be in Homebrew Cask instead.
## 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`.
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`.
PRs modifying formulae that don't need bottles or making changes that don't
require new bottles to be pulled should use GitHub's squash & merge or rebase & merge workflows.
See the [table below](#how-to-merge-without-bottles) for more details.
PRs modifying formulae that don't need bottles or making changes that don't require new bottles to be pulled should use GitHub's squash & merge or rebase & merge workflows. See the [table below](#how-to-merge-without-bottles) for more details.
Otherwise, you should use `brew pr-pull` (or `rebase`/`cherry-pick` contributions).
Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t
`rebase`: **you’re a maintainer now!**
Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t `rebase`: **you’re a maintainer now!**
Cherry-picking changes the date of the commit, which kind of sucks.
Don’t `merge` unclean branches. So if someone is still learning `git` and
their branch is filled with nonsensical merges, then `rebase` and squash
the commits. Our main branch history should be useful to other people,
not confusing.
Don’t `merge` unclean branches. So if someone is still learning `git` and their branch is filled with nonsensical merges, then `rebase` and squash the commits. Our main branch history should be useful to other people, not confusing.
Here’s a flowchart for managing a PR which is ready to merge:
@ -69,45 +52,25 @@ Here are guidelines about when to use squash & merge versus rebase & merge. Thes
## Naming
The name is the strictest item, because avoiding a later name change is
desirable.
The name is the strictest item, because avoiding a later name change is desirable.
Choose a name that’s the most common name for the project.
For example, we initially chose `objective-caml` but we should have chosen `ocaml`.
Choose what people say to each other when talking about the project.
Choose a name that’s the most common name for the project. For example, we initially chose `objective-caml` but we should have chosen `ocaml`. Choose what people say to each other when talking about the project.
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).
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!).
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!).
Don't merge any formula updates with failing `brew test`s. If a `test do` block
is failing it needs to be fixed. This may involve replacing more involved tests
with those that are more reliable. This is fine: false positives are better than
false negatives as we don't want to teach maintainers to merge red PRs. If the
test failure is believed to be due to a bug in `Homebrew/brew` or the CI system,
that bug must be fixed, or worked around in the formula to yield a passing test,
before the PR can be merged.
Don't merge any formula updates with failing `brew test`s. If a `test do` block is failing it needs to be fixed. This may involve replacing more involved tests with those that are more reliable. This is fine: false positives are better than false negatives as we don't want to teach maintainers to merge red PRs. If the test failure is believed to be due to a bug in `Homebrew/brew` or the CI system, that bug must be fixed, or worked around in the formula to yield a passing test, before the PR can be merged.
## Duplicates
@ -124,28 +87,24 @@ 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
The following checklist is intended to help maintainers decide on
whether to merge, request changes or close a PR. It also brings more
transparency for contributors in addition to the
[Acceptable Formulae](Acceptable-Formulae.md) requirements.
The following checklist is intended to help maintainers decide on whether to merge, request changes or close a PR. It also brings more transparency for contributors in addition to the [Acceptable Formulae](Acceptable-Formulae.md) requirements.
- 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))
- 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))
- stable/announced release
- some teams use 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
- 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 dependencies (for example [`certbot`](https://github.com/Homebrew/homebrew-core/pull/42966/files))
- stable/announced release:
- some teams use an odd minor release number for tests and even for stable 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 formula depend on versioned formula (for example `python@3.7`, `go@1.10`, `erlang@17`) that can be upgraded
- commits
- 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?
- commits:
- contain one formula change per commit
- ask author to squash
- rebase during merge
@ -158,23 +117,23 @@ transparency for contributors in addition to the
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 need to be amended, use `brew pr-pull $PR_ID`, make changes, and `git push`
- 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`
- don't forget to thank the contributor
- celebrate the first-time contributors
- suggest to use `brew bump-formula-pr` next time if this was not the case
- celebrate any first-time contributors
- suggest using `brew bump-formula-pr` next time if this was not the case
## Common build failures and how to handle them

2
docs/Homebrew-on-Linux.md
View File

@ -84,4 +84,4 @@ Due to [known issues](https://github.com/microsoft/WSL/issues/8219) with WSL 1,
## Homebrew on Linux Community
- [@HomebrewOnLinux on Twitter](https://twitter.com/HomebrewOnLinux)
- [Homebrew/discussions (forum)](https://github.com/homebrew/discussions/discussions)
- [Homebrew/discussions (forum)](https://github.com/orgs/Homebrew/discussions/categories/linux)

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

@ -4,7 +4,7 @@
## 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 [`brew` manual page](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.

50
docs/Maintainer-Guidelines.md
View File

@ -1,35 +1,19 @@
# Maintainer Guidelines
**This guide is for maintainers.** These special people have **write
access** to Homebrew’s repository and help merge the contributions of
others. You may find what is written here interesting, but it’s
definitely not a beginner’s guide.
**This guide is for maintainers.** These special people have **write access** to Homebrew’s repository and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not a beginner’s guide.
Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md) or [Cask Cookbook](Cask-Cookbook.md)?
## Overview
All Homebrew maintainers are encouraged to contribute to all parts of the project,
but there are four main teams that maintainers tend to be a part of:
All Homebrew maintainers are encouraged to contribute to all parts of the project, but there are four main teams that maintainers tend to be a part of:
- `brew` maintainers: this team maintains the [`Homebrew/brew`](https://github.com/Homebrew/brew) repository.
See the [Homebrew/brew Maintainer Guide](Homebrew-brew-Maintainer-Guide.md) for more details about being a `brew` maintainer.
- Core maintainers: this team maintains the [`Homebrew/homebrew-core`](https://github.com/Homebrew/homebrew-core)
repository. See the [Homebrew/homebrew-core Maintainer Guide](Homebrew-homebrew-core-Maintainer-Guide.md)
for more details about being a core maintainer.
- Linux maintainers: this team maintains the [`Homebrew/homebrew-core`](https://github.com/Homebrew/homebrew-core)
repository on Linux.
- Cask maintainers: this team maintains the [`Homebrew/homebrew-cask`](https://github.com/Homebrew/homebrew-cask),
[`Homebrew/homebrew-cask-drivers`](https://github.com/Homebrew/homebrew-cask-drivers),
[`Homebrew/homebrew-cask-fonts`](https://github.com/Homebrew/homebrew-cask-fonts) and
[`Homebrew/homebrew-cask-versions`](https://github.com/Homebrew/homebrew-cask-versions) repositories.
See the [Homebrew/homebrew-cask Maintainer Guide](Homebrew-homebrew-cask-Maintainer-Guide.md)
for more details about being a cask maintainer.
- `brew` maintainers: this team maintains the [`Homebrew/brew`](https://github.com/Homebrew/brew) repository. See the [Homebrew/brew Maintainer Guide](Homebrew-brew-Maintainer-Guide.md) for more details about being a `brew` maintainer.
- Core maintainers: this team maintains the [`Homebrew/homebrew-core`](https://github.com/Homebrew/homebrew-core) repository. See the [Homebrew/homebrew-core Maintainer Guide](Homebrew-homebrew-core-Maintainer-Guide.md) for more details about being a core maintainer.
- Linux maintainers: this team maintains the [`Homebrew/homebrew-core`](https://github.com/Homebrew/homebrew-core) repository on Linux.
- Cask maintainers: this team maintains the [`Homebrew/homebrew-cask`](https://github.com/Homebrew/homebrew-cask), [`Homebrew/homebrew-cask-drivers`](https://github.com/Homebrew/homebrew-cask-drivers), [`Homebrew/homebrew-cask-fonts`](https://github.com/Homebrew/homebrew-cask-fonts) and [`Homebrew/homebrew-cask-versions`](https://github.com/Homebrew/homebrew-cask-versions) repositories. See the [Homebrew/homebrew-cask Maintainer Guide](Homebrew-homebrew-cask-Maintainer-Guide.md) for more details about being a cask maintainer.
These documents are meant to serve as guiding principles. As a maintainer, you can make a call to either
request changes from a contributor or help them out based on their comfort and previous contributions.
Remember, as a team we [Prioritise Maintainers Over Users](Maintainers-Avoiding-Burnout.md) to avoid
burnout. If you wish to change or discuss any of the guidelines: open a PR to suggest a change.
These documents are meant to serve as guiding principles. As a maintainer, you can make a call to either request changes from a contributor or help them out based on their comfort and previous contributions. Remember, as a team we [Prioritise Maintainers Over Users](Maintainers-Avoiding-Burnout.md) to avoid burnout. If you wish to change or discuss any of the guidelines: open a PR to suggest a change.
## Mission
@ -39,25 +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.
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
@ -71,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.

10
docs/New-Maintainer-Checklist.md
View File

@ -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
Homebrew/homebrew-core and/or Homebrew/homebrew-cask. Let us know which so we
can grant you commit access appropriately.
You should watch or regularly check Homebrew/brew and/or Homebrew/homebrew-core
and/or Homebrew/homebrew-cask. Let us know which so we can grant you commit
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.

10
docs/README.md
View File

@ -2,19 +2,19 @@
## Users
- [`brew` man-page (command documentation)](Manpage.md)
- [`brew` manual page (command documentation)](Manpage.md)
- [Homebrew Blog (news on major updates)](https://brew.sh/blog/)
- [Troubleshooting](Troubleshooting.md)
- [Installation](Installation.md)
- [Frequently Asked Questions](FAQ.md)
- [Troubleshooting](Troubleshooting.md)
- [FAQ (Frequently Asked Questions)](FAQ.md)
- [Common Issues](Common-Issues.md)
- [`brew` Shell Completion](Shell-Completion.md)
- [Homebrew on Linux](Homebrew-on-Linux.md)
- [Tips and Tricks](Tips-N'-Tricks.md)
- [Bottles (binary packages)](Bottles.md)
- [Taps (third-party repositories)](Taps.md)
- [Interesting Taps and Forks](Interesting-Taps-and-Forks.md)
- [Tips and Tricks](Tips-N'-Tricks.md)
- [Anonymous Aggregate User Behaviour Analytics](Analytics.md)
- [Querying `brew`](Querying-Brew.md)
@ -65,7 +65,7 @@
- [Homebrew/homebrew-core Maintainer Guide](Homebrew-homebrew-core-Maintainer-Guide.md)
- [Homebrew/homebrew-cask Maintainer Guide](Homebrew-homebrew-cask-Maintainer-Guide.md)
- [Brew Test Bot For Maintainers](Brew-Test-Bot-For-Core-Contributors.md)
- [Brew Test Bot for Maintainers](Brew-Test-Bot-For-Core-Contributors.md)
- [Common Issues for Maintainers](Common-Issues-for-Core-Contributors.md)
- [Releases](Releases.md)
- [Developer/Internal API Documentation](https://rubydoc.brew.sh)

73
docs/Releases.md
View File

@ -1,48 +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.
3. Run `brew release` to create a new draft release. For major or minor version bumps, pass `--major` or `--minor`, respectively.
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: ...`.
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.
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.
- 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)
1. Before creating the tag you should:
- delete any `odisabled` code,
- make any `odeprecated` code `odisabled`,
- uncomment any `# odeprecated` code
- add any new `odeprecations` that are desired.
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`.
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.
- 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`.

2
docs/Troubleshooting.md
View File

@ -15,7 +15,7 @@ This document will help you check for common issues and make sure your issue has
* [Homebrew/homebrew-cask issue tracker](https://github.com/Homebrew/homebrew-cask/issues) (casks)
* [Homebrew/brew issue tracker](https://github.com/Homebrew/brew/issues) (`brew` itself)
* If the formula or cask that has failed to install is part of a non-Homebrew tap, then check that tap's issue tracker instead.
* Search the [Homebrew discussion forum](https://github.com/homebrew/discussions/discussions) or [Discourse archive](https://discourse.brew.sh/) to see if any discussions have started about the issue.
* Search the [Homebrew discussion forum](https://github.com/orgs/Homebrew/discussions) or [Discourse archive](https://discourse.brew.sh/) to see if any discussions have started about the issue.
## Create an issue

2
docs/Updating-Software-in-Homebrew.md
View File

@ -4,7 +4,7 @@ Did you find something in Homebrew that wasn't the latest version? You can help
First, check the pull requests in the Homebrew tap repositories to make sure a PR isn't already open. If you're submitting a [formula](Formula-Cookbook.md#homebrew-terminology), check [homebrew-core](https://github.com/Homebrew/homebrew-core/pulls). If you're submitting a [cask](Formula-Cookbook.md#homebrew-terminology), check [homebrew-cask](https://github.com/Homebrew/homebrew-cask/pulls). You may also want to look through closed pull requests in the repositories, as sometimes packages run into problems preventing them from being updated and it's better to be aware of any issues before putting significant effort into an update.
The [How To Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation should explain most everything you need to know about the process of creating a PR for a version update. For simple updates, this typically involves changing the `url` and `sha256` values.
The [How to Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation should explain most everything you need to know about the process of creating a PR for a version update. For simple updates, this typically involves changing the `url` and `sha256` values.
However, some updates require additional changes to the package. You can look back at previous pull requests to see how others have handled things in the past, but be sure to look at a variety of PRs. Sometimes packages aren't updated properly, so you may need to use your judgment to determine how best to proceed.

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

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