- 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!
- Add the same macOS `--build-from-source` default prefix behaviour
now we have ~4000 linuxbrew-core bottles.
- Merge remaining useful linuxbrew-core-Maintainer-Guide into
Homebrew-homebrew-core-Maintainer-Guide
- Don't special-case linuxbrew-core any more in docs
- I added these all the way back in December 2019 in #6826, but only
today realised that things have been failing unnoticeably because
"warning" level exits with status code 0, so doesn't fail CI.
- Upgrading to "error" level will enable us to see the style errors in
our docs and fix them faster.
- My editor also auto-formatted the YAML to have double quotes instead
of single.
Anywhere we can use `blob/master` we can use `blob/HEAD` instead. This
will make life easier if we ever rename our default branch in future
(once/if Git and GitHub provides the necessary tooling to do so).
- I wrote about the implications of (not) doing this in the PR
(https://github.com/Homebrew/brew/pull/6826#issuecomment-564273209),
but in summary:
- It looks like pretty much the only place we've ever adhered to the
sentence case rule is the Prose Guidelines itself.
- Correcting all these to sentence case would be a lot of work (and
sometimes not even make sense).
- Admittedly, some of the title case ones look a bit horrible, but
even with some allowed exceptions, but it's better than being
consistently inconsistent.
- Only lint for title case in h1 headings. H2s and H3s etc. can be
sentence case. There's not currently a lint for that.
- I noticed that another open source project had taken the Homebrew
style guide and made it into [Vale linting
rules](https://github.com/testthedocs/vale-styles/tree/master/Homebrew).
This copies them into here, so that we can make use of them. Thanks!
- What use is a style guide if our own docs don't at least try to
adhere to it? This aims to make the rules more visible to all
contributors.
- In order for these to do anything, you'll have to `brew install vale`
and run `vale` in the root of this repo. It will look for Markdown
files.
- A next step would be adding this as a pre-commit hook, or...
- The GitHub Action would have been really good, but [it doesn't support
forks](https://github.com/errata-ai/vale-action#limitations).
