Repository navigation
ci: add the guide style rules to the Vale check (non-blocking) - #375
Draft
mknell-godaddy wants to merge 5 commits into
Draft
mknell-godaddy wants to merge 5 commits into
mknell-godaddy wants to merge 5 commits into
Conversation
Why: guide text has no docs checks, so problems are found only after the text ships in the binary. This adds the wiring first, with one trivial rule, so the real rule set can be reviewed on its own later. What was tried: - A step at the end of the existing Rust job: rejected, because it never runs when an earlier cargo step fails. - A hand-written install script with a pinned, checksum-verified download: worked, but it is custom install code to maintain. The official action removes it, so it was dropped. - Starter rules (sentence length, em dash): rejected. The guides contain 124 em dashes, and a length rule collides with the soft-line-break guidance in docs/command-authoring.md. Both are rule decisions for later. - Vale's built-in style and style packages: rejected. A local one-rule style keeps the active rule set independent of what a Vale version ships, and packages add a network fetch and unreviewed rules for terminal text. - Running the job on pushes to main too: rejected. The action reports through pull request annotations, so a push has nothing to annotate. Decision: a separate guides-lint job runs vale-cli/vale-action, pinned to a commit SHA, with Vale 3.24.0 and fail_on_error: false, on pull requests only. It needs read access only and no secrets. One local rule, GddyCli.Repetition, is error level because Vale exits 1 only for error-level findings, which a later change needs to switch to blocking. Vale exits 0 when a path matches no files, so a wrong path could lint nothing silently. Check the job log for the file list when the paths change. Invalid frontmatter in a guide fails the job, because Vale cannot parse it.
Fix lint guide command syntax and update instructions. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Why: the Vale job added in the previous change runs one rule (repeated words) so the wiring could be reviewed alone. This adds the rules the guides are meant to follow, so findings show on pull requests before any of them can block a merge. What changed: 15 local rules in .vale/styles/GddyCli, plus the package rule Microsoft.Contractions. The local rules cover em dashes, Latin abbreviations, "after" instead of "once", "might" and "may", banned and discouraged words, passive voice, sentence length (30 words), gerund headings, recap headings, "and/or", slashes that stand for "and" or "or", and numbered headings. All are warnings except the rules for Latin abbreviations and "i.e.", banned vocabulary, accepted spellings and contractions, which are errors. The job still does not fail on findings. The action now downloads the package with `vale sync`, and the downloaded files are ignored by git. What was tried: enabling the whole Microsoft package and switching off the rules that don't fit. That needs a review of about 150 rules for terminal text, so only the one rule the guidelines name is enabled, by name. The built-in Vale style stays off, because it adds spelling errors for product and CLI terms and needs a vocabulary file. A rule for the PAT placeholder is left out: the CLI documents GDDY_PAT, so the version the docs site uses would point authors at the wrong variable. Baseline on the 12 guides: 332 findings. Warnings: em dash 144, sentence length 35, discouraged vocabulary 26, slash 20, passive voice 10, gerund headings 8, numbered headings 5, "once" 3, "may" 1, "and/or" 1. Errors: contractions 55, Latin abbreviations 18, banned vocabulary 6. Fixing the guide text is a separate change, and blocking comes after that.
…ength message Why: guide paragraphs that start with "AI assistants:" talk to an AI assistant, not to the reader. Six findings fall in them (contractions, an em dash, "such as", sentence length). Rust tests pin the exact wording of those notes, and the same text sits in Rust constants that agents read, so rewording them to satisfy the prose rules would change tests and agent-facing text for no gain. What was tried: light prose edits, for example "Do not" to "Don't". They would touch tests in several files (domain, shopping, hosting) and the wording the notes rely on. Rejected for now. Decision: BlockIgnores skips any line that starts with "AI assistants:". All four guide notes are single-line paragraphs of that shape. The sentence-length message printed "%!s(int=34)" because it used %s for a number. It uses %d now.
This was referenced Nov 16, 2026
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The slash-alternative pattern misses punctuation-terminated alternatives and multi-slash chains, so it needs broader matching while preserving filename-extension exclusions.
1 open issue
What changed in this PR
This PR expands the non-blocking Vale check for embedded CLI guides with local writing rules and Microsoft’s contractions rule. It builds on #371 without changing guide text or making findings block merges.
Changes:
- Adds 15 local rules covering wording, punctuation, headings, and sentence length.
- Enables
Microsoft.Contractionsand excludes AI-assistant notes from prose checks. - Documents package synchronization and ignores downloaded styles.
| File | Description |
|---|---|
| CONTRIBUTING.md | Documents local Vale setup and lint command. |
| .vale/styles/GddyCli/Repetition.yml | Retains the repeated-word rule from #371. |
| .vale/styles/GddyCli/NoSlashOption.yml | Warns about slash-separated alternatives. |
| .vale/styles/GddyCli/NoRecapHeadings.yml | Flags recap and summary headings. |
| .vale/styles/GddyCli/NoPassiveVoice.yml | Warns about common passive phrases. |
| .vale/styles/GddyCli/NoNumberedHeadings.yml | Flags numbered headings. |
| .vale/styles/GddyCli/NoIe.yml | Rejects “i.e.” in prose. |
| .vale/styles/GddyCli/NoEmDash.yml | Warns about em dashes. |
| .vale/styles/GddyCli/NoAndOr.yml | Flags “and/or.” |
| .vale/styles/GddyCli/MayVsMight.yml | Flags selected possibility uses of “may.” |
| .vale/styles/GddyCli/MaxSentenceLength.yml | Warns about sentences exceeding 30 words. |
| .vale/styles/GddyCli/LatinAbbreviations.yml | Suggests alternatives to Latin expressions. |
| .vale/styles/GddyCli/ImperativeHeadings.yml | Flags selected gerund-led headings. |
| .vale/styles/GddyCli/DiscouragedVocabulary.yml | Warns about discouraged vocabulary. |
| .vale/styles/GddyCli/BannedVocabulary.yml | Rejects specified words and phrases. |
| .vale/styles/GddyCli/AfterNotOnce.yml | Suggests “After” for selected sentence openings. |
| .vale/styles/GddyCli/AcceptedAbbreviations.yml | Supplies preferred spellings and wording. |
| .vale.ini | Enables guide rules and skips AI-assistant notes. |
| .gitignore | Excludes downloaded Vale styles. |
| .github/workflows/cicd.yml | Includes the non-blocking PR lint job and documents package synchronization. |
Review effort: Balanced
| scope: text | ||
| nonword: true | ||
| tokens: | ||
| - '(?<![\w/.:-])[A-Za-z][A-Za-z-]*/[A-Za-z][A-Za-z-]*(?![\w/.:-])' |
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.

