TL;DR: Added a markdownlint check to 33 repos at once — and woke up to ~100 CI failure emails about code I didn't write. The fix: lint only the files changed in the PR, never the whole backlog. Grandfather existing violations; enforce the standard on new changes.
I maintain a GitHub org with 33 open-source repos . Last month I decided to do the responsible thing: add a default markdownlint check to every repo so our docs stay consistent.
By the next morning I had ~100 failure emails in my inbox. Here's what went wrong — and the rollout playbook I'd use instead.
What happened
The lint workflow ran against every markdown file in each repo — READMEs, changelogs, and contributor guides written years ago by people who had never heard of markdownlint. Upstream markdown, as it turns out, has never passed a linter in its life.…