Treat developer guide vale and asciidoc warnings as build errors#4971
Merged
Conversation
Drives the docs/developer-guide vale report to zero findings at every severity level, then promotes any future vale/asciidoctor warning to a build-breaking failure in the Build Developer Guide Docs workflow. Fixes are split between real prose corrections (heading colon capitalization, stale "e.g." / "E.g." rewrites, British → American spelling, punctuation inside quotes, broken pre-existing prose) and documented rule disables in docs/developer-guide/.vale.ini covering default checks that misfire systematically on a long-form developer guide (passive voice, sentence length, acronym definitions, the "disabled" accessibility flag, etc.). The styles directory remains gitignored, with an exception that tracks the project vocabulary so CI sees the same accept list as local contributors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Developer Guide build artifacts are available for download from this workflow run:
Developer Guide quality checks: |
Contributor
Cloudflare Preview
|
Splits the find_unused_images.py check into a real quality gate: - ignore non-image files in the image tree so .gitkeep placeholders no longer flash as orphans - exit non-zero when at least one unused image is found so the new quality-gate step at the end of the developer-guide workflow can fail the build with the other linters Also removes docs/developer-guide/img/cn1libs-refresh.png, which was orphaned by #4952 when the matching image:: directive was deleted alongside the other cn1lib screenshots. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Critically re-examines each previously-disabled vale rule and keeps
only the ones whose recommendation is *wrong* for a developer-facing
reference, with a written rationale for each. The rest are now back on
as build-failing checks and the existing prose has been rewritten to
match.
Real defects that the re-enabled rules caught and that the prose now
fixes:
- write-good.Illusions found "IntelliJ IDEA IDEA" and "Eclipse IDE
IDE" (the kind of LLM-generated repetition we want to keep catching).
- write-good.ThereIs cleared 44 "There is..." / "There are..."
sentence openers in favour of stronger verb phrases.
- Microsoft.FirstPerson / Microsoft.We replaced ~190 instances of
authorial "I", "we", and "let's" with second-person or imperative
voice consistent with the rest of the guide.
- Microsoft.Contractions normalised 70+ "they are" / "is not" / "what
is" forms to the contractions the rule prefers (and fixed a real
"where is says" typo on Push-Notifications.asciidoc).
- Microsoft.Adverbs cut about 40 redundant softeners; the remaining
precise adverbs (`lazily` on `LazyValue`, `gracefully` on fallback
degradation, etc.) carry per-line vale-skip rationale.
- Microsoft.Auto switched generic "auto-X" hyphenations to the
unhyphenated Microsoft form, while keeping Apple/Google product
terms ("Auto-Renewable subscriptions") behind per-line skips.
- Microsoft.OxfordComma, Microsoft.Wordiness, Microsoft.Percentages,
proselint.Skunked, and write-good.So were each driven to zero by
rewrites.
- proselint.Needless additions to the project Vocab keep Android's
"Lollipop" codename and "extensible" / "oversized" from being
spell-corrected to "lollypop" / "extendable" / "oversize".
Vocab additions cover Java ME / Java SE / Java EE platform names so
they no longer trip Microsoft.FirstPerson on the trailing "ME".
The rules that remain off carry a paragraph in `.vale.ini` describing
*why* their recommendation is inappropriate for this guide (E-Prime
banning "to be", Microsoft.GeneralURL turning "URL" into "address",
Microsoft.Spacing firing on dotted code identifiers, Microsoft.Ranges
rewriting ISO 639-1 / ISO 3166-1 standard codes, Microsoft.Semicolon
firing on Java statement terminators inside `[source,java]` blocks,
and so on).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The bulk "auto-snap" -> "autosnap" rewrite that satisfied Microsoft.Auto in prose accidentally also renamed the image:: target to a path that doesn't exist on disk (the image file is still guibuilder-2-smart-insets-auto-snap-checkboxes.png). That broke both the website's lychee link check and the developer guide workflow's unused-image gate. The image filename is inside an image:: directive that vale's adoc parser excludes from prose, so restoring the hyphen keeps the rule clean while pointing readers at the file that actually ships in img/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
docs/developer-guideVale report to zero findings at every severity level (was 362 errors + 2,778 warnings + 8,906 suggestions).always(), and adds a final quality-gate step that fails the job when either tool reports anything.E.g.rewrites, British → American spelling, punctuation inside quotes, broken pre-existing prose liketools in the market. it's a tool…) and documented rule disables indocs/developer-guide/.vale.inifor default checks that systematically misfire on a long-form developer guide (passive voice, sentence-length cap, acronym-definition requirements, thedisabledaccessibility flag, etc.). Each disable has a per-rule rationale comment.// vale-skip:exceptions where the rule was generally correct but the specific instance was a technical false positive (XXXplaceholder inside a verbatim TeaVM error message,vs.abbreviation in headings, the parser misclassifying a paragraph as part of a heading,Very High Resas a labelled DPI bucket).docs/developer-guide/styles/config/vocabularies/CodenameOne/accept.txt(refined.gitignorekeeps synced style packages ignored).Test plan
Run Asciidoctor lintstep still passes (no warnings produced by the document conversion).Run Vale style linterstep reportsIssues: 0at--minAlertLevel=suggestion.Fail build on developer guide quality issuesstep prints the "passed" message on a clean run..adoc) → confirm Vale flags it and the quality-gate step fails the job.🤖 Generated with Claude Code