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.

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.

PRs must meet the following conditions to be merged:

  • Have at least one maintainer approval.
  • Have passing CI (continuous integration). This is a mandatory step. PRs with failing CI should never be merged. See the CI section below for more information about Homebrew/brew CI.

If possible, PRs should also have signed commits.

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. Stale Homebrew/brew PRs by lead maintainers may be approved automatically by github-actions[bot] after being open for at least 48 hours without human review when the PR is not from a fork, is not a draft, the author has approved another Homebrew/brew PR in the last 7 days, Copilot has already reviewed the PR, all CI jobs are passing, the workflow is running on a weekday and the PR does not modify sensitive paths. If the 48-hour window expires at the weekend, the workflow waits until Monday. The prior approval may be on a Homebrew/brew PR from a fork, because that approval is only evidence of recent maintainer review activity.

CI

Every PR in Homebrew/brew runs continuous-integration checks intended to prevent regressions. A PR must have passing required checks before it can be merged.

Depending on the files changed, the workflows check type signatures and style, run unit and integration tests on macOS and Linux, audit formulae and casks, validate vendored dependencies, build the documentation and test packaging such as the Docker image. Codecov reports test coverage separately. The current GitHub Actions workflows and the pull request’s checks are authoritative; job names and path-based triggers 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. 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 also monitors CI jobs for every push to Homebrew/brew to detect flaky tests and track them over time. The reports are available on CodeCov.

CodeCov 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, CodeCov 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 CodeCov to determine if the test always fails the same way.

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 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 sponsors, maintainers, manpage and completions 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.