docs: fix errors reported by Vale 3.17.0 - #23387
Merged
Merged
Conversation
The Documentation workflow installs Vale unpinned, and 3.17.0 reports two errors that 3.16.0 did not, so every pull request built after its release fails the docs job on unchanged content. Both are real violations of our own styles rather than new false positives. Drop an Oxford comma in the conference reimbursement list, and link to How-To-Open-a-Homebrew-Pull-Request.md by the name Homebrew.Terms exempts, which is also how every other page refers to it.
Contributor
There was a problem hiding this comment.
🟢 Ready to approve
The changes are minimal, documentation-only, and directly address the reported Vale style violations without introducing new content or behavioral risk.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
Updates Homebrew’s documentation prose to comply with the repository’s Vale-enforced style rules after Vale 3.17.0 began flagging previously-unreported violations in docs/.
Changes:
- Removes an Oxford comma in
docs/Maintainer-Stipends-and-Grants.mdto satisfyHomebrew.OxfordComma. - Updates the
docs/index.mdlink text to match the standard phrasing “How to Open a Homebrew Pull Request …”, satisfyingHomebrew.Termsand aligning with other docs pages.
File summaries
| File | Description |
|---|---|
| docs/Maintainer-Stipends-and-Grants.md | Removes an Oxford comma in a conference travel reimbursement bullet list item. |
| docs/index.md | Adjusts link text to the canonical “How to Open a Homebrew Pull Request …” phrasing used elsewhere. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 0
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
krehel
approved these changes
Jul 31, 2026
dduugg
enabled auto-merge
July 31, 2026 22:09
chenrui333
approved these changes
Jul 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this change do, and why?
The
Documentationworkflow installs Vale unpinned (brew install vale), and Vale 3.17.0 (published 2026-07-31T17:07Z) reports twodocs/errors that 3.16.0 did not.mainlast ran the job at 16:53Z on 2b7c468 and passed; every pull request built after 17:07Z fails thedocsjob on unchanged content, e.g. https://github.com/Homebrew/brew/actions/runs/30666983756/job/91276194089.Both are genuine violations of our own styles rather than new false positives, so this fixes the prose instead of pinning the version:
docs/Maintainer-Stipends-and-Grants.md:128has an Oxford comma, whichHomebrew.OxfordCommadisallows.docs/index.md:48links toHow-To-Open-a-Homebrew-Pull-Request.mdas "How to Open a Pull Request".Homebrew.Termsexempts only the exact phrase "How to Open a Homebrew Pull Request", and that is how every other page links to it (Adding-Software-to-Homebrew.md,Formula-Cookbook.md,Updating-Software-in-Homebrew.md).index.mdwas the lone outlier, so adding the missing "Homebrew" fixes the error and makes the link text consistent.Step-by-step reproduction
With this change,
vale docs/reports0 errors, 0 warnings and 0 suggestions in 88 files.brewcommands to reproduce the bug?brew lgtm(style, typechecking and tests) locally?Documentation prose only, so there is nothing for the last two boxes to cover: no Ruby changes for
brew lgtmto check and no behaviour to test. Verified withvale docs/on 3.17.0 instead, before and after.AI was used. Claude Code (Claude Sonnet) traced the
docsjob failure on #23386 to the Vale 3.17.0 release, confirmed the two flagged lines are unchanged onmainand are real style violations rather than regressions, checked that no open pull request already fixes them, and wrote this change. Verification: installed Vale 3.17.0 locally and ranvale docs/onmainto reproduce the two errors, then again with the fix to confirm 0 errors across the same 88 files.