Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update maintainer documentation. #5724

Merged
merged 2 commits into from
Feb 14, 2019
Merged

Update maintainer documentation. #5724

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1b609ce
Update maintainer documentation.
MikeMcQuaid Feb 13, 2019
bf87378
Apply suggestions from code review
MikeMcQuaid Feb 14, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
32 changes: 21 additions & 11 deletions docs/Maintainer-Guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This document is current practice. If you wish to change or discuss any of the b

## Mission

Homebrew aims to be the missing package manager for macOS. 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.
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

Expand All @@ -34,13 +34,14 @@ Checking dependencies is important, because they will probably stick around
forever. Nobody really checks if they are necessary or not. Use the
`:optional` and `:recommended` modifiers as appropriate.

Depend on as little stuff as possible. Disable X11 functionality by default.
For example, we build Wireshark, but not the heavy GTK/Qt GUI by default.
Depend on as little stuff as possible. Disable X11 functionality if possible.
For example, we build Wireshark, but not the heavy GUI.

Homebrew is about Unix software. Stuff that builds to an `.app` should
probably be in Homebrew Cask instead.
be in Homebrew Cask instead.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding this change, I’ve been thinking of mpv recently (formula, cask). The formula builds a .app, and according to the analytics it is almost ten times as popular as the cask. In addition, the cask uses the builds made not by the team, but a user that they trust (and link to directly and officially in the page).

Due to this, I have been considering removing the cask (I’m informally trying to query people to see how disruptive it is for their use of mpv that he app bundle is in a versioned directory in Cellar instead of /Applications). Does the removal of probably mean we should remove the formula instead?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the removal of probably mean we should remove the formula instead?

We shouldn't remove the formula but we should remove the .app that the formula builds. In general where something is useful on the command-line the formula should remain and the Cask be the "GUI install". How's that sound?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apologies for the length of the reply. I did try making it shorter. Maybe I should open an issue for discussion.

We shouldn't remove the formula but we should remove the .app that the formula builds.

I’m guessing the mpv formula includes the app because --with-bundle was popular. So removing the bundle will make users open issues.

To clarify, I like the formula (I use it instead of the cask) and think there is value to some formulae building .apps — cases where the dev team does not have someone in charge of making the bundles. For example, in Cask we are some versions behind on Inkscape (fun fact: also part of the SFC) because they have no macOS devs.

I’d be fine with removing those casks in favour of the formulae counterparts, as I think users would be better served when the alternative is having older software. But the brew/brew cask division is confusing for users and separating by CLI/GUI makes sense, so maybe app-building-formulae should be restricted to third party taps. To push the point further, maybe CLI-only casks (closed-source) should be removed as well.

But the cask can also install the CLI. I’m open to removing that line, but I guess some users would be unhappy to have to brew install mpv && brew cask install mpv to get both the CLI and the GUI versions. It would help bring home the HB is CLI and HBC is GUI point, but might it also cause problems stemming from different installed versions of the CLI and GUI? That makes me ambivalent to removing the binary stanza from the cask.

But otherwise, if you do think app bundles should be removed from formulae, the rule would be “if want the CLI, brew, if you want the GUI, brew cask but it would also bring the CLI that typically comes in the package”.

Some casks tried to make that clearer (mkvtoolnix) by adding an -app suffix, but that’s confusing even to maintainers. That suffix was added in the spirit of deduplication, but now we should probably get rid of that rule and rename those casks.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For context, right now in homebrew-core there are at least 33 formulae that build apps:

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I should open an issue for discussion.

Yeh, good idea. I've replied inline to your comment but would be good to move future conversation to one.

To clarify, I like the formula (I use it instead of the cask) and think there is value to some formulae building .apps — cases where the dev team does not have someone in charge of making the bundles.

The problem with formulae building apps is the way Homebrew handles apps is a mess. We removed the brew linkapps commands for this reason and generally application bundles that are created are not "real" i.e. relocatable or including their dependencies. It's a shitty experience, basically.

