[RFC] doc: modernize the contribution documentation and add an agent baseline - #15054
Draft
RonnyPfannschmidt wants to merge 6 commits into
Draft
RonnyPfannschmidt wants to merge 6 commits into
RonnyPfannschmidt wants to merge 6 commits into
Conversation
The setup instructions predated uv.lock and tox-uv: they installed pre-commit and tox with `pip install --user`, and pinned tox environments to interpreter versions (py312, py313) that the envlist has since moved past. `uv sync --group dev` was mentioned once, as an alternative to a hand-rolled venv. Lead with uv, keep the pip path for people who do not have it, and use `tox -e py` rather than naming an interpreter. Document `pre-commit run -a` as the check CI performs, and that pyright/pylint/pyupgrade are manual-stage hooks that run nowhere by default. Drop the two "follow PEP-8 for naming" asides: ruff-format and ruff-check decide this, and pre-commit applies them. Point the changelog steps at changelog/README.rst instead of listing the types a third and fourth time. Also record the trap that costs newcomers an afternoon: parts of the suite launch pytest in subprocesses with a scrubbed environment, so a pytest that is only visible through the user site-packages vanishes for those children. Add a short map of the tree, and link the backwards compatibility and deprecation policies from the section about implementing features. Co-Authored-By: Claude Opus 5 (1M context) via Claude Code <noreply@anthropic.com>
CONTRIBUTING.rst served four audiences at once. Everything from the merge/squash guidelines down -- backporting, stale issue handling, the wording for closing a stalled pull request -- is process the team performs, not steps a contributor takes, and it made up a third of the document a first-time contributor has to wade through. Move it to doc/en/maintenance.rst, along with the repository transfer runbook that sat inside the plugin submission section, and add the `test-me-*` branch trigger, which was documented only in the workflow file. CONTRIBUTING.rst keeps "Joining the Development Team", since that answers a contributor's question, and hands over to the new guide from there. Links from CONTRIBUTING.rst use explicit URLs rather than :ref:, because that file is also rendered by GitHub. Co-Authored-By: Claude Opus 5 (1M context) via Claude Code <noreply@anthropic.com>
The policy ran ninety lines of interleaved requirement and argument, so the part a contributor has to comply with could not be quoted without the part that explains our mood. Split it: "What we require" carries the four requirements, "Why this policy exists" carries the reasoning, including the paragraphs that moved down out of the requirements. Drop the name of a specific agentic tool from the rationale -- the problem is the mode of use, and naming a product dates the text. The pull request template listed `Co-authored-by` trailers as a checklist item, which reads as a requirement, while the policy calls them optional. Move it into the note above as the suggestion it is. Co-Authored-By: Claude Opus 5 (1M context) via Claude Code <noreply@anthropic.com>
The AI policy has so far existed only where a human reads it, which is not where it is needed: an agent pointed at this repository picks up no project context at all, invents its own idea of how to run the tests, and learns nothing about what we do and do not accept. AGENTS.md is the file the current crop of agent harnesses reads by convention; CLAUDE.md points at it so there is one text, not two that drift. It gives an agent the setup that actually works (tags, uv, why a user-site pytest breaks the subprocess tests), the layout, the conventions that reviewers would otherwise have to ask for, and -- first, because it is the part that matters -- the instruction to hand the work back to a human instead of opening a pull request. This is prose, and it stops only an agent that reads and honours it. That is deliberate for now: it removes the "nobody told me" case, which is most of what we actually see, without putting enforcement machinery in the repository before we know what it would need to catch. Co-Authored-By: Claude Opus 5 (1M context) via Claude Code <noreply@anthropic.com>
The section presented an "automatic method" and a "manual method" as two equally available options, which has not matched practice for a long time: patchback does the backports off the `backport x.x.x` label, and the cherry-pick by hand is what happens when it hits a conflict and gives up. Say that, and recast "who does the backporting" accordingly -- applying the label is part of merging, and the question of who does the work only arises once patchback has failed. Co-Authored-By: Claude Opus 5 (1M context) via Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) via Claude Code <noreply@anthropic.com>
psf-chronographer
Bot
added
the
bot:chronographer:provided
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.
Written by Claude Opus 5 (1M context) via Claude Code; I prompted it, it did the work, I read it.
CONTRIBUTING.rstwas 648 lines serving four audiences, with setup instructions older thanuv.lock. Six commits, each readable on its own.Tooling —
uvleads (uv sync --group dev,uv run pytest), pip path kept for those without it.tox -e pyinstead of pinnedpy312/py313. Addspre-commit run -aas the CI-equivalent check, and the trap that costs newcomers an afternoon: the suite spawns pytest subprocesses with a scrubbed environment, so a user-site pytest vanishes for them. Drops the two "follow PEP-8 for naming" asides — ruff decides that.Split by audience — merge/squash, backporting, stale handling and the close-a-stalled-PR wording are team process, not contributor steps. Moved to
doc/en/maintenance.rst, with the plugin-transfer runbook and thetest-me-*branch trigger (previously documented only intest.yml). "Joining the Development Team" stays put.Backporting — was written as a choice between an automatic and a manual method. Patchback does it off the label; the hand cherry-pick is the fallback when it conflicts. "Who does the backporting" recast to match.
AI policy — requirements and rationale were interleaved across ninety lines, so the rules couldn't be quoted without the mood. Now "What we require" / "Why this policy exists". Drops one tool's name from the rationale; it dates the text. PR template listed
Co-authored-byas a checklist item while the policy calls it optional — now a suggestion in both.AGENTS.md— the policy lived only where humans read it. This is what the harnesses read: setup, layout, conventions, and first, the instruction to hand work back to a human rather than open a PR.CLAUDE.mdpoints at it so there's one text, not two that drift.Deliberately not included: a
.claude/settings.jsondeny-list and aPreToolUsehook. Those have real teeth for one vendor, and are easy to add later — but the failure mode we actually see is well-meaning people running well-behaved harnesses that were never told anything. This removes the "nobody told me" case first.RFC and draft because the split and the shape of
AGENTS.mdare what's worth arguing about, ahead of wording.Docs build clean under
-W --keep-going;pre-commit run -agreen.