Update maintainer documentation.

- Fix Markdown format
- Note Linux in the mission statement
- Update the maintainer guidelines based on current state
- Loosen the new maintainer expectations
- Clarify what things the PLC should be added to
- Add documentation for making a new Homebrew release

docs/Maintainer-Guidelines.md

@@ -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
 
@@ -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.
 
 ### Naming
+
 The name is the strictest item, because avoiding a later name change is
 desirable.
 
@@ -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.
@@ -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
@@ -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.
@@ -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
@@ -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
@@ -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.

docs/New-Maintainer-Checklist.md

@@ -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 will 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.
@@ -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
@@ -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`):
+If they are elected to of the Homebrew's [Software Freedom Conservancy](https://sfconservancy.org) Project Leadership Committee:
 
-- Invite them to [Google Analytics](https://analytics.google.com/analytics/web/?authuser=1#management/Settings/a76679469w115400090p120682403/%3Fm.page%3DAccountUsers/).
-
-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.
 

docs/README.md

@@ -1,6 +1,7 @@
 # Documentation
 
 ## Users
+
 - [`brew` man-page (command documentation)](Manpage.md)
 - [Troubleshooting](Troubleshooting.md)
 - [Installation](Installation.md)
@@ -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)
@@ -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)

docs/Releases.md

@@ -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)
+   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)