Skip to content

ci: add the guide style rules to the Vale check (non-blocking) - #375

Draft
mknell-godaddy wants to merge 5 commits into
mainfrom
ci/vale-cli-rules
Draft

mknell-godaddy wants to merge 5 commits into
mainfrom
ci/vale-cli-rules

Conversation

@mknell-godaddy

@mknell-godaddy mknell-godaddy commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

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

  • 15 local rules in .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".
  • One package rule, Microsoft.Contractions. It's the only package rule that runs, and it's enabled by name in .vale.ini.
  • Paragraphs that start with "AI assistants:" are skipped. They speak to an AI assistant, tests pin their exact wording, and the same text sits in Rust constants.
  • The job runs vale sync to download the package. The downloaded files are ignored by git.
  • CONTRIBUTING.md shows vale sync before the local command.
  • Errors: contractions, Latin abbreviations, "i.e.", banned vocabulary and accepted spellings. Everything else is a warning. The job still doesn't fail on findings.

What was tried

  • The whole Microsoft package with the rules that don't fit switched off: rejected for now. It needs a review of about 150 rules for terminal text. A later change can switch to that.
  • Vale's built-in style: left off. It adds spelling errors for product and CLI terms and needs a vocabulary file.
  • A rule for the PAT placeholder: left out. The CLI documents GDDY_PAT, so the version used elsewhere would point authors at the wrong variable.
  • Slashes: a slash is fine for a rate or ratio such as 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).

  • Errors: contractions 52, Latin abbreviations 18, banned vocabulary 5.
  • Warnings: em dash 143, sentence length 34, discouraged vocabulary 26, slash 20, passive voice 10, gerund headings 8, numbered headings 5, "once" 3, "may" 1, "and/or" 1.

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

  • Fixes to the guide text. That is the next change.
  • Blocking mode, and the job staying out of required checks until then.
  • Linting --help output.
  • Switching the package rules to the blocklist approach.

mknell-godaddy and others added 4 commits November 13, 2026 11:38
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.
@mknell-godaddy
mknell-godaddy changed the base branch from ci/vale-guides-lint to main November 16, 2026 19:52
…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.

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.

🟡 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.Contractions and 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/.:-])'
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.

2 participants