From d158ec94be0c65b4d67e88ca4cb9a71687906059 Mon Sep 17 00:00:00 2001 From: mknell-godaddy Date: Thu, 12 Nov 2026 11:45:20 -0500 Subject: [PATCH 1/4] ci: lint CLI guides with Vale (non-blocking) 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. --- .github/workflows/cicd.yml | 26 ++++++++++++++++++++++++++ .vale.ini | 8 ++++++++ .vale/styles/GddyCli/Repetition.yml | 6 ++++++ CONTRIBUTING.md | 3 +++ 4 files changed, 43 insertions(+) create mode 100644 .vale.ini create mode 100644 .vale/styles/GddyCli/Repetition.yml diff --git a/.github/workflows/cicd.yml b/.github/workflows/cicd.yml index cb0f9bf8..3965a47e 100644 --- a/.github/workflows/cicd.yml +++ b/.github/workflows/cicd.yml @@ -70,3 +70,29 @@ jobs: echo "ERROR: unresolved external \$ref(s) in committed API catalog schemas (shown above)" exit 1 fi + + guides-lint: + # Lints the embedded guide text with Vale. Findings are reported but don't fail + # the job yet (fail_on_error: false); a later change sets it to true. Don't make + # this job a required check before then. The action reports through pull request + # annotations, so it runs only on pull requests. + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + steps: + - name: Checkout code + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false + + - name: Lint guide text + uses: vale-cli/vale-action@518a9136acc6e6668ce7c00d367051e0941e87ff # v3.0.0 + with: + version: 3.24.0 + reviewdog_version: 0.21.0 + fail_on_error: false + sync: false + files: rust/src + glob: "**/guides/*.md" diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000..3433d0e7 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,8 @@ +# Vale configuration for the embedded guide text (`gddy guide `). +# One local rule (repeated words) is on, to prove the wiring. The real rule set +# arrives in follow-up changes. +StylesPath = .vale/styles +MinAlertLevel = suggestion + +[rust/src/*/guides/*.md] +BasedOnStyles = GddyCli diff --git a/.vale/styles/GddyCli/Repetition.yml b/.vale/styles/GddyCli/Repetition.yml new file mode 100644 index 00000000..b62801f2 --- /dev/null +++ b/.vale/styles/GddyCli/Repetition.yml @@ -0,0 +1,6 @@ +extends: repetition +message: "'%s' is repeated." +level: error +alpha: true +tokens: + - '[^\s]+' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71aa9704..dc140585 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,6 +81,9 @@ cargo fmt # Type-check only (fast) cargo check +# Lint guide text (needs Vale 3.24.0; see https://github.com/errata-ai/vale/releases) +cd .. && vale rust/src/*/guides/*.md && cd rust + # Regenerate the embedded API catalog (needs access to GoDaddy's internal spec repos) cargo run -p generate-api-catalog ``` From 0889e655efd59ad22121828e1ae340109c7415dc Mon Sep 17 00:00:00 2001 From: Mitchell Knell <104020373+mknell-godaddy@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:16:16 -0500 Subject: [PATCH 2/4] Correct lint guide command in CONTRIBUTING.md Fix lint guide command syntax and update instructions. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dc140585..544632f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,7 +82,7 @@ cargo fmt cargo check # Lint guide text (needs Vale 3.24.0; see https://github.com/errata-ai/vale/releases) -cd .. && vale rust/src/*/guides/*.md && cd rust +(cd .. && vale rust/src/*/guides/*.md) # Regenerate the embedded API catalog (needs access to GoDaddy's internal spec repos) cargo run -p generate-api-catalog From 235e7396b950c20e4d6f81e8a70a4b0854a0e773 Mon Sep 17 00:00:00 2001 From: mknell-godaddy Date: Mon, 16 Nov 2026 14:48:03 -0500 Subject: [PATCH 3/4] ci: add the guide style rules to the Vale check (non-blocking) 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. --- .github/workflows/cicd.yml | 4 +- .gitignore | 4 ++ .vale.ini | 7 ++- .../styles/GddyCli/AcceptedAbbreviations.yml | 31 ++++++++++++ .vale/styles/GddyCli/AfterNotOnce.yml | 9 ++++ .vale/styles/GddyCli/BannedVocabulary.yml | 49 +++++++++++++++++++ .../styles/GddyCli/DiscouragedVocabulary.yml | 13 +++++ .vale/styles/GddyCli/ImperativeHeadings.yml | 9 ++++ .vale/styles/GddyCli/LatinAbbreviations.yml | 18 +++++++ .vale/styles/GddyCli/MaxSentenceLength.yml | 6 +++ .vale/styles/GddyCli/MayVsMight.yml | 7 +++ .vale/styles/GddyCli/NoAndOr.yml | 8 +++ .vale/styles/GddyCli/NoEmDash.yml | 9 ++++ .vale/styles/GddyCli/NoIe.yml | 9 ++++ .vale/styles/GddyCli/NoNumberedHeadings.yml | 8 +++ .vale/styles/GddyCli/NoPassiveVoice.yml | 43 ++++++++++++++++ .vale/styles/GddyCli/NoRecapHeadings.yml | 7 +++ .vale/styles/GddyCli/NoSlashOption.yml | 14 ++++++ CONTRIBUTING.md | 2 +- 19 files changed, 252 insertions(+), 5 deletions(-) create mode 100644 .vale/styles/GddyCli/AcceptedAbbreviations.yml create mode 100644 .vale/styles/GddyCli/AfterNotOnce.yml create mode 100644 .vale/styles/GddyCli/BannedVocabulary.yml create mode 100644 .vale/styles/GddyCli/DiscouragedVocabulary.yml create mode 100644 .vale/styles/GddyCli/ImperativeHeadings.yml create mode 100644 .vale/styles/GddyCli/LatinAbbreviations.yml create mode 100644 .vale/styles/GddyCli/MaxSentenceLength.yml create mode 100644 .vale/styles/GddyCli/MayVsMight.yml create mode 100644 .vale/styles/GddyCli/NoAndOr.yml create mode 100644 .vale/styles/GddyCli/NoEmDash.yml create mode 100644 .vale/styles/GddyCli/NoIe.yml create mode 100644 .vale/styles/GddyCli/NoNumberedHeadings.yml create mode 100644 .vale/styles/GddyCli/NoPassiveVoice.yml create mode 100644 .vale/styles/GddyCli/NoRecapHeadings.yml create mode 100644 .vale/styles/GddyCli/NoSlashOption.yml diff --git a/.github/workflows/cicd.yml b/.github/workflows/cicd.yml index 3965a47e..adedaca8 100644 --- a/.github/workflows/cicd.yml +++ b/.github/workflows/cicd.yml @@ -72,7 +72,8 @@ jobs: fi guides-lint: - # Lints the embedded guide text with Vale. Findings are reported but don't fail + # Lints the embedded guide text with Vale (the local rules plus one package rule, which + # the action downloads with `vale sync`). Findings are reported but do not fail # the job yet (fail_on_error: false); a later change sets it to true. Don't make # this job a required check before then. The action reports through pull request # annotations, so it runs only on pull requests. @@ -93,6 +94,5 @@ jobs: version: 3.24.0 reviewdog_version: 0.21.0 fail_on_error: false - sync: false files: rust/src glob: "**/guides/*.md" diff --git a/.gitignore b/.gitignore index 307e88b4..fbdd16c8 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,7 @@ __pycache__ # Local end-to-end test evidence stash/ + +# Vale package styles downloaded by `vale sync` +.vale/styles/Microsoft/ +.vale/styles/config/ diff --git a/.vale.ini b/.vale.ini index 3433d0e7..85437199 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,8 +1,11 @@ # Vale configuration for the embedded guide text (`gddy guide `). -# One local rule (repeated words) is on, to prove the wiring. The real rule set -# arrives in follow-up changes. +# Local rules live in .vale/styles/GddyCli. The only package rule that runs is +# Microsoft.Contractions: the package is downloaded by `vale sync`, and each +# package rule has to be switched on by name below. StylesPath = .vale/styles MinAlertLevel = suggestion +Packages = Microsoft [rust/src/*/guides/*.md] BasedOnStyles = GddyCli +Microsoft.Contractions = YES diff --git a/.vale/styles/GddyCli/AcceptedAbbreviations.yml b/.vale/styles/GddyCli/AcceptedAbbreviations.yml new file mode 100644 index 00000000..36872117 --- /dev/null +++ b/.vale/styles/GddyCli/AcceptedAbbreviations.yml @@ -0,0 +1,31 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +level: error +ignorecase: true +# Re-case the replacement when the match starts a sentence ("Prior to" becomes "Before"). +capitalize: true +action: + name: replace +swap: + on-prem: on-premises + on premise: on-premises + on-premise: on-premises + blacklist: blocklist + blacklisted: blocklisted + blacklisting: blocklisting + whitelist: allowlist + whitelisted: allowlisted + whitelisting: allowlisting + utilize: use + utilizes: uses + utilized: used + utilizing: using + utilization: use + in order to: to + allows you to: lets you + is able to: can + in the event that: if + prior to: before + subsequent to: after + it is recommended: it's recommended + wizard: guided workflow diff --git a/.vale/styles/GddyCli/AfterNotOnce.yml b/.vale/styles/GddyCli/AfterNotOnce.yml new file mode 100644 index 00000000..bd6405ef --- /dev/null +++ b/.vale/styles/GddyCli/AfterNotOnce.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Use 'After' instead of '%s' to start a sentence. 'Once' implies a one-time event." +level: warning +scope: sentence +ignorecase: false +tokens: + - '^Once you' + - '^Once the' + - '^Once your' diff --git a/.vale/styles/GddyCli/BannedVocabulary.yml b/.vale/styles/GddyCli/BannedVocabulary.yml new file mode 100644 index 00000000..de33c21a --- /dev/null +++ b/.vale/styles/GddyCli/BannedVocabulary.yml @@ -0,0 +1,49 @@ +# Filler and inflated words with a plain alternative. Keep the tokens in alphabetical order. +extends: existence +message: "'%s' is banned vocabulary. Use a plain alternative." +level: error +scope: sentence +ignorecase: true +tokens: + # Single words + - '\badditionally\b' + - '\bcommence[ds]?\b' + - '\bcomprehensive\b' + - '\bcutting-edge\b' + - '\bdeep dive\b' + - '\bdelve[ds]?\b' + - '\bempower(s|ed|ing|ment)?\b' + - '\bendeavou?rs?\b' + - '\bessentially\b' + - '\bfacilitate[ds]?\b' + - '\bfundamentally\b' + - '\bfurthermore\b' + - '\bgame-?changing\b' + - '\bharness(es|ed|ing)?\b' + - '\bholistic(ally)?\b' + - '\binherently\b' + - '\blandscape\b' + - '\bleverage[ds]?\b' + - '\bmoreover\b' + - '\bnotably\b' + - '\bparadigm\b' + - '\bpivotal\b' + - '\brobust(ness)?\b' + - '\bseamless(ly)?\b' + - '\bsuch as\b' + - '\bsynerg(y|ies|istic)\b' + - '\bunpack(s|ed|ing)?\b' + - '\butilize[ds]?\b' + # Phrases + - 'important to note' + - 'in order to' + - "in today's world" + - 'it bears mentioning' + - 'it should be noted' + - "it's worth noting" + - 'key to understanding' + - 'needless to say' + - 'offers a way to' + - 'plays a crucial role' + - 'prior to' + - 'serves as' diff --git a/.vale/styles/GddyCli/DiscouragedVocabulary.yml b/.vale/styles/GddyCli/DiscouragedVocabulary.yml new file mode 100644 index 00000000..612ae2b3 --- /dev/null +++ b/.vale/styles/GddyCli/DiscouragedVocabulary.yml @@ -0,0 +1,13 @@ +# Words to avoid in guides. Warning level until the guides are cleaned up. +extends: existence +message: "Avoid '%s'. Use a plain alternative." +level: warning +scope: sentence +ignorecase: true +tokens: + - '[Aa]bove' + - '[Aa]ppears?' + - '[Bb]elow' + - '[Cc]urrently' + - '[Pp]lease' + - '[Vv]ia' diff --git a/.vale/styles/GddyCli/ImperativeHeadings.yml b/.vale/styles/GddyCli/ImperativeHeadings.yml new file mode 100644 index 00000000..6c9c0aa3 --- /dev/null +++ b/.vale/styles/GddyCli/ImperativeHeadings.yml @@ -0,0 +1,9 @@ +# Matches a fixed list of leading gerunds. A heading that starts with another gerund +# needs a manual check. +extends: existence +message: "Heading starts with a gerund ('%s'). Use the imperative form instead, for example 'Configure' not 'Configuring'." +level: warning +scope: heading +ignorecase: false +tokens: + - '^(Adding|Configuring|Creating|Deleting|Deploying|Enabling|Getting|Installing|Managing|Registering|Removing|Running|Setting|Starting|Stopping|Testing|Transferring|Updating|Upgrading|Using|Viewing|Working)\b' diff --git a/.vale/styles/GddyCli/LatinAbbreviations.yml b/.vale/styles/GddyCli/LatinAbbreviations.yml new file mode 100644 index 00000000..e0cbdbea --- /dev/null +++ b/.vale/styles/GddyCli/LatinAbbreviations.yml @@ -0,0 +1,18 @@ +# The swaps match the trailing space or comma and put it back, so a one-click fix +# turns "e.g. the" into "for example the", not "for examplethe". +extends: substitution +message: "Use '%s' instead of '%s'." +ignorecase: true +# Re-case the replacement when the match starts a sentence ("E.g. " becomes "For example "). +capitalize: true +level: error +nonword: true +action: + name: replace +swap: + '\b(?:eg|e\.g\.)\s': 'for example ' + '\b(?:eg|e\.g\.),': 'for example,' + '\bviz\.\s': 'namely ' + '\bviz\.,': 'namely,' + '\bergo\s': 'therefore ' + '\bergo,': 'therefore,' diff --git a/.vale/styles/GddyCli/MaxSentenceLength.yml b/.vale/styles/GddyCli/MaxSentenceLength.yml new file mode 100644 index 00000000..6e0c2fec --- /dev/null +++ b/.vale/styles/GddyCli/MaxSentenceLength.yml @@ -0,0 +1,6 @@ +extends: occurrence +message: "Sentence has %s words. Keep sentences under 30 words for readability." +level: warning +scope: sentence +max: 30 +token: '\S+' diff --git a/.vale/styles/GddyCli/MayVsMight.yml b/.vale/styles/GddyCli/MayVsMight.yml new file mode 100644 index 00000000..bab0e596 --- /dev/null +++ b/.vale/styles/GddyCli/MayVsMight.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use 'might' for possibility and 'may' for permission only: '%s'." +level: warning +scope: sentence +ignorecase: true +tokens: + - '\bmay (not |be |cause |fail|result|change|vary|differ|take|require|need|have|include|contain|return|receive|lose|break|affect|impact|prevent|block|delay|timeout|expire|exceed|overlap|conflict)' diff --git a/.vale/styles/GddyCli/NoAndOr.yml b/.vale/styles/GddyCli/NoAndOr.yml new file mode 100644 index 00000000..d2ef6d02 --- /dev/null +++ b/.vale/styles/GddyCli/NoAndOr.yml @@ -0,0 +1,8 @@ +# "and/or" leaves the reader to guess. Say which one is true. +extends: existence +message: "Don't use 'and/or'. Decide which one is true and say 'and' or 'or'." +level: warning +scope: text +nonword: true +tokens: + - '\band/or\b' diff --git a/.vale/styles/GddyCli/NoEmDash.yml b/.vale/styles/GddyCli/NoEmDash.yml new file mode 100644 index 00000000..0ac97346 --- /dev/null +++ b/.vale/styles/GddyCli/NoEmDash.yml @@ -0,0 +1,9 @@ +# Only the em dash character (U+2014). En dashes in number ranges (10–120) are fine. +# Warning level until the guides are cleaned up. +extends: existence +message: "Remove the em dash. Use a colon, period, comma or new sentence." +level: warning +scope: text +nonword: true +tokens: + - '—' diff --git a/.vale/styles/GddyCli/NoIe.yml b/.vale/styles/GddyCli/NoIe.yml new file mode 100644 index 00000000..a3d4991c --- /dev/null +++ b/.vale/styles/GddyCli/NoIe.yml @@ -0,0 +1,9 @@ +# "i.e." has no short replacement that keeps its meaning, so the rule asks for a rewrite +# and offers no automatic fix. +extends: existence +message: "Don't use 'i.e.'. Rewrite the sentence, or use 'in other words'." +level: error +ignorecase: true +nonword: true +tokens: + - '\bi\.e\.' diff --git a/.vale/styles/GddyCli/NoNumberedHeadings.yml b/.vale/styles/GddyCli/NoNumberedHeadings.yml new file mode 100644 index 00000000..4f0f2679 --- /dev/null +++ b/.vale/styles/GddyCli/NoNumberedHeadings.yml @@ -0,0 +1,8 @@ +# A step number in a heading ("## 1. Create the application") goes stale when steps move. +extends: existence +message: "Don't number headings. Remove the step number from '%s'." +level: warning +scope: heading +nonword: true +tokens: + - '^\d+\.\s' diff --git a/.vale/styles/GddyCli/NoPassiveVoice.yml b/.vale/styles/GddyCli/NoPassiveVoice.yml new file mode 100644 index 00000000..11b6ac11 --- /dev/null +++ b/.vale/styles/GddyCli/NoPassiveVoice.yml @@ -0,0 +1,43 @@ +# Matches a short list of common passive phrases. A manual check finds the rest. +extends: existence +message: "Passive voice detected ('%s'). Prefer active voice." +level: warning +ignorecase: true +tokens: + - 'is created' + - 'is returned' + - 'is sent' + - 'is deleted' + - 'is updated' + - 'is used' + - 'is required' + - 'is needed' + - 'is called' + - 'is stored' + - 'is generated' + - 'is triggered' + - 'is passed' + - 'is included' + - 'is provided' + - 'are created' + - 'are returned' + - 'are sent' + - 'are deleted' + - 'are updated' + - 'are used' + - 'are required' + - 'are stored' + - 'are included' + - 'are provided' + - 'was created' + - 'was returned' + - 'was sent' + - 'was deleted' + - 'was updated' + - 'were created' + - 'were returned' + - 'were sent' + - 'been created' + - 'been deleted' + - 'been updated' + - 'been sent' diff --git a/.vale/styles/GddyCli/NoRecapHeadings.yml b/.vale/styles/GddyCli/NoRecapHeadings.yml new file mode 100644 index 00000000..b88a7808 --- /dev/null +++ b/.vale/styles/GddyCli/NoRecapHeadings.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Remove the recap heading '%s'. A guide shouldn't end with a summary or recap section." +level: warning +scope: heading +ignorecase: true +tokens: + - '^(Summary|What you learned|What you did|What we learned|What we covered|Recap|Wrapping up|Conclusion|Key takeaways|Next steps)$' diff --git a/.vale/styles/GddyCli/NoSlashOption.yml b/.vale/styles/GddyCli/NoSlashOption.yml new file mode 100644 index 00000000..1a2be304 --- /dev/null +++ b/.vale/styles/GddyCli/NoSlashOption.yml @@ -0,0 +1,14 @@ +# A slash is fine for a rate or ratio (req/min, km/h). In prose, a slash that stands in for +# "and" or "or" ("create/upload", "true/false") leaves the reader to guess. Write the word. +# Text in code style is skipped by Vale, so `a/b` and paths in backticks aren't flagged. +# "and/or" is reported by GddyCli.NoAndOr. +extends: existence +message: "Replace the slash in '%s' with 'and' or 'or', whichever is true." +level: warning +scope: text +nonword: true +tokens: + - '(? Date: Mon, 16 Nov 2026 15:43:30 -0500 Subject: [PATCH 4/4] ci: skip AI assistant notes in the style check and fix the sentence-length 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. --- .vale.ini | 4 ++++ .vale/styles/GddyCli/MaxSentenceLength.yml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 85437199..7e3531d5 100644 --- a/.vale.ini +++ b/.vale.ini @@ -9,3 +9,7 @@ Packages = Microsoft [rust/src/*/guides/*.md] BasedOnStyles = GddyCli Microsoft.Contractions = YES + +# Paragraphs that start with "AI assistants:" speak to an AI assistant, not to the +# reader of the guide. Tests pin their exact wording, so the prose rules skip them. +BlockIgnores = (?m)^AI assistants:[^\n]* diff --git a/.vale/styles/GddyCli/MaxSentenceLength.yml b/.vale/styles/GddyCli/MaxSentenceLength.yml index 6e0c2fec..1abb1362 100644 --- a/.vale/styles/GddyCli/MaxSentenceLength.yml +++ b/.vale/styles/GddyCli/MaxSentenceLength.yml @@ -1,5 +1,5 @@ extends: occurrence -message: "Sentence has %s words. Keep sentences under 30 words for readability." +message: "Sentence has %d words. Keep sentences under 30 words for readability." level: warning scope: sentence max: 30