Skip to content

docs: fix errors reported by Vale 3.17.0 - #23387

Merged
dduugg merged 1 commit into
mainfrom
docs-vale-3-17-errors
Jul 31, 2026
Merged

docs: fix errors reported by Vale 3.17.0#23387
dduugg merged 1 commit into
mainfrom
docs-vale-3-17-errors

Conversation

@dduugg

@dduugg dduugg commented Jul 31, 2026

Copy link
Copy Markdown
Member

What does this change do, and why?

The Documentation workflow installs Vale unpinned (brew install vale), and Vale 3.17.0 (published 2026-07-31T17:07Z) reports two docs/ errors that 3.16.0 did not. main last ran the job at 16:53Z on 2b7c468 and passed; every pull request built after 17:07Z fails the docs job 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:128 has an Oxford comma, which Homebrew.OxfordComma disallows.
  • docs/index.md:48 links to How-To-Open-a-Homebrew-Pull-Request.md as "How to Open a Pull Request". Homebrew.Terms exempts 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.md was the lone outlier, so adding the missing "Homebrew" fixes the error and makes the link text consistent.

Step-by-step reproduction

$ brew install vale   # 3.17.0
$ vale docs/
 docs/Maintainer-Stipends-and-Grants.md
 128:3  error  No Oxford commas!  Homebrew.OxfordComma

 docs/index.md
 48:18  error  Use 'pull request' instead of 'Pull Request'.  Homebrew.Terms

✖ 2 errors, 0 warnings and 0 suggestions in 88 files.

With this change, vale docs/ reports 0 errors, 0 warnings and 0 suggestions in 88 files.


  • Have you followed our Contributing guidelines?
  • Have you checked for other open Pull Requests for the same change?
  • Have you explained what your changes do? Performance claims (e.g. "this is faster") must include Hyperfine benchmarks.
  • Have you explained why you'd like these changes included, not just what they do?
  • For bug fixes, have you given step-by-step brew commands to reproduce the bug?
  • Have you written new tests (excluding integration tests)? Here's an example.
  • Have you successfully run 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 lgtm to check and no behaviour to test. Verified with vale docs/ on 3.17.0 instead, before and after.


  • I did not use AI/LLM to create this PR, or I disclosed the tool/model below and reviewed its output; I did not attribute commits to AI and will answer maintainer questions and review comments myself without AI/LLM.

AI was used. Claude Code (Claude Sonnet) traced the docs job failure on #23386 to the Vale 3.17.0 release, confirmed the two flagged lines are unchanged on main and 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 ran vale docs/ on main to reproduce the two errors, then again with the fix to confirm 0 errors across the same 88 files.

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.
Copilot AI review requested due to automatic review settings July 31, 2026 21:52

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 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.md to satisfy Homebrew.OxfordComma.
  • Updates the docs/index.md link text to match the standard phrasing “How to Open a Homebrew Pull Request …”, satisfying Homebrew.Terms and 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.

@dduugg
dduugg enabled auto-merge July 31, 2026 22:09
@dduugg
dduugg added this pull request to the merge queue Jul 31, 2026
Merged via the queue into main with commit aa32874 Jul 31, 2026
46 checks passed
@dduugg
dduugg deleted the docs-vale-3-17-errors branch July 31, 2026 22:34

@MikeMcQuaid MikeMcQuaid left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants