From 0f472906222c16c4d33265446cb5ddcc0c41e788 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Wed, 12 May 2021 20:54:06 -0400 Subject: [PATCH 01/15] docs: add cask maintainer guide --- docs/Cask-Maintainer-Guide.md | 59 +++++++++++++++++++++++++++++++++++ docs/README.md | 1 + 2 files changed, 60 insertions(+) create mode 100644 docs/Cask-Maintainer-Guide.md diff --git a/docs/Cask-Maintainer-Guide.md b/docs/Cask-Maintainer-Guide.md new file mode 100644 index 0000000000..0650d9c482 --- /dev/null +++ b/docs/Cask-Maintainer-Guide.md @@ -0,0 +1,59 @@ +# 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 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 + +## Common Situations + +Here is a list of the most common situations that arise in 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. +- `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 in formulae, casks do not consider the `sha256` stanza as meaningful security measure as maintainers cannot realistically check them for authenticity. Casks download from upstream; if a malicious actor compromised a URL, they could just as well compromise a version and make it look like an update. + +## Merging + +### Approvals + +In general, PRs in the cask repositories should have at least one approval from a maintainer +before being merged. + +If desired, a maintainer can self-approve one of their PRs using the +`self-approve` GitHub Actions workflow to satisfy this requirement. To trigger a self-approval, navigate to the +["Self-approve a Pull Request" section of the Actions tab](https://github.com/Homebrew/homebrew-cask/actions/workflows/self-approve.yml), +click on "Run workflow", enter the PR number and click "Run workflow". + +### Merge Types + +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. + +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. diff --git a/docs/README.md b/docs/README.md index 94916142dc..e3fc7ddee7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,6 +66,7 @@ - [Releases](Releases.md) - [Developer/Internal API Documentation](https://rubydoc.brew.sh) - [Homebrew/homebrew-core merge checklist](Homebrew-homebrew-core-Merge-Checklist.md) +- [Cask Maintainer Guide](Cask-Maintainer-Guide.md) ## Governance From 068292cfdcf4aa219b0b4ef9a056309c3a38fbe1 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Wed, 12 May 2021 20:59:09 -0400 Subject: [PATCH 02/15] docs: reorganize maintainer guides --- ...w-core-Merge-Checklist.md => Core-Maintainer-Guide.md} | 0 ...core-Maintainer-Guide.md => Linux-Maintainer-Guide.md} | 2 +- docs/README.md | 8 +++++--- 3 files changed, 6 insertions(+), 4 deletions(-) rename docs/{Homebrew-homebrew-core-Merge-Checklist.md => Core-Maintainer-Guide.md} (100%) rename docs/{Homebrew-linuxbrew-core-Maintainer-Guide.md => Linux-Maintainer-Guide.md} (99%) diff --git a/docs/Homebrew-homebrew-core-Merge-Checklist.md b/docs/Core-Maintainer-Guide.md similarity index 100% rename from docs/Homebrew-homebrew-core-Merge-Checklist.md rename to docs/Core-Maintainer-Guide.md diff --git a/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md b/docs/Linux-Maintainer-Guide.md similarity index 99% rename from docs/Homebrew-linuxbrew-core-Maintainer-Guide.md rename to docs/Linux-Maintainer-Guide.md index 2cff970dcc..82ced3a785 100644 --- a/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md +++ b/docs/Linux-Maintainer-Guide.md @@ -1,4 +1,4 @@ -# Homebrew/linuxbrew-core Maintainer Guide +# Linux Maintainer Guide ## Merging formulae updates from Homebrew/homebrew-core diff --git a/docs/README.md b/docs/README.md index e3fc7ddee7..fb7c11bdc4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -59,14 +59,16 @@ - [New Maintainer Checklist](New-Maintainer-Checklist.md) - [Maintainers: Avoiding Burnout](Maintainers-Avoiding-Burnout.md) + - [Maintainer Guidelines](Maintainer-Guidelines.md) -- [Homebrew/linuxbrew-core Maintainer Guide](Homebrew-linuxbrew-core-Maintainer-Guide.md) +- [Core Maintainer Guide](Core-Maintainer-Guide.md) +- [Linux Maintainer Guide](Linux-Maintainer-Guide.md) +- [Cask Maintainer Guide](Cask-Maintainer-Guide.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) -- [Homebrew/homebrew-core merge checklist](Homebrew-homebrew-core-Merge-Checklist.md) -- [Cask Maintainer Guide](Cask-Maintainer-Guide.md) ## Governance From e0230330d03eb40cabf5e725f57ee306b76e4803 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Thu, 13 May 2021 02:30:01 -0400 Subject: [PATCH 03/15] docs: add `brew` maintainer guide --- docs/Brew-Maintainer-Guide.md | 98 +++++++++++++++++++++++ docs/Core-Maintainer-Guide.md | 134 +++++++++++++++++++++++++++---- docs/Maintainer-Guidelines.md | 145 ++++++---------------------------- docs/README.md | 1 + 4 files changed, 241 insertions(+), 137 deletions(-) create mode 100644 docs/Brew-Maintainer-Guide.md diff --git a/docs/Brew-Maintainer-Guide.md b/docs/Brew-Maintainer-Guide.md new file mode 100644 index 0000000000..82813e8b5e --- /dev/null +++ b/docs/Brew-Maintainer-Guide.md @@ -0,0 +1,98 @@ +# `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 repo 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](#automatic-approvals) + 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](#ci) 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](Typechecking.md) 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](#automatic-approvals) for more information about automatic approvals. +- `codecov/patch` and `codecov/project`: These show the Codecov report for the PR. + See [below](#brew-tests-and-codecov) 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](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 shorty if there are any changes. diff --git a/docs/Core-Maintainer-Guide.md b/docs/Core-Maintainer-Guide.md index 443d736559..abc8fabe4c 100644 --- a/docs/Core-Maintainer-Guide.md +++ b/docs/Core-Maintainer-Guide.md @@ -1,23 +1,129 @@ -# Homebrew/homebrew-core Merge Checklist +# Core Maintainer Guide + +## Quick merge checklist + +A detailed checklist can be found [below](#detailed-merge-checklist). This is all that really matters: + +- 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 [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. +- Thank people for contributing. + +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. + +For [some formulae](https://github.com/Homebrew/homebrew-core/search?q=%22homebrew%2Fmirror%22&unscoped_q=%22homebrew%2Fmirror%22), +we mirror the tarballs to our own BinTray automatically as part of the +bottle publish CI run. + +Homebrew is about Unix software. Stuff that builds to an `.app` should +be in Homebrew Cask instead. + +## Naming + +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. + +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](Versions.md). + +## Merging, rebasing, cherry-picking + +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!** + +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. + +Here’s a flowchart for managing a PR which is ready to merge: + +![Flowchart for managing pull requests](assets/img/docs/managing-pull-requests.drawio.svg) + +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. + +### How to merge without bottles + +Here are guidelines about when to use squash & merge versus rebase & merge. These options should only be used with PRs where bottles are not needed or affected. + +| | PR modified 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 | + +## Testing + +We need to at least check that it builds. Use the [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. + +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. + +## Duplicates + +We now accept stuff that comes with macOS as long as it uses `keg_only :provided_by_macos` to be keg-only by default. + +## Removing formulae + +Formulae that: + +- work on at least 2/3 of our supported macOS versions in the default Homebrew prefix +- do not require patches rejected by upstream to work +- do not have known security vulnerabilities or CVEs for the version we package +- are shown to be still installed by users in our analytics with a `BuildError` rate of <25% + +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. + +## 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 [Acceptable Formulae](Acceptable-Formulae.md) requirements. -This is a guiding principle. 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. - -This is a more practical checklist; it should be used after you get familiar with -[Maintainer Guidelines](Maintainer-Guidelines.md). - -## Checklist - -Check for: - - 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)) diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index d9d296a319..609e582df5 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -7,124 +7,38 @@ definitely not a beginner’s guide. Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md)? -This document is current practice. If you wish to change or discuss any of the below: open a PR to suggest a change. +## 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: + +- `brew` maintainers: this team maintains the [`Homebrew/brew`](https://github.com/Homebrew/brew) repository. + See the [`brew` Maintainer Guide](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 [Core Maintainer Guide](Core-Maintainer-Guide.md) for more details about being a core maintainer. +- Linux maintainers: this team maintains the [`Homebrew/linuxbrew-core`](https://github.com/Homebrew/linuxbrew-core) + repository. See the [Linux Maintainer Guide](Linux-Maintainer-Guide.md) for more details about being a Linux maintainer. +- 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 [Cask Maintainer Guide](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. ## 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. -## Quick checklist - -This is all that really matters: - -- 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 [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. -- Thank people for contributing. - -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. - -For [some formulae](https://github.com/Homebrew/homebrew-core/search?q=%22homebrew%2Fmirror%22&unscoped_q=%22homebrew%2Fmirror%22), -we mirror the tarballs to our own BinTray automatically as part of the -bottle publish CI run. - -Homebrew is about Unix software. Stuff that builds to an `.app` should -be in Homebrew Cask instead. - -### Naming - -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. - -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](Versions.md). - -### Merging, rebasing, cherry-picking - -Merging should be done in the `Homebrew/brew` repository to preserve history and GPG commit signing. - -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!** - -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. - -Here’s a flowchart for managing a PR which is ready to merge: - -![Flowchart for managing pull requests](assets/img/docs/managing-pull-requests.drawio.svg) - -#### How to merge without bottles - -Here are guidelines about when to use squash & merge versus rebase & merge. These options should only be used with PRs where bottles are not needed or affected. - -| | PR modified 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 | - -### Testing - -We need to at least check that it builds. Use the [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. - -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. - ## Common “gotchas” 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 -### Duplicates - -We now accept stuff that comes with macOS as long as it uses `keg_only :provided_by_macos` to be keg-only by default. - ### Add comments It may be enough to refer to an issue ticket, but make sure changes are clear so that @@ -143,21 +57,6 @@ 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. -### Adding or updating formulae - -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. - -### Removing formulae - -Formulae that: - -- work on at least 2/3 of our supported macOS versions in the default Homebrew prefix -- do not require patches rejected by upstream to work -- do not have known security vulnerabilities or CVEs for the version we package -- are shown to be still installed by users in our analytics with a `BuildError` rate of <25% - -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. - ### Closing issues/PRs Maintainers (including the lead maintainer) 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 (i.e. have seen no updates for 28 days) 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. @@ -178,7 +77,7 @@ PRs that are an "enhancement" to existing functionality i.e. not a fix to an ope 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). -The vast majority of Homebrew/homebrew-core PRs are bug fixes or version bumps so can be self-merged once CI has completed. +The vast majority of `Homebrew/homebrew-core` PRs are bug fixes or version bumps so can be self-merged once CI has completed. ## Communication diff --git a/docs/README.md b/docs/README.md index fb7c11bdc4..957cd58977 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,6 +61,7 @@ - [Maintainers: Avoiding Burnout](Maintainers-Avoiding-Burnout.md) - [Maintainer Guidelines](Maintainer-Guidelines.md) +- [`brew` Maintainer Guide](Brew-Maintainer-Guide.md) - [Core Maintainer Guide](Core-Maintainer-Guide.md) - [Linux Maintainer Guide](Linux-Maintainer-Guide.md) - [Cask Maintainer Guide](Cask-Maintainer-Guide.md) From ce2a942d6791f7e0d2969b88ab19d94cb2196803 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Thu, 13 May 2021 02:34:31 -0400 Subject: [PATCH 04/15] docs: temporarily rename core maintainer guide --- ...ainer-Guide.md => Homebrew-homebrew-core-Merge-Checklist.md} | 0 docs/Maintainer-Guidelines.md | 2 +- docs/README.md | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename docs/{Core-Maintainer-Guide.md => Homebrew-homebrew-core-Merge-Checklist.md} (100%) diff --git a/docs/Core-Maintainer-Guide.md b/docs/Homebrew-homebrew-core-Merge-Checklist.md similarity index 100% rename from docs/Core-Maintainer-Guide.md rename to docs/Homebrew-homebrew-core-Merge-Checklist.md diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index 609e582df5..10794bc3b3 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -15,7 +15,7 @@ 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 [`brew` Maintainer Guide](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 [Core Maintainer Guide](Core-Maintainer-Guide.md) for more details about being a core maintainer. + repository. See the [Core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md) for more details about being a core maintainer. - Linux maintainers: this team maintains the [`Homebrew/linuxbrew-core`](https://github.com/Homebrew/linuxbrew-core) repository. See the [Linux Maintainer Guide](Linux-Maintainer-Guide.md) for more details about being a Linux maintainer. - Cask maintainers: this team maintains the [`Homebrew/homebrew-cask`](https://github.com/Homebrew/homebrew-cask), diff --git a/docs/README.md b/docs/README.md index 957cd58977..f062d09d5d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -62,7 +62,7 @@ - [Maintainer Guidelines](Maintainer-Guidelines.md) - [`brew` Maintainer Guide](Brew-Maintainer-Guide.md) -- [Core Maintainer Guide](Core-Maintainer-Guide.md) +- [Core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md) - [Linux Maintainer Guide](Linux-Maintainer-Guide.md) - [Cask Maintainer Guide](Cask-Maintainer-Guide.md) From 73ca9a0e05efa24c9e26011271729589d48e481b Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Thu, 13 May 2021 02:51:15 -0400 Subject: [PATCH 05/15] docs: add cask cookbook link to maintainer guidlines --- docs/Maintainer-Guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index 10794bc3b3..1b5f21eb58 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -5,7 +5,7 @@ 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)? +Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md) or [Cask Cookbook](Cask-Cookbook.md)? ## Overview From 04f5433dccdbac4eb27730c2dd9a1830b0a70dfa Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Thu, 13 May 2021 20:14:28 -0400 Subject: [PATCH 06/15] docs: update based on suggestions from code review --- ...r-Guide.md => Homebrew-brew-Maintainer-Guide.md} | 6 +++--- ...d => Homebrew-homebrew-cask-Maintainer-Guide.md} | 13 +++++++------ docs/Homebrew-homebrew-core-Merge-Checklist.md | 12 +++++++----- ... => Homebrew-linuxbrew-core-Maintainer-Guide.md} | 2 +- docs/Maintainer-Guidelines.md | 11 +++++++---- 5 files changed, 25 insertions(+), 19 deletions(-) rename docs/{Brew-Maintainer-Guide.md => Homebrew-brew-Maintainer-Guide.md} (96%) rename docs/{Cask-Maintainer-Guide.md => Homebrew-homebrew-cask-Maintainer-Guide.md} (87%) rename docs/{Linux-Maintainer-Guide.md => Homebrew-linuxbrew-core-Maintainer-Guide.md} (99%) diff --git a/docs/Brew-Maintainer-Guide.md b/docs/Homebrew-brew-Maintainer-Guide.md similarity index 96% rename from docs/Brew-Maintainer-Guide.md rename to docs/Homebrew-brew-Maintainer-Guide.md index 82813e8b5e..84a9415987 100644 --- a/docs/Brew-Maintainer-Guide.md +++ b/docs/Homebrew-brew-Maintainer-Guide.md @@ -1,11 +1,11 @@ -# `brew` Maintainer Guide +# 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 repo checkout NUMBER` is a super easy way to check out a PR branch using the GitHub CLI. +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 @@ -95,4 +95,4 @@ merged. These follow-up PRs can be merged immediately if the changes seem correc 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 shorty if there are any changes. +A PR will be opened shortly if there are any changes. diff --git a/docs/Cask-Maintainer-Guide.md b/docs/Homebrew-homebrew-cask-Maintainer-Guide.md similarity index 87% rename from docs/Cask-Maintainer-Guide.md rename to docs/Homebrew-homebrew-cask-Maintainer-Guide.md index 0650d9c482..d5f5970141 100644 --- a/docs/Cask-Maintainer-Guide.md +++ b/docs/Homebrew-homebrew-cask-Maintainer-Guide.md @@ -1,4 +1,4 @@ -# Cask Maintainer Guide +# 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). @@ -14,7 +14,7 @@ This guide applies to all four of the cask repositories: Here is a list of the most common situations that arise in PRs and how to handle them: -- The `version` and `sha256` both change (keeping the same format): Merge +- 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. - `livecheck` is updated: Use your best judgement and try to make sure that the changes @@ -31,11 +31,12 @@ Note that unlike in formulae, casks do not consider the `sha256` stanza as meani ### Approvals -In general, PRs in the cask repositories should have at least one approval from a maintainer -before being merged. +PRs in the cask repositories should must have at least one approval +from a user with write access before they can be merged. -If desired, a maintainer can self-approve one of their PRs using the -`self-approve` GitHub Actions workflow to satisfy this requirement. To trigger a self-approval, navigate to the +Ideally, this approval will come from another maintainer. If necessary, however, a maintainer +can self-approve one of their PRs using the `self-approve` GitHub Actions workflow to satisfy +this requirement. To trigger a self-approval, navigate to the ["Self-approve a Pull Request" section of the Actions tab](https://github.com/Homebrew/homebrew-cask/actions/workflows/self-approve.yml), click on "Run workflow", enter the PR number and click "Run workflow". diff --git a/docs/Homebrew-homebrew-core-Merge-Checklist.md b/docs/Homebrew-homebrew-core-Merge-Checklist.md index abc8fabe4c..bba579ac5e 100644 --- a/docs/Homebrew-homebrew-core-Merge-Checklist.md +++ b/docs/Homebrew-homebrew-core-Merge-Checklist.md @@ -1,4 +1,4 @@ -# Core Maintainer Guide +# Homebrew/homebrew-core Maintainer Guide ## Quick merge checklist @@ -23,10 +23,6 @@ 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. -For [some formulae](https://github.com/Homebrew/homebrew-core/search?q=%22homebrew%2Fmirror%22&unscoped_q=%22homebrew%2Fmirror%22), -we mirror the tarballs to our own BinTray automatically as part of the -bottle publish CI run. - Homebrew is about Unix software. Stuff that builds to an `.app` should be in Homebrew Cask instead. @@ -39,6 +35,9 @@ 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). + 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. @@ -117,6 +116,9 @@ 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) + ## Detailed merge checklist The following checklist is intended to help maintainers decide on diff --git a/docs/Linux-Maintainer-Guide.md b/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md similarity index 99% rename from docs/Linux-Maintainer-Guide.md rename to docs/Homebrew-linuxbrew-core-Maintainer-Guide.md index 82ced3a785..2cff970dcc 100644 --- a/docs/Linux-Maintainer-Guide.md +++ b/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md @@ -1,4 +1,4 @@ -# Linux Maintainer Guide +# Homebrew/linuxbrew-core Maintainer Guide ## Merging formulae updates from Homebrew/homebrew-core diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index 1b5f21eb58..d67448bbea 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -13,16 +13,19 @@ All Homebrew maintainers are encouraged to contribute to all parts of the projec 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 [`brew` Maintainer Guide](Brew-Maintainer-Guide.md) for more details about being a `brew` maintainer. + 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 [Core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md) for more details about being a core maintainer. + repository. See the [Homebrew/homebrew-core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md) + for more details about being a core maintainer. - Linux maintainers: this team maintains the [`Homebrew/linuxbrew-core`](https://github.com/Homebrew/linuxbrew-core) - repository. See the [Linux Maintainer Guide](Linux-Maintainer-Guide.md) for more details about being a Linux maintainer. + repository. See the [Homebrew/linuxbrew-core Maintainer Guide](Homebrew-linuxbrew-core-Maintainer-Guide.md) + for more details about being a Linux maintainer. - 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 [Cask Maintainer Guide](Cask-Maintainer-Guide.md) for more details about being a cask maintainer. + 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. From de5fd4642d58f6c905b98ad9b4f7d7ed5b5e13ed Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Fri, 14 May 2021 13:49:16 -0400 Subject: [PATCH 07/15] docs: update based on suggestions from code review Co-Authored-By: Eric Knibbe <3324775+EricFromCanada@users.noreply.github.com> --- docs/Homebrew-brew-Maintainer-Guide.md | 30 +++++++++++-------- ...Homebrew-homebrew-cask-Maintainer-Guide.md | 17 ++++++----- .../Homebrew-homebrew-core-Merge-Checklist.md | 6 ++-- docs/Maintainer-Guidelines.md | 2 +- docs/README.md | 8 ++--- 5 files changed, 34 insertions(+), 29 deletions(-) diff --git a/docs/Homebrew-brew-Maintainer-Guide.md b/docs/Homebrew-brew-Maintainer-Guide.md index 84a9415987..e0a622d1ba 100644 --- a/docs/Homebrew-brew-Maintainer-Guide.md +++ b/docs/Homebrew-brew-Maintainer-Guide.md @@ -7,10 +7,13 @@ be aware of, but don't necessarily need to appear in documentation for most user 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. +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 a genuine reason to oppose the PR. ## Merging PRs @@ -20,13 +23,13 @@ PRs must meet the following conditions to be merged: - Have at least one maintainer (or `BrewTestBot`) approval. See [below](#automatic-approvals) for more details about how `BrewTestBot` approves PRs. -- Passing CI. This is a _mandatory_ step. PRs with failing CI should _never_ be merged. +- Have passing CI. This is a _mandatory_ step. PRs with failing CI should _never_ be merged. See [below](#ci) 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) +- 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 @@ -56,27 +59,28 @@ There are many checks that run on every PR. The following is a quick list of the - `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 controls whether the PR has been open for long enough or not. +- `Triage / review`: This verifies that the PR has been open for long enough. See [above](#automatic-approvals) for more information about automatic approvals. - `codecov/patch` and `codecov/project`: These show the Codecov report for the PR. - See [below](#brew-tests-and-codecov) 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 + See [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. -- `CI / test default formula (Linux)`: This runs `brew test-bot` Linux to ensure it still works as expected. +- `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`, `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 / 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 +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. diff --git a/docs/Homebrew-homebrew-cask-Maintainer-Guide.md b/docs/Homebrew-homebrew-cask-Maintainer-Guide.md index d5f5970141..712a4a0f21 100644 --- a/docs/Homebrew-homebrew-cask-Maintainer-Guide.md +++ b/docs/Homebrew-homebrew-cask-Maintainer-Guide.md @@ -12,7 +12,7 @@ This guide applies to all four of the cask repositories: ## Common Situations -Here is a list of the most common situations that arise in PRs and how to handle them: +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. @@ -25,18 +25,19 @@ Here is a list of the most common situations that arise in PRs and how to handle If in doubt, ask another cask maintainer on GitHub or Slack. -Note that unlike in formulae, casks do not consider the `sha256` stanza as meaningful security measure as maintainers cannot realistically check them for authenticity. Casks download from upstream; if a malicious actor compromised a URL, they could just as well 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 just as well compromise a version and make it look like an update. ## Merging ### Approvals -PRs in the cask repositories should must have at least one approval -from a user with write access before they can be merged. - -Ideally, this approval will come from another maintainer. If necessary, however, a maintainer -can self-approve one of their PRs using the `self-approve` GitHub Actions workflow to satisfy -this requirement. To trigger a self-approval, navigate to the +Most PRs in the cask repositories are simple version bumps that don't necessarily need +another maintainer's approval. However, GitHub will not allow a PR to be merged without +at least one approving review. To bypass this requirement if necessary, a maintainer +can self-approve one of their PRs using the `self-approve` GitHub Actions workflow to +satisfy this requirement. To trigger a self-approval, navigate to the ["Self-approve a Pull Request" section of the Actions tab](https://github.com/Homebrew/homebrew-cask/actions/workflows/self-approve.yml), click on "Run workflow", enter the PR number and click "Run workflow". diff --git a/docs/Homebrew-homebrew-core-Merge-Checklist.md b/docs/Homebrew-homebrew-core-Merge-Checklist.md index bba579ac5e..b3c858c7fe 100644 --- a/docs/Homebrew-homebrew-core-Merge-Checklist.md +++ b/docs/Homebrew-homebrew-core-Merge-Checklist.md @@ -72,7 +72,7 @@ Only one maintainer is necessary to approve and merge the addition of a new or u Here are guidelines about when to use squash & merge versus rebase & merge. These options should only be used with PRs where bottles are not needed or affected. -| | PR modified a single formula | PR modifies multiple formulae | +| | 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 | @@ -117,13 +117,13 @@ 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) +[Deprecating, Disabling, and Removing Formulae page](Deprecating-Disabling-and-Removing-Formulae.md). ## 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 +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 diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index d67448bbea..b74b08bf5c 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -80,7 +80,7 @@ PRs that are an "enhancement" to existing functionality i.e. not a fix to an ope 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). -The vast majority of `Homebrew/homebrew-core` PRs are bug fixes or version bumps so can be self-merged once CI has completed. +The vast majority of `Homebrew/homebrew-core` PRs are bug fixes or version bumps which can be self-merged once CI has completed. ## Communication diff --git a/docs/README.md b/docs/README.md index f062d09d5d..df46165646 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,10 +61,10 @@ - [Maintainers: Avoiding Burnout](Maintainers-Avoiding-Burnout.md) - [Maintainer Guidelines](Maintainer-Guidelines.md) -- [`brew` Maintainer Guide](Brew-Maintainer-Guide.md) -- [Core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md) -- [Linux Maintainer Guide](Linux-Maintainer-Guide.md) -- [Cask Maintainer Guide](Cask-Maintainer-Guide.md) +- [Homebrew/brew Maintainer Guide](Homebrew-brew-Maintainer-Guide.md) +- [Homebrew/homebrew-core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md) +- [Homebrew/linuxbrew-core Maintainer Guide](Homebrew-linuxbrew-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) - [Common Issues for Maintainers](Common-Issues-for-Core-Contributors.md) From ba22ec64471d78364eb63ec3d4be32797d16aad1 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Fri, 14 May 2021 14:04:09 -0400 Subject: [PATCH 08/15] docs: update vale config with new titles --- docs/vale-styles/Homebrew/Titles.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/vale-styles/Homebrew/Titles.yml b/docs/vale-styles/Homebrew/Titles.yml index 7f92482915..b96b78be6e 100644 --- a/docs/vale-styles/Homebrew/Titles.yml +++ b/docs/vale-styles/Homebrew/Titles.yml @@ -7,6 +7,8 @@ style: AP exceptions: - brew(1) - macOS + - Homebrew/brew - Homebrew/homebrew-core - Homebrew/linuxbrew-core + - Homebrew/homebrew-cask - (or Linux) From 46af59fe3a4caba617fb568c889d16ac07775741 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Tue, 18 May 2021 02:39:33 -0400 Subject: [PATCH 09/15] docs: update based on suggestions from code review Co-Authored-By: Mike McQuaid --- docs/Homebrew-brew-Maintainer-Guide.md | 45 ++++++++++--------- ...Homebrew-homebrew-cask-Maintainer-Guide.md | 15 +------ .../Homebrew-homebrew-core-Merge-Checklist.md | 45 ++++++++++--------- 3 files changed, 51 insertions(+), 54 deletions(-) diff --git a/docs/Homebrew-brew-Maintainer-Guide.md b/docs/Homebrew-brew-Maintainer-Guide.md index e0a622d1ba..bcacd32780 100644 --- a/docs/Homebrew-brew-Maintainer-Guide.md +++ b/docs/Homebrew-brew-Maintainer-Guide.md @@ -13,41 +13,41 @@ When reviewing a PR, use "comment", "approve", or "request changes" when submitt - 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 a genuine reason to oppose the PR. + have another 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. +Merging is 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](#automatic-approvals) - for more details about how `BrewTestBot` approves PRs. +- 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 [below](#ci) for more information about `Homebrew/brew` CI. + See the ["CI" section below](#ci) 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). +If possible, PRs should also have 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 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 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. +(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 -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. +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 @@ -62,7 +62,7 @@ There are many checks that run on every PR. The following is a quick list of the - `Triage / review`: This verifies that the PR has been open for long enough. See [above](#automatic-approvals) for more information about automatic approvals. - `codecov/patch` and `codecov/project`: These show the Codecov report for the PR. - See [below](#brew-tests-and-codecov) for more info about Codecov. + 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. - `CI / test default formula (Linux)`: This runs `brew test-bot` on Linux to ensure it still works as expected. @@ -71,11 +71,14 @@ There are many checks that run on every PR. The following is a quick list of the - `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 / 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. +_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. @@ -93,8 +96,8 @@ but this should be avoided if possible. 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. +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) diff --git a/docs/Homebrew-homebrew-cask-Maintainer-Guide.md b/docs/Homebrew-homebrew-cask-Maintainer-Guide.md index 712a4a0f21..5a1cf7d147 100644 --- a/docs/Homebrew-homebrew-cask-Maintainer-Guide.md +++ b/docs/Homebrew-homebrew-cask-Maintainer-Guide.md @@ -17,6 +17,7 @@ Here is a list of the most common situations that arise in cask PRs and how to h - 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 @@ -27,22 +28,10 @@ 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 just as well compromise a version and make it look like an update. +actor compromised a URL, they could potentially compromise a version and make it look like an update. ## Merging -### Approvals - -Most PRs in the cask repositories are simple version bumps that don't necessarily need -another maintainer's approval. However, GitHub will not allow a PR to be merged without -at least one approving review. To bypass this requirement if necessary, a maintainer -can self-approve one of their PRs using the `self-approve` GitHub Actions workflow to -satisfy this requirement. To trigger a self-approval, navigate to the -["Self-approve a Pull Request" section of the Actions tab](https://github.com/Homebrew/homebrew-cask/actions/workflows/self-approve.yml), -click on "Run workflow", enter the PR number and click "Run workflow". - -### Merge Types - 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. diff --git a/docs/Homebrew-homebrew-core-Merge-Checklist.md b/docs/Homebrew-homebrew-core-Merge-Checklist.md index b3c858c7fe..31fec5c9c8 100644 --- a/docs/Homebrew-homebrew-core-Merge-Checklist.md +++ b/docs/Homebrew-homebrew-core-Merge-Checklist.md @@ -13,7 +13,8 @@ A detailed checklist can be found [below](#detailed-merge-checklist). This is al [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 [below](#how-to-merge-without-bottles) for more details. +- 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. - Thank people for contributing. @@ -26,26 +27,12 @@ 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. -## Naming - -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. - -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](Versions.md). - ## Merging, rebasing, cherry-picking +In most cases, you can simply approve a 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. + 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. @@ -70,13 +57,31 @@ Only one maintainer is necessary to approve and merge the addition of a new or u ### How to merge without bottles -Here are guidelines about when to use squash & merge versus rebase & merge. These options should only be used with PRs where bottles are not needed or affected. +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 | +## Naming + +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. + +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](Versions.md). + ## Testing We need to at least check that it builds. Use the [Brew Test Bot](Brew-Test-Bot.md) for this. From ac6b4dbe6e6921f6cb33fbbd87d4f39416a6af90 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Tue, 18 May 2021 02:39:57 -0400 Subject: [PATCH 10/15] docs: update new maintainer checklist --- docs/New-Maintainer-Checklist.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/New-Maintainer-Checklist.md b/docs/New-Maintainer-Checklist.md index fefc93f8a7..bcf1968c84 100644 --- a/docs/New-Maintainer-Checklist.md +++ b/docs/New-Maintainer-Checklist.md @@ -26,28 +26,24 @@ contribute to Homebrew, but we will ask you to step down as a maintainer. A few requests: -- Please make pull requests on any changes to Homebrew/brew code or any - non-trivial (e.g. not a test or audit improvement or version bump) changes - to formulae code and don't merge them unless you get at least one approval +- Please make pull requests for any changes in the Homebrew repositories (instead + of committing directly) and don't merge them unless you get at least one approval and passing tests. -- In Homebrew/brew, close pull requests using GitHub's "Merge pull request" - button in "Create a merge commit" mode. -- In Homebrew/homebrew-core, use `brew pr-publish` to close pull requests - that require new bottles or change multiple formulae. Note that an approving - review on a pull request for an existing formula will trigger this automatically. - If commits need to be amended use `brew pr-pull` instead. Let these commands - auto-close issues whenever possible (it may take up to 5 minutes). If in doubt, - check with e.g. Fork.app that you've not accidentally added merge commits. - If bottles are unnecessary, use GitHub's "Merge pull request" button in - "Squash and merge" mode for a single formula change. +- Please review the Maintainer Guidelines at https://docs.brew.sh/Maintainer-Guidelines +- Please review the team-specific guides for whichever teams you will be a part of. + Here are links to these guides: + - Homebrew/brew: https://docs.brew.sh/Homebrew-brew-Maintainer-Guide + - Homebrew/homebrew-core: https://docs.brew.sh/Homebrew-homebrew-core-Maintainer-Guide + - Homebrew/linuxbrew-core: https://docs.brew.sh/Homebrew-linuxbrew-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. 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. - If still in doubt please ask for help and we'll help you out. - Please read: - - https://docs.brew.sh/Brew-Test-Bot-For-Core-Contributors - https://docs.brew.sh/Maintainer-Guidelines + - the team-specific guides linked above and in the maintainer guidelines - anything else you haven't read on https://docs.brew.sh How does that sound? From 6bcb3bd3678f3975e79a4688a1766ad940b5cfc4 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Tue, 18 May 2021 02:43:16 -0400 Subject: [PATCH 11/15] docs: clarify link to above section --- docs/Homebrew-brew-Maintainer-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Homebrew-brew-Maintainer-Guide.md b/docs/Homebrew-brew-Maintainer-Guide.md index bcacd32780..8db6e98759 100644 --- a/docs/Homebrew-brew-Maintainer-Guide.md +++ b/docs/Homebrew-brew-Maintainer-Guide.md @@ -60,7 +60,7 @@ There are many checks that run on every PR. The following is a quick list of the 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 [above](#automatic-approvals) for more information about automatic approvals. + 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 From 93ef624649ae50890a114e7f9d5c3a500679c194 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Tue, 18 May 2021 10:15:08 -0400 Subject: [PATCH 12/15] docs: remove mailing list references --- docs/New-Maintainer-Checklist.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/New-Maintainer-Checklist.md b/docs/New-Maintainer-Checklist.md index bcf1968c84..5be3945bd6 100644 --- a/docs/New-Maintainer-Checklist.md +++ b/docs/New-Maintainer-Checklist.md @@ -54,7 +54,6 @@ Thanks for all your work so far! If they accept, follow a few steps to get them set up: - Invite them to the [**@Homebrew/maintainers** team](https://github.com/orgs/Homebrew/teams/maintainers) (or any relevant [subteams](https://github.com/orgs/Homebrew/teams/maintainers/teams)) to give them write access to relevant repositories (but don't make them owners). They will need to enable [GitHub's Two Factor Authentication](https://help.github.com/articles/about-two-factor-authentication/). -- Invite them to the [`homebrew-maintainers` private maintainers mailing list](https://lists.sfconservancy.org/mailman/admin/homebrew-maintainers/members/add). - Invite them to the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin/invites) (and ensure they've read the [communication guidelines](Maintainer-Guidelines.md#communication)) and ask them to use their real name there (rather than a pseudonym they may use on e.g. GitHub). - Ask them to disable SMS as a 2FA device or fallback on their GitHub account in favour of using one of the other authentication methods. - Ask them to (regularly) review remove any unneeded [GitHub personal access tokens](https://github.com/settings/tokens). @@ -62,7 +61,6 @@ If they accept, follow a few steps to get them set up: If they are interested in doing system administration work: -- Invite them to the [`homebrew-ops` private operations mailing list](https://lists.sfconservancy.org/mailman/admin/homebrew-ops/members/add). - Invite them to the [`homebrew` private 1Password](https://homebrew.1password.com/people). - Optionally: make them [owners on the Homebrew GitHub organisation](https://github.com/orgs/Homebrew/people) if they need to access organisation-wide settings (like GitHub Actions organisation shared runners). From 817914fc042015ebfed558637a3dd592f3e67337 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Tue, 18 May 2021 14:01:05 -0400 Subject: [PATCH 13/15] docs: fix wording in brew maintainer guide --- docs/Homebrew-brew-Maintainer-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Homebrew-brew-Maintainer-Guide.md b/docs/Homebrew-brew-Maintainer-Guide.md index 8db6e98759..85db2e45eb 100644 --- a/docs/Homebrew-brew-Maintainer-Guide.md +++ b/docs/Homebrew-brew-Maintainer-Guide.md @@ -17,7 +17,7 @@ When reviewing a PR, use "comment", "approve", or "request changes" when submitt ## Merging PRs -Merging is be done using the standard Merge button in the `Homebrew/brew` repository to preserve +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: From 8edd4d3facdf6384f624380036440ff7378ba134 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Wed, 19 May 2021 12:50:34 -0400 Subject: [PATCH 14/15] docs: cleanup core merge info --- docs/Homebrew-homebrew-core-Merge-Checklist.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/Homebrew-homebrew-core-Merge-Checklist.md b/docs/Homebrew-homebrew-core-Merge-Checklist.md index 31fec5c9c8..1073223919 100644 --- a/docs/Homebrew-homebrew-core-Merge-Checklist.md +++ b/docs/Homebrew-homebrew-core-Merge-Checklist.md @@ -29,10 +29,14 @@ be in Homebrew Cask instead. ## Merging, rebasing, cherry-picking -In most cases, you can simply approve a PR and an automatic merge (with bottles) -will be performed by [@BrewTestBot](https://github.com/BrewTestBot). +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. +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. From 52f4025c619edccac4d38cf7903e011afc732b50 Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Wed, 19 May 2021 12:52:28 -0400 Subject: [PATCH 15/15] docs: rename core maintainer guide for consistency --- ...-Checklist.md => Homebrew-homebrew-core-Maintainer-Guide.md} | 0 docs/Maintainer-Guidelines.md | 2 +- docs/README.md | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename docs/{Homebrew-homebrew-core-Merge-Checklist.md => Homebrew-homebrew-core-Maintainer-Guide.md} (100%) diff --git a/docs/Homebrew-homebrew-core-Merge-Checklist.md b/docs/Homebrew-homebrew-core-Maintainer-Guide.md similarity index 100% rename from docs/Homebrew-homebrew-core-Merge-Checklist.md rename to docs/Homebrew-homebrew-core-Maintainer-Guide.md diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index b74b08bf5c..4689c0f2bf 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -15,7 +15,7 @@ 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-Merge-Checklist.md) + 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/linuxbrew-core`](https://github.com/Homebrew/linuxbrew-core) repository. See the [Homebrew/linuxbrew-core Maintainer Guide](Homebrew-linuxbrew-core-Maintainer-Guide.md) diff --git a/docs/README.md b/docs/README.md index df46165646..7a2cc53a50 100644 --- a/docs/README.md +++ b/docs/README.md @@ -62,7 +62,7 @@ - [Maintainer Guidelines](Maintainer-Guidelines.md) - [Homebrew/brew Maintainer Guide](Homebrew-brew-Maintainer-Guide.md) -- [Homebrew/homebrew-core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md) +- [Homebrew/homebrew-core Maintainer Guide](Homebrew-homebrew-core-Maintainer-Guide.md) - [Homebrew/linuxbrew-core Maintainer Guide](Homebrew-linuxbrew-core-Maintainer-Guide.md) - [Homebrew/homebrew-cask Maintainer Guide](Homebrew-homebrew-cask-Maintainer-Guide.md)