docs(ci): scope vale to what it can honestly judge, 308 findings to 17
vale was emitting 308 findings that nobody acted on, because the job is allow_failure: true. A linter whose output is permanently ignored is not help, it is noise with a CI cost. This gets the count down to a residual that is genuinely zero real defects, and states plainly what remains.
308 findings -> 17. Zero of the 17 are real prose defects.
The largest single cause was a rule that should not have been running
gitlab_docs.InternalLinkFormat accounted for 107 of the 308, and every one was an ordinary working relative link such as [README.md](./README.md).
The vale template's mode input documents project mode as disabling InternalLink* rules. It does not. Reproduced locally with the pinned vale 3.14.1, the same styles archive, the same .vale.ini shape project mode generates, and the same paths and disable_rules from this file: project mode disables FrontMatter, InternalLinkExtension, InternalLinksCode, RelativeLinks and Spelling. InternalLinkFormat is never in that list.
The rule enforces docs.gitlab.com's link-path convention, and this repo does not publish there. Disabled here as the narrow fix. The real fix belongs upstream in the pipeline/vale template, either by adding it to the project-mode disables or by correcting the description; that is a follow-up MR on the catalog.
CHANGELOG.md leaves the paths glob
21 findings. A changelog is a dated record of what shipped, so rewording an entry to satisfy a linter edits history. Without this, every future release permanently fails the gate on its own new entry.
templates/*/CHANGELOG.md stays in scope. Those are standing explanatory boilerplate about the changelog convention, not dated entries, and their findings were fixed normally.
Two rules de-tuned, each proven rather than assumed
| rule | why |
|---|---|
gitlab_base.Offerings |
Wants GitLab Self-Managed capitalisation. Every instance is the house term "self-managed and airgap awareness", describing the reader's environment, not GitLab's product tier. Capitalising would misassert what the sentence is about. Confirmed consistent across AGENTS.md, design/DESIGN-LANGUAGE.md and every template. |
gitlab_base.OxfordComma |
Rule limitation, verified by isolating each trigger sentence into a test file: it fires identically whether the comma is present or absent. Its own documentation admits it "will catch overly complex sentence structures with lots of commas". None of the flagged sentences actually lacks a comma. |
Prose actually fixed
252 findings across 40 files: codeblock fences, term substitutions, future tense, possessives, unclear antecedents, bold-for-emphasis. The byte-identical groups (SECURITY.md x5, CONTRIBUTING.md x5) were edited identically and verified by checksum before and after, so validate-templates stays green.
One real finding in AGENTS.md: future tense.
The residual 17, itemised
| category | count | why not fixed |
|---|---|---|
docs.gitlab.com as visible link text |
6 | substituting produces documentation.gitlab.com, misrepresenting a real URL |
docs as this repo's starter-kind name |
7 | parallel to lab and paper; vale has no swap for lab, so renaming only docs breaks the three-way naming |
config in conformance-config |
2 | the standard's own slug, matching its directory; conformance-configuration resolves to nothing |
| "in one click" | 1 | idiom; the literal swap produces "in one select" |
FutureTense |
1 | fixed |
allow_failure stays true, deliberately, and here is the decision it leaves open
I am not flipping the gate in this MR. With 17 findings remaining it would simply make CI red, and a red-by-design check is the thing we are removing.
Reaching a true zero needs one of two choices, and it is a judgement about prose noise rather than a mechanical fix:
- 16 inline
<!-- vale gitlab_base.SubstitutionWarning = NO -->markers at the specific sites. Precise, documents each exception where it lives, and adds roughly 30 comment lines to prose files. - Accept the 17 as a tracked residual and leave
allow_failure: true, on the grounds that 17 itemised known-good findings is a different thing from 308 undifferentiated ones.
Option 1 is the only one that lets vale become a real gate. I would rather that call be made deliberately than tacked onto the end of this change.
Verification
just validate: PASS, including the byte-identicalSECURITY.md/CONTRIBUTING.md/CODEOWNERSgateglab ci lint: valid- vale re-run against the exact
pathsanddisable_rulesin this file: 17 findings, all itemised above git diff --stat: 41 files, prose only plus the one.gitlab-ci.ymlblock
One note for the record: the local reproduction found 308 where CI reported 313. The styles archive is fetched live from gitlab-org/gitlab@master, so the ruleset drifts day to day. That floating dependency is why an untouched branch can go red, and it is worth pinning separately.