diff --git a/.github/workflows/cicd.yml b/.github/workflows/cicd.yml index cb0f9bf8..adedaca8 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 (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. + 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 + 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 new file mode 100644 index 00000000..7e3531d5 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,15 @@ +# Vale configuration for the embedded guide text (`gddy guide `). +# 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 + +# 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/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..1abb1362 --- /dev/null +++ b/.vale/styles/GddyCli/MaxSentenceLength.yml @@ -0,0 +1,6 @@ +extends: occurrence +message: "Sentence has %d 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: + - '(?