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.