feat(.vale.ini): strip third-party rules; enable per-rule only#26586
Draft
nickvigilante wants to merge 1 commit into
Draft
feat(.vale.ini): strip third-party rules; enable per-rule only#26586nickvigilante wants to merge 1 commit into
nickvigilante wants to merge 1 commit into
Conversation
Collapse the Vale config to load only the Coder rule package. Drop the
Packages directive (no external packages sync), BasedOnStyles=Coder
only, drop every Google.X, write-good.X, and alex.X rule line. The
repo-root .vale.ini becomes a four-line config plus a doctrine comment.
Motivation: the previous config carried ~12,000 baseline findings
corpus-wide (412 errors / 5380 warnings / 6247 suggestions), almost
entirely from third-party rules whose false-positive patterns Vale
cannot distinguish from author intent. Google.Headings false-positives
on every acronym and product name (VM, AWS, Coder, Vale, JetBrains);
Google.Will fires on legitimate event-sequencing prose; alex.* rules
were enabled in DOCS-40 without a corpus cleanup commit. Engineers
stop reading annotations when CI cries wolf. The fix is a tight,
trustworthy ruleset rather than tuning around individual false
positives.
Doctrine added to docs/.style/README.md ('Adding a Vale rule'): every
rule ships clean (zero baseline findings) with a deliberate per-rule
severity choice. 'error' blocks merge in CI; 'warning' surfaces
annotations without failing CI; 'suggestion' surfaces 'notice'
annotations. The severity choice and the cleanup discipline are
independent, so a rule landing at any severity still ships with zero
baseline findings to keep the annotation channel trustworthy. Third-
party rules return via the same per-rule PR pattern after their corpus
is clean. See DOCS-425.
Effect on baseline: 412 errors -> 0, 5380 warnings -> 0, 6247
suggestions -> 0. Verified with 'mise exec aqua:errata-ai/vale -- vale
--no-exit docs/' against 465 files. Vale sync now skips the
third-party packages (the directories remain on disk for developers
who already synced; they're gitignored and no longer load). The CI
'Vale prose lint' step is currently advisory; PR #26587 (DOCS-426)
installs the merge gate that honors the doctrine's 'error blocks
merge' semantic.
95f6409 to
ba20bc2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes DOCS-425.
Summary
Collapse
.vale.inito load only the Coder rule package. DropPackages = Google, alex, write-good. ReplaceBasedOnStyles = Google, write-good, CoderwithBasedOnStyles = Coder. Drop everyGoogle.X,write-good.X, andalex.Xper-rule line. Add a rule-rollout doctrine underdocs/.style/README.md.Why
The previous config carried roughly 12,000 baseline findings across
docs/: 412 errors / 5380 warnings / 6247 suggestions, almost entirely from third-party rules whose false-positive patterns Vale cannot distinguish from author intent.Google.Headingsfalse-positives on every acronym and product name: VM, AWS, GCP, Coder, Vale, JetBrains, VS Code.Google.Willfires on legitimate event-sequencing prose.Google.Acronymsfires on widely-known terms the audience reads fluently (AWS, RDP, VPC).alex.*rules shipped in DOCS-40 without a corpus cleanup commit.When CI surfaces false positives, engineers stop reading annotations. PR #25501 review surfaced this concretely on
Google.Headings. The fix is a tight, trustworthy ruleset rather than tuning around individual false positives.Doctrine
Full text in
docs/.style/README.md. Summary:feat(docs/.style): enable <RuleName>style-guide.mdsection + custom YAML if applicableerrorblocks merge;warningandsuggestionannotate without failing CIApplies equally to Coder-authored rules and third-party rules. Third-party rules return through the same per-rule pattern after their corpus is clean.
Severity ladder
The three-severity ladder is deliberate. Some rules catch hard policy where any violation is wrong (brand names, banned first-person pronouns, em-dashes); those ship at
errorand block merge. Other rules catch strong guidance with legitimate human-judgment exceptions (disabledas a technical state vs. ableist usage); those ship atwarningand annotate without failing CI. Soft guidance (noun-as-adjective patterns likedesired state, wordiness) ships atsuggestionas anoticeannotation.The cleanup discipline applies at every severity. A rule landing at
warningorsuggestionstill ships with zero baseline findings; the rule's purpose is to catch new violations, not to surface a backlog of existing ones. Standing backlogs train contributors to ignore the annotation channel.The
error-blocks-merge half of this contract lands operationally via PR #26587 (DOCS-426), which removescontinue-on-error: trueandvale --no-exitfrom the CI step.Effect on the corpus baseline
Verified locally with
mise exec aqua:errata-ai/vale -- vale --no-exit docs/.Functional state after merge
The CI
Vale prose lintstep stays advisory (continue-on-error: true,--no-exit) until PR #26587 lands. With no rules loaded except Coder's package (currently empty onmain), the step is effectively a no-op untilCoder.BrandNameslands via PR #25501 (DOCS-34). At that point the lint step becomes aCoder.BrandNames-only check. Subsequent per-rule PRs extend coverage one rule at a time per the doctrine, each rule choosing the severity that matches its policy strictness.The Makefile target
docs/.style/.vale-synced: .vale.inistill runsvale sync, which is now a no-op becausePackagesis empty. The previously-synceddocs/.style/styles/{Google,alex,write-good}/directories remain on developers' disks (they're gitignored) but are no longer loaded by Vale.Sequencing
Google.Parens = NOchange, landsCoder.BrandNamesas the first concrete ruleDecision log
alex.*rules: yanked in this PR. They were enabled in DOCS-40 without a corpus cleanup commit. The "audit then keep" call returns them via dedicated per-rule PRs once the audit confirms baseline violation counts and the doctrine accepts them.Packagesdirective dropped: with no third-party rules loaded,vale synchad no work to do. Removing the directive avoids implying we intend to re-add packages without a per-rule PR. The directive returns when a future PR opts in a Google or write-good rule.docs/.style/README.mdrather than a dedicateddocs/.style/RULE_ROLLOUT.md. Keeps the contributor-facing entry point single, and the section sits alongside the existing "Editing the style guide" and "Editing the content guidelines" sections.errorwould either reject useful warning- and suggestion-level rules (noun-as-adjective patterns, wordiness guidance) or push them onto an inappropriate gate. The CI severity rendering and merge-gate work in PR fix: preserve Vale severity in CI annotations and block merge on errors #26587 was built specifically to support this ladder.Filed via Coder Agents on Nick's behalf.