Document agent pitfalls in AGENTS.md: test coverage, fork-only pushes, doc spell check#1345
Merged
Merged
Conversation
Adds a section to AGENTS.md explaining that coverage in this repo is collected over `source = .`, so unreachable lines in tests (defensive `raise` inside a monkeypatched stub, one-sided cleanup branches, backend-specific arms the matrix never enters) show up the same as dead code in `multidict/`. Calls out the common shapes and points to the patterns that keep tests fully covered (deterministic fixtures, unconditional restores, parametrize over both backends, `monkeypatch` auto-revert).
- Adds "Push from a fork, not to upstream" as PR rule aio-libs#3, with the commands and a note on the `GH013` error you get for trying to push a feature branch to `aio-libs/multidict`. - Folds in the docs spell check section from aio-libs#1344 as PR rule aio-libs#7, so `make doc-spelling` is documented as the pre-push gate; adds `codecov` to `docs/spelling_wordlist.txt` for the new fragment. - Renumbers PR rules 3-6 to 4-8, and extends the news fragments to cover all three additions.
psf-chronographer
Bot
added
the
bot:chronographer:provided
Per AGENTS.md, when both an issue and a PR number are in play the issue-numbered fragment is the real file and the PR-numbered sibling is a symlink, so both cross-references resolve in towncrier and on GitHub. - `CHANGES/1343.contrib.rst` stays as the real fragment for the spelling-check section (tied to issue aio-libs#1343). - `CHANGES/1345.contrib.rst` becomes a symlink to it. - The coverage + fork content moves to `1345.contrib.1.rst`, using the towncrier sequence-number convention since the unsuffixed PR slot is now taken by the symlink.
Merged
5 tasks
Per maintainer feedback, three contrib fragments for one docs-only PR is noise. Folds spelling check, test coverage, and fork-only push into one entry in `CHANGES/1343.contrib.rst` and keeps `CHANGES/1345.contrib.rst` as the symlink so the PR number still resolves. Removes the `1345.contrib.1.rst` file that the earlier split introduced.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
What do these changes do?
Three AGENTS.md additions for failure modes agents keep hitting:
covered section under Tests, explaining that coverage runs
over
source = .(so test files are measured), and listingthe shapes agents commonly leave uncovered: defensive
raiseinside a monkeypatched stub, one-sided cleanup branches,
backend-specific arms the C-ext/pure-Python matrix never
enters. Mirrors docs: spell out in AGENTS.md that the coverage gate covers tests yarl#1689.
to upstream, documenting that branch creation on
aio-libs/multidictis restricted (returnsGH013: Cannot create ref due to creations being restricted) and that allPRs must come from a fork, with the standard
git remote addgh pr createrecipe.Document docs spell check in AGENTS.md, add 'unparseable' #1344 as PR rule Fix set operations #7, so
make doc-spellingis documented asthe pre-push gate. Adds
codecovtodocs/spelling_wordlist.txtfor the new fragment.Renumbers the surrounding PR rules and extends Things-not-to-do
with matching bullets.
Are there changes in behavior for the user?
No. Docs-only change to the agent-facing contributor notes.
Is it a substantial burden for the maintainers to support this?
No. All three rules are already enforced (by the coverage
report, by the branch-creation restriction, and by the docs
spelling step in CI); this just writes them down where agents
will read them.
Related issue number
Folds in #1344 (which can be closed in favour of this PR) and
resolves the AGENTS.md side of #1343. References
aio-libs/yarl#1689 as the canonical example for the coverage
section.
Checklist
Drafted with Claude Code (claude-opus-4-7, 1M context); reviewed by @bdraco.
Agent run details (optional, for reviewers)
Docs-only change, no test suite to run. Verification:
passed (only the `:user:` role check applied to the changed
files; ruff/clang/mypy had no targets).
`1345.contrib.rst` fragment; added it to
`docs/spelling_wordlist.txt`, after which the only remaining
warnings are 5 pre-existing words (`parametrization`,
`postfix`, `instantiation`, `init`, `parametrized`) in
the released `CHANGES.rst` from 6.7.1, unrelated to this PR.