- Most of these were fine still, apart from:
- FAQ: `hub` is less maintained than `gh`.
- Brew-Maintainer-Guide: link to GitHub docs on commit signing via GPG or SSH.
- Interesting-Taps-and-Forks: remove outdated information about `homebrew/core` being in `Library/Taps`.
- New-Maintainer-Checklist: remove outdated information about the `@members` team.
- At the AGM we formed an ad-hoc documentation working group.
- One of our ideas was that we should have a last reviewed date for
documentation, so that we can periodically implement a review
mechanism (GitHub Actions posts to Slack for a regular documentation
outdatedness check?) to track how old docs are and ensure they're
still relevant.
- This is a first step towards that goal, by adding a `last_review_date`
to the metadata of all docs with a date of earlier than Homebrew's
inception because everything needs reviewing so that we start from a
good base!
- Move the guidelines from Homebrew/brew Maintainer Guide to
Maintainer Guidelines as they apply to all repositories.
- Clarify the guidelines to make it clear that the default option
should be to approve a PR, with or without comments.
- Note in the New Maintainer Checklist that the most important task for
maintainers is reviewing pull requests.
Co-authored-by: Issy Long <me@issyl0.co.uk>
Co-authored-by: Sam Ford <1584702+samford@users.noreply.github.com>
Co-authored-by: Eric Knibbe <enk3@outlook.com>
This was discussed at the AGM. It's no longer needed to avoid
"cluttering up clones" because most users use the API for our
main repositories now.
It should also simplify security work in future because we can assume
anyone who can create a branch on the main repository has write access
rather than e.g. having a hardcoded list of maintainers we rely on.
My intent was to disambiguate what ownership means and be specific but we decided it was better to just keep the title the same since that's what it's called in all of the systems.
We've had problems in the past with Homebrew maintainers being unwilling to disclose their identity or meet other maintainers so here are some very light-touch suggestions to address this in future.
These ideas were run past the PLC and agreed there but I still welcome input from maintainers.
- I raised a PR for adding myself to the README. CI failed because the
README had changed without the man pages changing too. Then I had to
amend my "hello!" commit which was slightly embarrassing.
- Document that there are multiple places, and suggest `brew man` to
generate man pages, so that the next people have it easier.
- 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
We've made these recommendations to current maintainers to update the
documentation so we don't forget to ask new maintainers to do the same
when we invite more in future.
- Remove no longer needed `acme-challenge` file
- Set title, description, social image, logo, etc. for SEO
- Use extensionless permalinks (old links still work)
- Cleanup `_config.yml`
- Import latest `_layouts/base` from https://brew.sh
GitHub now nicely generates a documentation site for us at
http://brew.sh/brew based on our docs folder. Optimise the output of
this and the GitHub docs directory for readability and the various user
groupings.
