ci: make formatting and spelling advisory on the document-only path

.github/workflows/format-documents.yml

@@ -0,0 +1,55 @@
+name: Format documents
+
+# Repairs formatting drift that reaches main through the advisory
+# document-only lint path (ADR 0011, amendment of 2026-10-30). Formats the
+# authored document paths with the repository Prettier configuration and
+# opens or refreshes a single pull request when anything changed.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'blog/**'
+      - 'adr/**'
+      - 'CODE_OF_CONDUCT.md'
+      - 'CONTENT-SECURITY.md'
+      - 'CONTRIBUTING.md'
+      - 'GOVERNANCE.md'
+      - 'MAINTAINERS.md'
+      - 'README.md'
+      - 'SECURITY.md'
+  schedule:
+    - cron: '27 4 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# Serialised on the branch this workflow force-pushes; see the note in
+# refresh-radar-reports.yml. Not cancelled, for the same reason.
+concurrency:
+  group: automation/format-documents
+  cancel-in-progress: false
+
+jobs:
+  format:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Check out main
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install dependencies
+        uses: ./.github/actions/setup-node-deps
+      - name: Format authored documents
+        run: npm run fix:format:documents
+      - name: Open or refresh the formatting pull request
+        uses: ./.github/actions/open-automation-pr
+        with:
+          branch: automation/format-documents
+          commit-message: 'chore: format documents'
+          title: 'chore: format documents'
+          body: |
+            Automated Prettier pass over the authored documents (docs/, blog/, adr/ and the root documents). A document-only pull request may merge with formatting findings left as advisory annotations; this pull request normalizes what landed.

.markdownlint.yaml

@@ -4,7 +4,8 @@
 # small set of inline HTML elements (figure/figcaption/a) for captions.
 default: true
 
-# Prose lines are not hard-wrapped in this repository.
+# Prose may be wrapped or unwrapped (Prettier runs with proseWrap: preserve
+# for Markdown), so line length is not enforced.
 MD013: false
 
 # Docusaurus doc/blog frontmatter provides the H1 via `title`, so pages may

AGENTS.md

