mirror of https://github.com/coder/coder.git synced 2026-11-01 04:47:17 +08:00

Files

T

Nick Vigilante 66a55e1ebd feat(docs/.style): enable Coder.GerundHeading (#25502 )

## Summary

Adds `Coder.GerundHeading`, a `warning`-level Vale rule that flags
headings and titles whose first word ends in `-ing` (a gerund or present
participle used as a verb form, like `Installing` or `Configuring`).

Task headings read better in the imperative (`Install Coder`); concept
headings read better as nouns (`Installation`). The choice is
context-dependent, so the rule is a `warning`: it annotates without
blocking CI.

The style-guide section this rule enforces already lives on `main` at
[`capitalization-and-punctuation.md#no-gerund-leading-headings`](https://github.com/coder/coder/blob/main/docs/.style/style-guide/capitalization-and-punctuation.md#no-gerund-leading-headings).
This PR adds the matching rule and nothing else: the net diff is a
single file.

## What's in this PR

- `docs/.style/styles/Coder/GerundHeading.yml` (new). Heading-scoped
`existence` rule, anchored regex `^[A-Z][a-z]+ing\b`, `level: warning`.
- `exceptions:` mirror the style guide's **Exceptions** section: `-ing`
words that name a feature, category, or attribute (`Logging`,
`Monitoring`, `Networking`, `Tracing`, `Troubleshooting`, `Pricing`,
`Billing`, ...) plus words that only look like gerunds (`Bring`,
`String`, ...).

This branch was rebuilt onto `main`'s restructured `docs/.style/` (the
single `style-guide.md` became a `style-guide/` directory and Vale moved
into `ci.yaml`), which is why the diff is now just the rule.

## Scope: rule only

The rule ships as a `warning`, so it surfaces the existing `-ing` task
headings (~200) as advisory annotations rather than failing CI.
De-gerunding those headings (imperative rewrites plus internal anchor
fixes) is a corpus-wide content change and lands in a dedicated
follow-up PR, tracked separately. Splitting keeps this PR to the rule
and keeps the content churn reviewable on its own.

<details>
<summary>Decision log</summary>

**`existence` + `scope: heading`, not `sequence` + `tag: VBG`.** Vale's
POS-tagging sequence rules are hardcoded to sentence scope and never
reach heading text, so a `VBG` sequence rule fires on paragraphs and
stays silent on H1-H6. Google's and Microsoft's heading rules all use
the existence+regex pattern; this rule follows it.

**Exceptions align to the committed style guide, not the original branch
design.** The first draft of this rule intentionally left concept-noun
gerunds (`Logging`, `Monitoring`, ...) in the flagged set. Since then,
`main`'s style guide declared exactly those as non-violations. The rule
now excepts them so the rule and the guide agree. An excepted first word
is allowed everywhere, which is a deliberate precision trade-off for a
first-word regex: `Monitoring Coder` (a task) is not flagged, but the
standalone concept heading `Monitoring` stays clean.

**Severity = warning.** The imperative-vs-noun choice is judgment-bound,
which is the case the `warning` tier exists for: strong guidance,
legitimate human-judgment exceptions, no CI block.

**Verification.** `make lint/prose` loads the rule cleanly; the excepted
words (`Troubleshooting`, `Monitoring`, `Networking`, `Logging`,
`Contributing`, `Styling`, `Scaling`, `Routing`, `Pricing`, `Billing`,
`Tracing`) each produce zero findings.

</details>

---

*Opened via Coder Agents on @nickvigilante's behalf.*

2026-07-23 20:38:42 +00:00

BrandNames.yml

fix: exempt docs/.style/ prose from Vale's own Coder rules (#27192 )

2026-07-18 13:41:27 -04:00

DemoError.yml

fix: preserve Vale severity in CI annotations and add three-severity demo (#26587 )

2026-06-23 12:55:15 -04:00

DemoSuggestion.yml

fix: preserve Vale severity in CI annotations and add three-severity demo (#26587 )

2026-06-23 12:55:15 -04:00

DemoWarning.yml

fix: preserve Vale severity in CI annotations and add three-severity demo (#26587 )

2026-06-23 12:55:15 -04:00

GerundHeading.yml

feat(docs/.style): enable Coder.GerundHeading (#25502 )

2026-07-23 20:38:42 +00:00

README.md

fix: exempt docs/.style/ prose from Vale's own Coder rules (#27192 )

2026-07-18 13:41:27 -04:00

README.md

Coder custom Vale rules

Custom Vale rules specific to Coder live here. Each rule is a YAML file that Vale loads through the BasedOnStyles = Coder setting in the repo-root .vale.ini.

Active rules ship as YAML files in this directory. See the matching sections in docs/.style/style-guide/ for the user-facing policy each rule enforces. Follow-up PRs add rules incrementally. Planned coverage:

Dev Container terminology
Limit we
Setup vs set up, Quickstart casing
Next steps vs Learn more
Vale substitution rule scaffold
Weasel words
Em-dash and en-dash mirror in Vale
Inclusive-language substitutions
Product-voice rules

Authoring a new rule

Write a YAML file under this directory. Name it after the rule's intent, for example InclusiveLanguage.yml or ProductVoice.yml.
Each rule's message: should link to the matching section in the appropriate subpage of docs/.style/style-guide/, ideally with a deep-link anchor, so a contributor reading a Vale warning can jump straight to the guidance.
Land at level: warning first. Promote to level: error only after both conditions hold:
- The rule is objectively correct (typo, brand-name casing, banned substitution).
- The existing-content violation count for the rule reaches zero.
A follow-up PR adds a parity CI check that verifies every rule here has a matching section in style-guide/. Add the section in the same PR as the rule.

Reference

Vale docs: https://vale.sh/docs/
Vale rule types: https://vale.sh/docs/topics/styles/