Why
The Vale job from #371 runs one rule, so the wiring could be reviewed alone. This adds the rules the guides are meant to follow. Findings show on pull requests, and nothing can block a merge yet.
This PR is stacked on #371, so its diff includes the commits from #371 until that PR merges. Review the last commit only.
What changed
.vale/styles/GddyCli: em dash, Latin abbreviations and "i.e.", "after" instead of "once", "might" and "may", banned and discouraged words, accepted spellings, passive voice, sentence length (30 words), gerund headings, recap headings, numbered headings, "and/or", and slashes that stand for "and" or "or".Microsoft.Contractions. It's the only package rule that runs, and it's enabled by name in.vale.ini.vale syncto download the package. The downloaded files are ignored by git.CONTRIBUTING.mdshowsvale syncbefore the local command.What was tried
GDDY_PAT, so the version used elsewhere would point authors at the wrong variable.req/min, and nothing else is excepted. "true/false" becomes "true or false", and "CI/CD" becomes "CICD" in the guide text.Checked
Local run, Vale 3.24.0, on the 12 guides: 326 findings, after skipping the AI notes (6 findings fell in them).
Three of the em dashes are in
summary:lines, because Vale lints frontmatter here. Vale doesn't lint the paragraph right after an indented code fence inside a list item, so one slash hit is missed.Not in this PR
--helpoutput.