mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity
brew/docs/Homebrew-brew-Maintainer-Guide.md
Rylan Polster 04f5433dcc
docs: update based on suggestions from code review
2021-05-13 20:14:28 -04:00

5.8 KiB
Raw Blame History

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.

Reviewing PRs

Using gh pr checkout NUMBER is a super easy way to check out a PR branch using the GitHub CLI.

When reviewing, choose the "comment" type for reviews when the PR isn't quite ready to be merged. Use the "approve" type when 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. Use the "request changes" type if you feel strongly that the PR is likely to cause a problem for users or have a genuine reason to oppose the PR.

Merging PRs

Merging should be 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) approval. See below for more details about how BrewTestBot approves PRs.
  • Passing CI. This is a mandatory step. PRs with failing CI should never be merged. See below for more information about Homebrew/brew CI.

If possible, PRs should also have:

  • Linear commit history (i.e. no merge commits in PR branches)
  • GPG-signed commits (see the private ops repository for instructions on setting this up)

Automatic approvals

To ensure that each PR has 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 during the business week). After the triage period has expired, the CI job will show up as "passed" and 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 can be applied to the PR. When this label is applied, the Triage CI job will immediately be successful and 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.

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 for more information about RBI files and typechecking.
  • Triage / review: This controls whether the PR has been open for long enough or not. See above for more information about automatic approvals.
  • codecov/patch and codecov/project: These show the Codecov report for the PR. See below for more info about Codecov
  • CI / vendored gems (Linux): This checks whether there was a change to the venered gems on Linux that needs to be committed to the PR branch.
  • CI / test default formula (Linux): This runs brew test-bot 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, Homebrew/linuxbrew-core and all cask repos).
  • CI / docker: This builds and deploys a new Homebrew docker image.
  • CI / test everything (macOS): This runs brew tests on macOS
  • CI / tests (no-compatibility mode), CI / tests (generic OS) and CI / tests (Linux): These run brew tests with various options on Linux.

brew tests and Codecov

A coverage report is generated by Codecov for every PR, and its results are shown as CI jobs. Additionally, annotations will appear in the "Files changed" 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.

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