A detailed checklist can be found below. This is all that really matters:
keg_only :provided_by_macosif it already comes with macOS.
brew pr-pullotherwise, which adds messages to auto-close pull requests and pull bottles built by the Brew Test Bot.
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.
Homebrew is about Unix software. Stuff that builds to an
be in Homebrew Cask instead.
For most PRs that make formula modifications, you can simply approve the PR and an automatic merge (with bottles) will be performed by @BrewTestBot. See Brew Test Bot For Core Contributors for more information.
Certain PRs may not be merged automatically by @BrewTestBot,
even after they’ve been approved. This includes PRs with the
linux-only labels. To trigger a merge for these PRs, run
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 for more details.
Otherwise, you should use
brew pr-pull (or
rebase until you finally
master is pushed, you can’t
rebase: you’re a maintainer now!
Cherry-picking changes the date of the commit, which kind of sucks.
merge unclean branches. So if someone is still learning
their branch is filled with nonsensical merges, then
rebase and squash
the commits. Our main branch history should be useful to other people,
Here’s a flowchart for managing a PR which is ready to merge:
Only one maintainer is necessary to approve and merge the addition of a new or updated formula which passes CI. However, if the formula addition or update proves controversial the maintainer who adds it will be expected to answer requests and fix problems that arise with it in future.
Here are guidelines about when to use squash & merge versus rebase & merge. These options should only be used with PRs where bottles are not affected.
|PR modifies a single formula||PR modifies multiple formulae|
|Commits look good||rebase & merge or squash & merge||rebase & merge|
|Commits need work||squash & merge||manually merge using the command line|
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
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).
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.
We now accept versioned formulae as long as they meet the requirements.
We need to at least check that it builds. Use the Brew Test Bot 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.
If the formula uses a repository, then the
url parameter should have a
tag or revision.
urls have versions and are stable (not yet
Don’t merge any formula updates with failing
brew tests. 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.
We now accept stuff that comes with macOS as long as it uses
keg_only :provided_by_macos to be keg-only by default.
BuildErrorrate of <25%
should not be removed from Homebrew. The exception to this rule are versioned formulae 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.
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 requirements.
inreplacethat have been applied to upstream and can be removed
url, as we do skip some versions (for example vim or v8)
erlang@17) that can be upgraded
foobar: fix flibble matrix
bottle block is not removed
Please keep bottle block in place, [@BrewTestBot](https://github.com/BrewTestBot) takes care of it.
# in this example PR is for `libuv` formula and `urbit` needs revision bump brew bump-revision --message 'for libuv' urbit
bottle :unneeded, you can merge it through GitHub UI
automerge-skip): approve the PR to trigger an automatic merge (use
brew pr-publish $PR_IDto trigger manually in case of a new formula)
brew pr-publish $PR_ID
brew pr-pull $PR_ID, make changes, and
brew bump-formula-prnext time if this was not the case