From 1c8eade6a808754ac782c5ce4dbe9c6f8225aa99 Mon Sep 17 00:00:00 2001 From: aiolibsbot Date: Sun, 17 May 2026 02:39:08 +0000 Subject: [PATCH 1/2] Document docs spell check in AGENTS.md and accept 'unparseable' --- AGENTS.md | 23 +++++++++++++++++++++++ CHANGES/1343.contrib.rst | 5 +++++ docs/spelling_wordlist.txt | 1 + 3 files changed, 29 insertions(+) create mode 100644 CHANGES/1343.contrib.rst diff --git a/AGENTS.md b/AGENTS.md index 400d3c4fe..baff07681 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -266,6 +266,29 @@ the style here. Match that style; do not force `feat:` / `fix:` prefixes onto every commit. +### 7. Run the docs spell check before pushing + +CI builds the docs with `sphinxcontrib.spelling` and treats any +unknown word as a hard failure. The spell checker reads every +`CHANGES/*.rst` fragment as part of the build, so a technical word +in your news fragment (`unparseable`, `parametrization`, `repr`, +and so on) that is not in +[`docs/spelling_wordlist.txt`](docs/spelling_wordlist.txt) +will fail `make doc-spelling` and burn a CI run before a human +even sees the PR. + +Before pushing: + +```bash +make doc-spelling +``` + +If it flags a word you actually meant to use, add it to +`docs/spelling_wordlist.txt` (one word per line, roughly +alphabetical) in the same commit as the fragment. If it flags +a typo, fix the typo. Do not paper over real misspellings by +adding them to the wordlist. + ## Dual-backend discipline This is the single biggest source of broken multidict PRs from agents. diff --git a/CHANGES/1343.contrib.rst b/CHANGES/1343.contrib.rst new file mode 100644 index 000000000..4faebc7b9 --- /dev/null +++ b/CHANGES/1343.contrib.rst @@ -0,0 +1,5 @@ +Documented the docs spell check in ``AGENTS.md`` and added the +``unparseable`` entry to ``docs/spelling_wordlist.txt`` so LLM +contributors run ``make doc-spelling`` before pushing rather than +burning a CI run on a missing dictionary entry +-- by :user:`aiolibsbot`. diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 1b25f5bdc..00a51748a 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -103,6 +103,7 @@ toolset tuples un uncompiled +unparseable upstr url urlencoded From 2b5a1898a8a4e80fd0b9e2f8f41b8929b1475049 Mon Sep 17 00:00:00 2001 From: aiolibsbot Date: Sun, 17 May 2026 03:55:55 +0000 Subject: [PATCH 2/2] rebase: apply review feedback on #1344 --- CHANGES/1343.contrib.rst | 3 +-- docs/spelling_wordlist.txt | 1 - 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/CHANGES/1343.contrib.rst b/CHANGES/1343.contrib.rst index 4faebc7b9..321b7f1bd 100644 --- a/CHANGES/1343.contrib.rst +++ b/CHANGES/1343.contrib.rst @@ -1,5 +1,4 @@ -Documented the docs spell check in ``AGENTS.md`` and added the -``unparseable`` entry to ``docs/spelling_wordlist.txt`` so LLM +Documented the docs spell check in ``AGENTS.md`` so LLM contributors run ``make doc-spelling`` before pushing rather than burning a CI run on a missing dictionary entry -- by :user:`aiolibsbot`. diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 00a51748a..1b25f5bdc 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -103,7 +103,6 @@ toolset tuples un uncompiled -unparseable upstr url urlencoded