-
Notifications
You must be signed in to change notification settings - Fork 3
chore: add gated docs linting and repoint the e2e Gitea image #262
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
80c1c20
chore(docs): add markdown linting and a documentation style guide
sunib 85e54da
chore(docs): wire markdownlint-cli2 and Vale into task lint
sunib 3b351f1
docs: bring the READMEs in line with the style guide
sunib f8b6509
docs: apply the style guide to architecture.md and configuration.md
sunib eaad579
Merge branch 'main' into chore/docs-linting
sunib b12b6c8
chore(docs): gate the docs linters on an explicit file list
sunib 3c9eff3
chore: fix failing Gitea image default
sunib 75e8acf
docs: correct the linters' own description of how they run
sunib bffa9c3
fix(docs): catch British spellings at the start of a sentence
sunib d2e8cb6
chore: this should resolve the last problems
sunib File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # Markdown files the documentation linters gate. | ||
| # | ||
| # `task lint` fails on markdownlint findings or Vale errors in these files and | ||
| # ignores every other .md file in the tree. That is a rollout position, not the | ||
| # destination: measured with the committed config, 102 of 174 linted files fail | ||
| # markdownlint and 148 of 174 fail Vale, so gating everything today would be a | ||
| # wall no one could land a change through. | ||
| # | ||
| # Add a file here once it passes. Check what it would cost first: | ||
| # | ||
| # markdownlint-cli2 docs/some-file.md | ||
| # vale docs/some-file.md | ||
| # task lint-markdown-fix DOCS_SCOPE=all # the mechanical half, whole tree | ||
| # | ||
| # `task lint-markdown DOCS_SCOPE=all` and `task lint-prose DOCS_SCOPE=all` show | ||
| # the whole backlog without gating on it. | ||
| # | ||
| # Every path here must be tracked by git; a typo fails the lint run rather than | ||
| # silently shrinking the gate to nothing. | ||
| # | ||
| # Not in scope here: hack/doccheck, which always checks references across every | ||
| # tracked markdown, Go, YAML, and shell file. Only structure and prose are | ||
| # staged this way. | ||
|
|
||
| README.md | ||
| docs/architecture.md | ||
| docs/configuration.md |
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| // markdownlint-cli2 configuration -- https://github.com/DavidAnson/markdownlint-cli2 | ||
| // | ||
| // Structural markdown rules. Prose is Vale's job (.vale.ini); references are | ||
| // hack/doccheck's. See docs/design/docs-linting.md for what each choice cost | ||
| // when measured against the real corpus. | ||
| // | ||
| // `task lint-markdown` runs this, and `task lint` includes it, over the files | ||
| // .docs-lint-scope lists. Everything else is checked only when you ask: | ||
| // markdownlint-cli2 docs/some-file.md | ||
| // task lint-markdown DOCS_SCOPE=all | ||
| // task lint-markdown-fix DOCS_SCOPE=all | ||
| // | ||
| // Never point this at a bare recursive glob: external-sources/ holds gitignored | ||
| // upstream checkouts with symlink cycles that have OOM-killed the host once. | ||
| // Pass an explicit file list from `git ls-files`. | ||
| { | ||
| "config": { | ||
| // Wrap at 100 is a convention, not a gate (docs/style-guide.md). 120 costs | ||
| // 119 fixes and still catches a runaway paragraph; 100 costs 890 and would | ||
| // reformat most of docs/. Code and tables cannot be rewrapped. | ||
| "MD013": { | ||
| "line_length": 120, | ||
| "code_blocks": false, | ||
| "tables": false, | ||
| "headings": true | ||
| }, | ||
|
|
||
| // The docs repeat headings like "Why" and "What it writes" under different | ||
| // parents on purpose. Only a clash between siblings is a real problem. | ||
| "MD024": { "siblings_only": true }, | ||
|
|
||
| // 3,369 dash bullets to 155 asterisks. "consistent" would only catch the | ||
| // files that mix and leave the split in the tree; --fix repairs all 156. | ||
| "MD004": { "style": "dash" }, | ||
|
|
||
| // docs/style-guide.md fixes the fence language set. Sorted by use; the last | ||
| // four are the ones the guide does not list yet (see the design doc's open | ||
| // questions). `sh` is deliberately absent: write `bash`. | ||
| "MD040": { | ||
| "allowed_languages": [ | ||
| "bash", | ||
| "yaml", | ||
| "text", | ||
| "mermaid", | ||
| "go", | ||
| "promql", | ||
| "console", | ||
| "json", | ||
| "jsonc", | ||
| "http", | ||
| "gitignore", | ||
| "dockerfile" | ||
| ] | ||
| }, | ||
|
|
||
| "MD029": { "style": "ordered" }, | ||
|
|
||
| // The demo GIF and the centered badge block in the root README. | ||
| "MD033": { | ||
| "allowed_elements": ["br", "details", "summary", "img", "div", "kbd", "sup"] | ||
| }, | ||
|
|
||
| // Wants padded table cells; the repo writes |---|---| in 1,604 places and | ||
| // that is not worth a reflow of every table. | ||
| "MD060": false | ||
|
|
||
| // MD041 (first line must be a top-level heading) stays on. It catches six | ||
| // real files today, and the root README is the only one in the repo that | ||
| // opens with something other than prose or a heading. Its badge block earns | ||
| // an inline `markdownlint-disable-next-line` rather than a global opt-out. | ||
| }, | ||
|
|
||
| // Generated by release-please, and a record of what happened rather than | ||
| // prose we maintain. Kept in sync with .vale.ini. | ||
| "ignores": ["CHANGELOG.md", "docs/finished/**", "external-sources/**", "node_modules/**"] | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # Vale configuration -- https://vale.sh/docs/vale-cli/structure/ | ||
| # | ||
| # Prose linting against docs/style-guide.md. The rules live in | ||
| # .vale/styles/HouseStyle/ and are written for this repository; no external | ||
| # package is used and `vale sync` is never needed, so a lint run works offline. | ||
| # See docs/design/docs-linting.md for the measurements and the rollout plan. | ||
| # | ||
| # `task lint-prose` runs this, and `task lint` includes it, over the files | ||
| # .docs-lint-scope lists. Everything else is checked only when you ask: | ||
| # vale docs/some-file.md | ||
| # task lint-prose DOCS_SCOPE=all | ||
| # | ||
| # Vale skips fenced code blocks and inline code by default, which is what makes | ||
| # the "identifiers keep American spelling" tier of the style guide work without | ||
| # a single exception being listed. Two rules opt out of that with `scope: raw` | ||
| # and say why in their own headers: EmDash.yml and Correctives.yml. | ||
| StylesPath = .vale/styles | ||
|
|
||
| # Warnings and suggestions are informational. This is not a policy choice we get | ||
| # to make -- Vale's exit code tracks errors alone, so a run with warnings still | ||
| # exits 0. Verified, because it decides which level a rule needs to gate: | ||
| # | ||
| # error fails the gate once one exists. Mechanical rules only. | ||
| # warning informs an edit. Real but needs a human to weigh. | ||
| # suggestion a call a machine cannot make (Filler-Judgment.yml). | ||
| MinAlertLevel = suggestion | ||
|
|
||
| [*.md] | ||
| BasedOnStyles = HouseStyle | ||
|
|
||
| # CHANGELOG.md is generated by release-please, and docs/finished/ is a record of | ||
| # what happened rather than prose we maintain. Both are out of scope. | ||
| [CHANGELOG.md] | ||
| BasedOnStyles = | ||
|
|
||
| [docs/finished/*.md] | ||
| BasedOnStyles = | ||
|
|
||
| # Per-file rule exemptions go here, one stanza per file, because .vale.ini is | ||
| # applied above the scope machinery and is the only suppression that survives | ||
| # `scope: raw`. See EmDash.yml for when a file earns one. Empty on purpose today: | ||
| # | ||
| # [docs/style-guide.md] | ||
| # HouseStyle.EmDash = NO |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # docs/style-guide.md -> "The construction the dash is hiding". | ||
| # | ||
| # The corrective appositive, `X, not Y`, is not banned. Used once it lands; used | ||
| # in every third paragraph it becomes the tic readers point at when they say text | ||
| # sounds machine-written. The guide budgets roughly one per page. | ||
| # | ||
| # This is the only rule here that a human could not enforce by reading a diff, | ||
| # because the problem is the density and not any single instance. | ||
| # | ||
| # `scope: raw` makes the whole file one block, so this fires once per over-budget | ||
| # file rather than once per paragraph. "Roughly one per page" has to become a | ||
| # number, and files here run to several pages: max 3 flags 75 files, max 1 flags | ||
| # 110, max 5 flags 52. Three is the middle, and it is a warning, so it informs an | ||
| # edit rather than blocking one. | ||
| # | ||
| # The cost of `raw` is that a match inside a code block counts, and that guess has | ||
| # now been measured: 20 in-fence matches across 16 files, of which exactly two are | ||
| # pushed over budget by them and would otherwise sit at the limit -- | ||
| # docs/spec/type-followability.md and | ||
| # test/fixtures/gitops-layouts/2-rendered/helm-environment-values/README.md. | ||
| # Two false alarms at warning level is cheaper than the alternative, which is | ||
| # giving up `raw` and counting per paragraph, where a budget of three is no budget | ||
| # at all. Left as is; do not re-litigate without new numbers. | ||
| # | ||
| # Note that unlike EmDash.yml, this rule needs no escape hatch. `raw` disables the | ||
| # in-file suppression comments there too, but a warning that fires once per file | ||
| # does not have to be silenced. | ||
| extends: occurrence | ||
| message: "Several 'X, not Y' correctives in one file. Budget roughly one per page, and prefer stating the correct thing positively." | ||
| link: https://github.com/ConfigButler/gitops-reverser/blob/main/docs/style-guide.md#the-construction-the-dash-is-hiding | ||
| level: warning | ||
| scope: raw | ||
| max: 3 | ||
| token: ',\s+(?:not|never|rather than)\s' |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| # docs/style-guide.md -> "Punctuation: no em dashes", the one hard rule. | ||
| # | ||
| # Vale skips code fences and inline code, so a dash inside a quoted specimen is | ||
| # left alone -- which is exactly what the style guide asks for. docs/style-guide.md | ||
| # itself is full of em dashes and is correctly never flagged. | ||
| # | ||
| # Known limitation: the reported count is a lower bound. A sentence with two | ||
| # dashes sometimes yields one alert. File-level detection is complete, so a gate | ||
| # is sound, but re-run after each pass instead of trusting one list. | ||
| # | ||
| # `scope: raw` was tried and reverted. It is tempting, because per-occurrence | ||
| # recall goes from 37% to 99.9% (measured over every tracked doc with fences and | ||
| # inline code stripped: 1,140 of 3,029 prose dashes at the default scope, 3,027 | ||
| # at raw). It is still the wrong trade for a gate, for three measured reasons: | ||
| # | ||
| # 1. It costs the exemption above. Raw makes the whole file one block, so fences | ||
| # and inline code stop being skipped: 92 of 3,126 dashes (2.9%) across 32 | ||
| # files, and style-guide.md flips from correctly clean to a false positive. | ||
| # 2. It cannot be suppressed. `<!-- vale off -->` and | ||
| # `<!-- vale HouseStyle.EmDash = NO -->` are markup-layer features that raw | ||
| # never sees, so the false positives above have no local escape hatch. | ||
| # 3. It does not buy gate correctness, because the default scope already has it. | ||
| # Over 148 files carrying a prose dash, the default scope misses none of them | ||
| # entirely and flags no clean file. Raw matches that and adds one false | ||
| # positive. Recall of the *count* is what improves, and the gate does not | ||
| # read the count. | ||
| # | ||
| # So: this rule decides whether a file is clean, and it is exact at that job. For | ||
| # the full list while you fix one, the style guide's checklist already ends with | ||
| # `grep '—' <file>`. That division is deliberate; do not re-litigate it with | ||
| # `scope:` without re-running those three measurements. | ||
| extends: existence | ||
| message: "Do not use an em dash in prose. Match the mark to the job: parentheses for an aside, a colon for a definition or expansion, a period or semicolon for two clauses." | ||
| link: https://github.com/ConfigButler/gitops-reverser/blob/main/docs/style-guide.md#punctuation-no-em-dashes | ||
| level: error | ||
| nonword: true | ||
| tokens: | ||
| - '—' |
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.