For example, in Cask we are some versions behind on Inkscape (fun fact: also part of the SFC) because they have no macOS devs.

Yeh, I'm aware of this. To me this does seem fairly similar to the days of when we weren't favouring X11, required Clang, etc. in that we're partly acting as a forcing function to produce a better macOS ecosystem. We should make it easier to package well-packaged macOS applications than the opposite.

I’d be fine with removing those casks in favour of the formulae counterparts, as I think users would be better served when the alternative is having older software. But the brew/brew cask division is confusing for users and separating by CLI/GUI makes sense, so maybe app-building-formulae should be restricted to third party taps. To push the point further, maybe CLI-only casks (closed-source) should be removed as well.

I really don't want to remove even older GUI Casks that build .apps in favour of formulae. Inkscape is a great example, actually, because the formula was a nightmare to keep building successfully and it had generally a long, painful build process and also that I'm not convinced older versions so old as to be "useless" (despite what others may claim).

But the brew/brew cask division is confusing for users and separating by CLI/GUI makes sense, so maybe app-building-formulae should be restricted to third party taps.

I'd be in favour of this if we're also going to nudge towards Casks. Something we've talked about in the past that may be worth resurrecting is somehow having a formulae tap that's designed to build and upload files that can be then used as casks.

To push the point further, maybe CLI-only casks (closed-source) should be removed as well.

