Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .github/workflows/cicd.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
15 changes: 15 additions & 0 deletions .vale.ini
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Vale configuration for the embedded guide text (`gddy guide <name>`).
# 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]*
31 changes: 31 additions & 0 deletions .vale/styles/GddyCli/AcceptedAbbreviations.yml
Original file line number Diff line number Diff line change
@@ -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
9 changes: 9 additions & 0 deletions .vale/styles/GddyCli/AfterNotOnce.yml
Original file line number Diff line number Diff line change
@@ -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'
49 changes: 49 additions & 0 deletions .vale/styles/GddyCli/BannedVocabulary.yml
Original file line number Diff line number Diff line change
@@ -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'
13 changes: 13 additions & 0 deletions .vale/styles/GddyCli/DiscouragedVocabulary.yml
Original file line number Diff line number Diff line change
@@ -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'
9 changes: 9 additions & 0 deletions .vale/styles/GddyCli/ImperativeHeadings.yml
Original file line number Diff line number Diff line change
@@ -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'
18 changes: 18 additions & 0 deletions .vale/styles/GddyCli/LatinAbbreviations.yml
Original file line number Diff line number Diff line change
@@ -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,'
6 changes: 6 additions & 0 deletions .vale/styles/GddyCli/MaxSentenceLength.yml
Original file line number Diff line number Diff line change
@@ -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+'
7 changes: 7 additions & 0 deletions .vale/styles/GddyCli/MayVsMight.yml
Original file line number Diff line number Diff line change
@@ -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)'
8 changes: 8 additions & 0 deletions .vale/styles/GddyCli/NoAndOr.yml
Original file line number Diff line number Diff line change
@@ -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'
9 changes: 9 additions & 0 deletions .vale/styles/GddyCli/NoEmDash.yml
Original file line number Diff line number Diff line change
@@ -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:
- '—'
9 changes: 9 additions & 0 deletions .vale/styles/GddyCli/NoIe.yml
Original file line number Diff line number Diff line change
@@ -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\.'
8 changes: 8 additions & 0 deletions .vale/styles/GddyCli/NoNumberedHeadings.yml
Original file line number Diff line number Diff line change
@@ -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'
43 changes: 43 additions & 0 deletions .vale/styles/GddyCli/NoPassiveVoice.yml
Original file line number Diff line number Diff line change
@@ -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'
7 changes: 7 additions & 0 deletions .vale/styles/GddyCli/NoRecapHeadings.yml
Original file line number Diff line number Diff line change
@@ -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)$'
14 changes: 14 additions & 0 deletions .vale/styles/GddyCli/NoSlashOption.yml
Original file line number Diff line number Diff line change
@@ -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:
- '(?<![\w/.:-])[A-Za-z][A-Za-z-]*/[A-Za-z][A-Za-z-]*(?![\w/.:-])'
exceptions:
- '(?i)and/or'
- '(?i)\w+/(?:s|sec|min|h|hr|hour|day|week|month|year)'
6 changes: 6 additions & 0 deletions .vale/styles/GddyCli/Repetition.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
extends: repetition
message: "'%s' is repeated."
level: error
alpha: true
tokens:
- '[^\s]+'
3 changes: 3 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 sync && vale rust/src/*/guides/*.md)

# Regenerate the embedded API catalog (needs access to GoDaddy's internal spec repos)
cargo run -p generate-api-catalog
```
Expand Down
Loading