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.

Maybe you were looking for the Formula Cookbook or Cask Cookbook?

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:

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 to avoid burnout. If you wish to change or discuss any of the guidelines: open a PR to suggest a change.

Reviewing PRs

When reviewing a PR, use “approve”, “approve with comments”, “comment” or “request changes” when submitting based on the following guidelines:

Relatedly:

Mission

Homebrew aims to be the missing package manager for macOS (and Linux). Its primary goal is to be useful to as many people as possible, while remaining maintainable to a professional, high standard by a small group of volunteers. Where possible and sensible, it should seek to use features of macOS to blend in with the macOS and Apple ecosystems. On Linux and Windows, it should seek to be as self-contained as possible.

Common “gotchas”

  1. Ensure you have set your username and email address properly
  2. Sign off cherry-picks if you amended them (use git -s)
  3. If your commit fixes a bug, use issue linking syntax (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 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.

This also applies to issue and PR bodies. Be as explicit as possible. If a pull request is part of a larger initiative: link to a relevant tracking issue. If there isn’t a tracking issue yet: create one to improve communication and get consensus.

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.

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

Maintainers (including the project leader) should not close issues or pull requests (note a merge is not considered a close in this case) opened by other maintainers unless they are stale in which case they can be closed by any maintainer. Any maintainer is encouraged to reopen a closed issue when they wish to do additional work on the issue.

Any maintainer can merge any PR they have carefully reviewed and is passing CI that has been opened by any other maintainer. If you do not wish to have other maintainers merge your PRs: please use the draft pull request status to indicate that until you’re ready to merge it yourself.

Reverting PRs

Any maintainer can revert a PR created by another maintainer after a user submitted issue or CI failure that results. The maintainer who created the original PR should be given no less than an hour to fix the issue themselves or decide to revert the PR themselves if they would rather.

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 to Friday before being merged. For example,

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.

Communication

Maintainers have a variety of ways to communicate with each other:

All communication should ideally occur in public on GitHub. Where this is not possible or appropriate (e.g. a security disclosure, interpersonal issue between two maintainers, urgent breakage that needs to be resolved) this can move to maintainers’ private group communication and, if necessary, 1:1 communication. Technical decisions should not happen in 1:1 communications but if they do (or did in the past) they must end up back as something linkable on GitHub. For example, if a technical decision was made a year ago on Slack and another maintainer/contributor/user asks about it on GitHub, that’s a good chance to explain it to them and have something that can be linked to in the future.

This makes it easier for other maintainers, contributors and users to follow along with what we’re doing (and, more importantly, why we’re doing it) and means that decisions have a linkable URL.

All maintainers (and project leader) communication through any medium is bound by Homebrew’s Code of Conduct. Abusive behaviour towards other maintainers, contributors or users will not be tolerated; the maintainer will be given a warning and if their behaviour continues they will be removed as a maintainer.

Maintainers should feel free to pleasantly disagree with the work and decisions of other maintainers. Healthy, friendly, technical disagreement between maintainers is actively encouraged and should occur in public on the issue tracker to make the project better. Interpersonal issues should be handled privately in Slack, ideally with moderation. If work or decisions are insufficiently documented or explained any maintainer or contributor should feel free to ask for clarification. No maintainer may ever justify a decision with e.g. “because I say so” or “it was I who did X” alone. Off-topic discussions on the issue tracker, bike-shedding and personal attacks are forbidden.

Fork me on GitHub