@@ -80,8 +80,11 @@ takes the full path.
   in a file a PR does not touch is not a finding. See
   [`CONTRIBUTING.md`](CONTRIBUTING.md#mutation-testing).
 - **Lint**: the required "Lint repository" CI check runs on every PR. A
-  document-only PR lints just the changed files (formatting, spelling and
-  Markdown); every other PR runs `npm run check:format`,
+  document-only PR lints just the changed files: markdownlint blocks, while
+  Prettier and cspell findings are advisory annotations that do not fail the
+  check (ADR 0011 amendment); the "Format documents" workflow then opens a
+  `chore: format documents` PR to normalize any drift on `main`. Every other PR
+  runs `npm run check:format`,
   `npm run check:spelling`, `npm run check:markdown`,
   `npm run check:duplication`, `npm run check:lint` and `npm run check:unused`.
   `check:lint` runs ESLint (`eslint.config.mjs`) over `src/`, `scripts/`,

CONTRIBUTING.md

@@ -277,9 +277,17 @@ enough for a first contribution.
 Pull requests that change only recognized, human-maintained Markdown or MDX
 documents use focused CI: formatting, spelling, and Markdown checks run on the
 changed documents, document-contract tests run, and the production site is
-built. Generated or data-backed pages, code, configuration, assets, mixed
-changes, and unrecognized paths keep the full validation, lint, and browser
-suites. If CI cannot confidently classify a change, it uses the full path.
+built. On that path formatting and spelling are advisory: their findings appear
+as annotations on the pull request and in the job summary, with the fix to
+apply, but do not fail the check, so a page edited in the GitHub web editor can
+merge without hard-wrapped lines or a dictionary entry for a new proper noun.
+Markdown lint, the document-contract tests and the build still block. The
+"Format documents" workflow opens a single `chore: format documents` pull
+request whenever formatting drift reaches `main`. Generated or data-backed
+pages, code, configuration, assets, mixed changes, and unrecognized paths keep
+the full validation, lint, and browser suites, where formatting and spelling
+fail as before. If CI cannot confidently classify a change, it uses the full
+path.
 
 1. Fork the repository and create a branch from `main`.
 2. Make your change and run the relevant validation script.
@@ -300,9 +308,12 @@ suites. If CI cannot confidently classify a change, it uses the full path.
    `npm run check:spelling`, `npm run check:markdown`,
    `npm run check:duplication`, `npm run check:lint` and `npm run check:unused`.
    The "Lint repository" check runs these six on that path. Content-only PRs use
-   focused formatting, spelling and Markdown checks on changed documents. If a
-   full-path check fails:
-   - `check:format` — run `npm run fix:format` to auto-format.
+   focused formatting, spelling and Markdown checks on changed documents, with
+   formatting and spelling reported as advisory annotations rather than
+   failures. If a full-path check fails:
+   - `check:format` — run `npm run fix:format` to auto-format. Markdown prose
+     may be wrapped or unwrapped (`proseWrap: preserve`); Prettier only
+     normalizes structure such as lists, emphasis and tables.
    - `check:spelling` — add the flagged term to `.cspell.yml` if it's a
      legitimate project word, or fix the typo.
    - `check:markdown` — fix the reported issue, or add an inline disable comment

adr/0011-content-focused-validation-for-documentation.md

@@ -1,6 +1,11 @@
 # ADR 0011: Content-only pull requests use focused validation
 
 - **Status**: Accepted
+- **Status note**: Amended 2026-10-30: on the document-only path, formatting and
+  spelling are reported as advisory annotations instead of failing the check,
+  Markdown no longer requires hard-wrapped prose, and formatting drift on `main`
+  is repaired by an automated pull request; see
+  [Amendment: advisory formatting and spelling](#amendment-advisory-formatting-and-spelling-2026-10-30).
 - **Date**: 2026-10-29
 - **Related**:
   [ADR 0008](./0008-scope-agent-findings-to-user-observable-change.md),
@@ -118,3 +123,53 @@ queue must apply the same classification and safety rules.
   silently skip validation.
 - This decision changes which checks run by change type; it does not change test
   coverage requirements or any other frozen threshold.
+
+## Amendment: advisory formatting and spelling (2026-10-30)
+
+The focused path still failed the contributions it was meant to ease. A page
+edited in the GitHub web editor is never hard-wrapped at 80 columns, so the
+Prettier check (`proseWrap: always`) failed every such change, most recently
+[#2005](https://github.com/cncf/endusers/pull/2005), which a maintainer had to
+force-merge and repair in [#2008](https://github.com/cncf/endusers/pull/2008).
+Spelling failed on proper nouns that a new User Group page legitimately
+introduces. Neither failure is a defect an end user can observe, and both are
+mechanical to repair, so they should not stand between a contributor and a
+merge. The DCO is not a hurdle here: the repository requires sign-off on web
+commits, so the web editor adds the trailer itself.
+
+### What changes
+
+1. Markdown and MDX files use `proseWrap: preserve`. Prettier accepts prose
+   either wrapped or unwrapped and still normalizes everything else (lists,
+   emphasis, tables, blockquote continuation). Code files keep their settings.
+2. On the document-only path, Prettier and cspell are advisory. Their findings
+   are surfaced as GitHub workflow annotations on the changed lines and in the
+   step summary, with the one-line fix for each (`npm run fix:format`, or a
+   `cspell:ignore` comment for a genuine proper noun), and they do not fail the
+   "Lint repository" check. markdownlint, the document-contract suites and the
+   production build still block, because what they catch does render wrong.
+3. The full path is unchanged: every other change still fails on formatting and
+   spelling as before.
+4. Formatting drift that reaches `main` through the advisory path is repaired by
+   a `format-documents` workflow. It runs on every push to `main` that touches
+   an authored document and on a weekly schedule, formats the authored document
+   paths with the repository Prettier configuration (so `.prettierignore` still
+   protects `blog/`), and opens or refreshes a single `chore: format documents`
+   pull request through the existing `open-automation-pr` action when anything
+   changed. That pull request is itself document-only and merges through the
+   focused path.
+
+### Effects
+
+- A contributor editing a page in the web editor can merge with unwrapped prose
+  and an unlisted proper noun; the formatting is normalized shortly after by the
+  automation pull request, and the spelling warning stays visible to the
+  reviewer on the pull request.
+- `main` may carry unformatted prose for the minutes between a merge and the
+  repair pull request. `npm run check:format` on a fresh clone can therefore
+  fail until that pull request lands; `npm run fix:format` restores it.
+- Advisory does not mean unchecked: the annotations appear on the pull request
+  and a reviewer can still ask for the fix. The classifier, the blocking
+  contract suites and the production build remain the trust boundary.
+- No frozen threshold changes. This amendment narrows which focused-path
+  findings block; it does not alter coverage, mutation or clone gates.

docs/community/index.md

@@ -1,7 +1,6 @@
 ---
 title: Community
-description:
-  'The CNCF End User Community, TAB, governance, and community groups.'
+description: 'The CNCF End User Community, TAB, governance, and community groups.'
 sidebar_position: 1
 ---
 

docs/community/technical-advisory-board/governance.md

@@ -60,10 +60,8 @@ standards bodies, such as the [Internet Engineering Task Force (IETF)] and the
   optional.
 
 [RFC2119 keywords]: https://www.ietf.org/rfc/rfc2119.txt
-[Internet Engineering Task Force (IETF)]:
-  https://en.wikipedia.org/wiki/Internet_Engineering_Task_Force
-[Kubernetes project]:
-  https://github.com/kubernetes/community/blob/master/committee-steering/governance/sig-governance-requirements.md
+[Internet Engineering Task Force (IETF)]: https://en.wikipedia.org/wiki/Internet_Engineering_Task_Force
+[Kubernetes project]: https://github.com/kubernetes/community/blob/master/committee-steering/governance/sig-governance-requirements.md
 
 ## User Groups (UGs)
 
@@ -339,8 +337,7 @@ approval.
 TOC or TAB; the TCG organizers should reach out to the chairs of the TOC and TAB
 to discuss which group would be the most appropriate.
 
-[Community Groups README]:
-  https://github.com/cncf/communitygroups?tab=readme-ov-file#how-to-apply
+[Community Groups README]: https://github.com/cncf/communitygroups?tab=readme-ov-file#how-to-apply
 
 ### Roles, Terms, and Elections
 
@@ -403,7 +400,5 @@ Community Groups.
 
 {/* Common Links */}
 
-[Technical Leadership Principles]:
-  https://github.com/cncf/toc/blob/main/PRINCIPLES.md#technical-leadership-principles
-[Community Group Organizer Requirements]:
-  https://github.com/cncf/communitygroups/blob/main/organizers.md
+[Technical Leadership Principles]: https://github.com/cncf/toc/blob/main/PRINCIPLES.md#technical-leadership-principles
+[Community Group Organizer Requirements]: https://github.com/cncf/communitygroups/blob/main/organizers.md

package.json

@@ -56,6 +56,7 @@
     "validate:members": "node scripts/validate-members.mjs",
     "docusaurus": "docusaurus",
     "fix:format": "npm run _check:format -- --write",
+    "fix:format:documents": "npx prettier --write docs blog adr CODE_OF_CONDUCT.md CONTENT-SECURITY.md CONTRIBUTING.md GOVERNANCE.md MAINTAINERS.md README.md SECURITY.md",
     "fix": "npm run seq -- $(npm -s run _list:fix:*)",
     "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ",
     "serve": "npm run docus:serve",
@@ -147,7 +148,18 @@
   "spelling": "cSpell:ignore ACMR docus HTMLTEST loglevel pkgs -",
   "prettier": {
     "proseWrap": "always",
-    "singleQuote": true
+    "singleQuote": true,
+    "overrides": [
+      {
+        "files": [
+          "*.md",
+          "*.mdx"
+        ],
+        "options": {
+          "proseWrap": "preserve"
+        }
+      }
+    ]
   },
   "homepage": "https://endusers.cncf.io/",
   "overrides": {