feat(docs): add Coder.BrandNames Vale rule, enforce HashiCorp casing #25501
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # Coder.BrandNames - enforce canonical brand-name casing in prose. | ||
|
Contributor
There was a problem hiding this comment. P3 [CRF-6] The PR description's verification section says the rule "flags the 7 instances the cleanup commit fixes." Vale scopes to
|
||
| # | ||
| # Vale's substitution rule applies in prose only; it skips fenced code | ||
| # blocks, inline code, and URLs by default. That means `hashicorp/kubernetes` | ||
| # (Terraform provider source) and `developer.hashicorp.com` (URL) stay | ||
| # untouched. The rule fires on body text and headings where the wrong | ||
| # casing appears as a normal word. | ||
| # | ||
| # Level: error. Each swap targets a brand whose owner publishes a | ||
| # canonical casing; "Hashicorp Vault" instead of "HashiCorp Vault" is | ||
| # objectively wrong, not a judgment call. The existing-content violation | ||
| # count is zero (cleanup landed in the previous commit), so this rule | ||
|
Contributor
There was a problem hiding this comment. P3 [CRF-4] "cleanup landed in the previous commit" is a temporal reference that dissolves after merge. After a squash merge, "the previous commit" doesn't exist. After a rebase merge, the SHA changes. The factual claim (violation count is zero) stands on its own. Drop the parenthetical: (Leorio)
|
||
| # can ship at error from day one. | ||
| # | ||
| # Adding a brand: append a key/value to the swap table below and audit | ||
| # the docs corpus for the wrong-casing variant. Keep the message template | ||
| # unchanged; the `%s` token interpolates the matched (wrong) text. | ||
|
Contributor
There was a problem hiding this comment. P2 [CRF-2] The comment says "the Suggestion: (Leorio)
Comment on lines
+1
to
+17
Contributor
There was a problem hiding this comment. P3 [CRF-7] The header comment is 17 lines for 11 lines of config. Roughly half restates identifiers or duplicates content from
The trap (false-positive scope) and why-not-what (error level) carry their weight. Trimmed draft that keeps both: # substitution rules skip code blocks, inline code, and URLs, so
# provider sources (hashicorp/kubernetes) and URLs are unaffected.
#
# Error from day one: brand casing is objectively right or wrong,
# and existing-content violations are zero.
#
# Adding a brand: append to swap, audit docs for violations.(Gon)
|
||
| extends: substitution | ||
| message: "Use '%s' instead of '%s' (brand-name casing)." | ||
| link: https://github.com/coder/coder/blob/main/docs/.style/style-guide.md#brand-names | ||
| level: error | ||
|
Contributor
There was a problem hiding this comment. Note [CRF-12] Worth knowing:
|
||
| ignorecase: false | ||
| nonword: false | ||
|
Contributor
There was a problem hiding this comment. P4 [CRF-8] No regression fixture for the rule. If someone later breaks the swap YAML or removes an entry, there's no automated check that the rule still fires on known-bad input. The "test" is the absence of violations in the corpus, which is indistinguishable from a broken rule that fires on nothing. Not this PR's debt (no Vale rule test infrastructure exists in the repo), but worth noting as the
|
||
| action: | ||
| name: replace | ||
| swap: | ||
| Hashicorp: HashiCorp | ||
|
Contributor
There was a problem hiding this comment. P3 [CRF-5] The swap table catches The stated fallback ( swap:
hashicorp: HashiCorp
Hashicorp: HashiCorp
HASHICORP: HashiCorp(Zoro P3, Hisoka Note)
|
||
| HASHICORP: HashiCorp | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2 [CRF-1] PR description says "Two commits, in this order so each is independently valid" and lists exactly two. The branch has five:
Commit 5 changes
Google.ParensfromsuggestiontoNO, dropping ~1800 suggestion-level findings frommake lint/prose. The commit message is honest and the rationale is sound, but this is an independent Vale severity-policy decision invisible to reviewers who scope from the description. The verification numbers in the PR description ("7681 suggestions") may reflect the pre-Parens-disable state.Update the PR description to account for all five commits, or split the Google.Parens disable into its own PR. (Mafu-san P2, Hisoka P3, Luffy P3, Kite P3)