Are there many CLI-only closed-source casks? I'd be interested in thinking more about this. It'd be worth using analytics data to inform this and other decisions (https://formulae.brew.sh/analytics/cask-install/30d/)

But the cask can also install the CLI. I’m open to removing that line, but I guess some users would be unhappy to have to brew install mpv && brew cask install mpv to get both the CLI and the GUI versions.

Yes, I agree. I think it's fine for the Cask to install a CLI link if it's already included with the software.

But otherwise, if you do think app bundles should be removed from formulae, the rule would be “if want the CLI, brew, if you want the GUI, brew cask but it would also bring the CLI that typically comes in the package”.

Yes, this seems reasonable.

Some casks tried to make that clearer (mkvtoolnix) by adding an -app suffix, but that’s confusing even to maintainers. That suffix was added in the spirit of deduplication, but now we should probably get rid of that rule and rename those casks.

Yes, agreed.

It's also worth noting that I don't think these requirements changing here state would should be done immediately to all existing formulae/casks but should be enforced pretty strongly for new formulae and casks.

Something that always rings in my ears is what @mxcl said about Homebrew's primary purpose being "to be useful". In my Homebrew I've slightly extended that to be "to be useful at a quality that minimises support issues and improves the macOS ecosystem". I think that's what I'd like to keep in mind when we're thinking about this stuff.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there many CLI-only closed-source casks? I'd be interested in thinking more about this. It'd be worth using analytics data to inform this and other decisions

Homebrew/homebrew-cask#62715


### Naming

The name is the strictest item, because avoiding a later name change is
desirable.

Expand All @@ -55,6 +56,7 @@ 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 & GPG commit signing,
and squash/merge via GitHub should be used for formulae where those formulae
don't need bottles or the change does not require new bottles to be pulled.
Expand All @@ -71,6 +73,7 @@ the commits. Our main branch history should be useful to other people,
not confusing.

### 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
Expand All @@ -94,23 +97,24 @@ 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 ([GitX-dev](https://github.com/rowanj/gitx)
can do this, otherwise there is a command-line flag for it)
3. If the commit fixes a bug, use “Fixes \#104” syntax to close the bug
report and link to the commit

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
if you came to them unaware of the surrounding issues they would make sense
to you. Many times on other projects I’ve seen code removed because the
new guy didn’t know why it was there. Regressions suck.

### 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.
Expand All @@ -121,9 +125,11 @@ 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
Any 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.

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
Expand All @@ -134,14 +140,17 @@ 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.

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

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 `do not merge` label 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.

## Communication

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

- Homebrew's public repositories on GitHub
Expand All @@ -157,6 +166,7 @@ All maintainers (and lead maintainer) communication through any medium is bound
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](https://en.wikipedia.org/wiki/Law_of_triviality) and personal attacks are forbidden.

## Project lead guidelines

There should be one project lead for Homebrew. On February 4, 2019, coinciding with the Homebrew maintainers' conference, Mike McQuaid stepped down as lead maintainer of Homebrew. He was elected by a supermajority of Homebrew maintainers into the new project lead role.

Additional documentation for the project lead and governance are to follow.
37 changes: 19 additions & 18 deletions docs/New-Maintainer-Checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,24 @@

**This is a guide used by existing maintainers to invite new maintainers. You might find it interesting but there's nothing here users should have to know.**

There's someone who has been making consistently high-quality contributions to Homebrew for a long time and shown themselves able to make slightly more advanced contributions than just e.g. formula updates? Let's invite them to be a maintainer!
There's someone who has been making consistently high-quality contributions to Homebrew and shown themselves able to make slightly more advanced contributions than just e.g. formula updates? Let's invite them to be a maintainer!

First, send them the invitation email:

```
```markdown
The Homebrew team and I really appreciate your help on issues, pull requests and
your contributions to Homebrew.

We would like to invite you to have commit access and be a Homebrew maintainer.
If you agree to be a maintainer, you should spend a significant proportion of
the time you are working on Homebrew fixing user-reported issues, resolving any
issues that arise from your code in a timely fashion and reviewing user
contributions. You should also be making contributions to Homebrew every month
unless you are ill or on vacation (and please let another maintainer know if
that's the case so we're aware you won't be able to help while you are out).
the time you are working on Homebrew applying and self-merging widely used
changes (e.g. version updates), triaging, fixing and debugging user-reported
issues, or reviewing user pull requests. You should also be making contributions
to Homebrew at least once per quarter.

You will need to watch Homebrew/brew and/or Homebrew/homebrew-core. Let us know
which (or both) so we can grant you commit access appropriately.
You should watch or regularly check Homebrew/brew and/or
Homebrew/homebrew-core. Let us know which (or both) so we can grant you commit
access appropriately.

If you're no longer able to perform all of these tasks, please continue to
contribute to Homebrew, but we will ask you to step down as a maintainer.
Expand All @@ -34,8 +34,8 @@ A few requests:
multiple formulae and let it auto-close issues wherever possible (it may
take ~5m). When this isn't necessary use GitHub's "Merge pull request"
button in "create a merge commit" mode for Homebrew/brew or "squash and
merge" for a single formulae change. If in doubt, check with e.g. GitX that
you've not accidentally added merge commits.
merge" for a single formulae change. If in doubt, check with e.g. Fork.app
that you've not accidentally added merge commits.
- 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
Expand Down Expand Up @@ -63,18 +63,19 @@ If they accept, follow a few steps to get them set up:
- Ask them to (regularly) review remove any unneeded [GitHub personal access tokens](https://github.com/settings/tokens).
- Add them to [Homebrew/brew's README](https://github.com/Homebrew/brew/edit/master/README.md).

If they are also interested in doing system administration work:
If they are interested in doing system administration work or Homebrew/brew releases:

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

If they want to consume raw anonymous aggregate analytics data (rather than use `brew formula-analytics`):

- Invite them to [Google Analytics](https://analytics.google.com/analytics/web/?authuser=1#management/Settings/a76679469w115400090p120682403/%3Fm.page%3DAccountUsers/).
If they are elected to the Homebrew's [Software Freedom Conservancy](https://sfconservancy.org) Project Leadership Committee:

Once they have been active maintainers for at least a year and had some activity on more than one Homebrew organisation repository (or one repository and helped with system administration work):

- Homebrew's [Software Freedom Conservancy](https://sfconservancy.org) Project Leadership Committee can take a vote on whether to extend an offer to the maintainer to join the committee. If they accept, email their name, email and employer to homebrew@sfconservancy.org, make them [owners on the Homebrew GitHub organisation](https://github.com/orgs/Homebrew/people) and add them to the relevant section of the [Homebrew/brew's README](https://github.com/Homebrew/brew/edit/master/README.md).
- Email their name, email and employer to homebrew@sfconservancy.org
- Make them [owners on the Homebrew GitHub organisation](https://github.com/orgs/Homebrew/people)
- Invite them to the [**@Homebrew/plc** team](https://github.com/orgs/Homebrew/teams/plc/members)
- Invite them to [Google Analytics](https://analytics.google.com/analytics/web/#management/Settings/a76679469w115400090p120682403/%3Fm.page%3DAccountUsers/) and add them to the relevant section of the [Homebrew/brew's README](https://github.com/Homebrew/brew/edit/master/README.md).
- Invite them to the [`homebrew` private 1Password](https://homebrew.1password.com/people).
- Make them owners on the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin)).

If there are problems, ask them to step down as a maintainer and revoke their access to all of the above.

Expand Down
4 changes: 4 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Documentation

## Users

- [`brew` man-page (command documentation)](Manpage.md)
- [Troubleshooting](Troubleshooting.md)
- [Installation](Installation.md)
Expand All @@ -27,6 +28,7 @@
- [Kickstarter Supporters](Kickstarter-Supporters.md)

## Contributors

- [How To Open A Pull Request (and get it merged)](How-To-Open-a-Homebrew-Pull-Request.md)
- [Formula Cookbook](Formula-Cookbook.md)
- [Acceptable Formulae](Acceptable-Formulae.md)
Expand All @@ -41,8 +43,10 @@
- [Prose Style Guidelines](Prose-Style-Guidelines.md)

## Maintainers

- [New Maintainer Checklist](New-Maintainer-Checklist.md)
- [Maintainers: Avoiding Burnout](Maintainers-Avoiding-Burnout.md)
- [Maintainer Guidelines](Maintainer-Guidelines.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)
39 changes: 39 additions & 0 deletions docs/Releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Releases

Since Homebrew 1.0.0 most Homebrew users (those who haven't run a `dev-cmd` or
set `HOMEBREW_DEVELOPER=1`) require tags on the [Homebrew/brew repository](https://github.com/homebrew/brew)
in order to get new versions of Homebrew. There are a few steps in making a new
Homebrew release:

1. Check the [Homebrew/brew pull requests](https://github.com/homebrew/brew/pulls)
and [issues](https://github.com/homebrew/brew/issues) to see if there is
anything pressing that needs to be fixed or merged before the next release.
If so, fix and merge these changes.
2. After no code changes have happened for at least a few hours (ideally 24 hours)
and you are confident there's no major regressions on the current `master`
branch you can create a new Git tag. Ideally this should be signed with your
GPG key. This can then be pushed to GitHub.
3. Use `brew release-notes --markdown $PREVIOUS_TAG` to generate the release
notes for the release. [Create a new release on GitHub](https://github.com/Homebrew/brew/releases/new)
based on the new tag.

If this is a major or minor release (e.g. X.0.0 or X.Y.0) then there are a few more steps:

1. Before creating the tag you should delete any `odisabled` code, make any
`odeprecated` code `odisabled` and add any new `odeprecations` that are
desired.
2. Write up a release notes blog post to https://brew.sh
e.g. https://github.com/Homebrew/brew.sh/pull/319.
This should use `brew release-notes` as input but have the wording adjusted
to be more human readable and explain not just what has changed but why.
3. When the release has shipped and the blog post has been merged, tweet the
blog post as the @MacHomebrew Twitter account or tweet it yourself and
retweet it with the @MacHomebrew Twitter account (credentials are in
1Password).
4. Send the email to the Homebrew TinyLetter email list (credentials are in
1Password).
5. Consider whether to submit it to other sources e.g. Hacker News, Reddit.

- Pros: gets a wider reach and user feedback
- Cons: negative comments are common and people take this as a chance to
complain about Homebrew (regardless of their usage)