docs: restructure contribution guidelines around authorship vs composition

[d-v-b]

Preface

I drafted some changes to our contribution policy with the goal of producing something that would cover AI contributions as a logical consequence of some more basic rules about humans and tools. Then I had claude expand on that draft, after doing a survey of the contribution policies of a lot of different open source projects. My personal goals are:

• ensuring that we can safely use powerful tools like AI
• ensuring that good actors can easily follow project rules
• ensuring that reviewer / contributor time is well spent.

I think the end result is pretty good. Our new guidelines distinguish accountability from authorship: only a human can be accountable, but tools can be authors. The guidelines clarify that machine-written text is unwelcome in review comments, but generally acceptable when clearly annotated as machine-written text, and when the accountable human has demonstrated ownership over it.

Summary

🤖 AI-generated text below, from Claude Code (claude-opus-4.8). Not yet reviewed by a human. 🤖

This follows from the discussion on zarr-developers#4132, where @maxrjones objected that the PR description was not human-written and that the change was out of scope, and where we converged on a narrower rule than the one the contributing guide then carried. Rather than patch that rule, this reorganizes the guidelines around the distinction the discussion surfaced.

The framework. Two different things are true of any contribution: someone is accountable for it, and someone composed it. Accountability can never be delegated to a tool. Composition can, if disclosed. Every rule now follows from that split, which is why the separate ## AI-assisted contributions section is gone — its rules are consequences of the general guidelines, which apply equally to contributors, core developers, and agents. There is no core-developer carve-out.

What changes in substance. The guide previously said "do not paste AI-generated text as comments or review responses." Labeled machine-composed text is now permitted, subject to three limits:

• A pull request opens with a sentence the author wrote. This is @maxrjones' minimum bar, and the part a tool cannot produce without the human having thought about the change.
• Review responses must be in the author's own words. A reviewer asking a question is asking you.
• Endorsing machine-composed text means having trimmed it, not merely read it. Reading padding does not spare the reviewer from it.

The guide also explains why Dependabot is exempt from the human-sentence rule and an agent is not: a bot's identity fully supplies its motivation, an agent's does not.

What else it adds. A Write commit messages for the reader section, which is what @maxrjones said he cared most about and which the guide did not mention at all; the Assisted-by: trailer, noting that it certifies nothing here since this project has no DCO; and a statement that an agent should not open a pull request nobody asked for.

Relationship to zarr-developers#4041

This branch merges @maxrjones' docs/agents (zarr-developers#4041) wholesale, preserving his eight commits and authorship. Either zarr-developers#4041 lands first and this rebases, or this supersedes it — needs a decision, and it is why the PR is a draft.

Merging the two exposed a contradiction. His AGENTS.md opened by pointing at "docs/contributing.md, especially the AI-assisted contributions section" — the section this PR deletes — and restated the rule this PR changes ("PR descriptions / review responses must be in the human's own words"). Landed independently, the repo would have shipped an agent-facing file citing a nonexistent section and asserting the opposite of the policy. That paragraph now points at ## Contribution guidelines and carries only the short imperative rules that bind an agent directly. The rest of his file — pure mechanics — is untouched, which is the shape the evidence supports.

Where this sits relative to other projects

I surveyed ~25 projects' AI policies, verifying every quote against a primary source. Full write-up: https://gist.github.com/d-v-b/d56c653d52b5acca7ebc37ba0534ded6

Our position on machine-composed PR prose is a minority one, deliberately. NumPy, SciPy, scikit-learn, and xarray all ban it outright; xarray's wording is what our old text was adapted from. CPython requires no disclosure at all, and Fedora actively encourages AI prose for contributors writing in a second language. Expect this line to be argued about. The strongest defense of it is that a ban on machine-composed prose is really a proxy for effort — it catches the contributor who pasted an unread summary — and that a label recording whether a human read and cut the text measures that directly, instead of by inference. The honest cost: a ban binds bad-faith contributors and an attestation does not. That trade is worth making for a project whose contributors are few and repeat, and would not be for one drowning in anonymous drive-bys.

Three findings shaped the draft:

• The label records whether a human read the text, not just which tool composed it — two variants, after apache/airflow's AGENTS.md (Drafted-by: … (no human review before posting) vs … reviewed by @handle before posting). Provenance alone tells a reviewer little; review state tells them where to look.
• Endorsing text means editing it, after ghostty's AI_POLICY.md — "reviewed and edited by a human… AI is very good at being overly verbose and including noise that distracts from the main point." Ghostty also supplies the framing now opening Attribute your sources: posting unread text at the boundary where a person meets your work shifts the burden of validating it onto them, which is a discourtesy rather than a procedural violation. Not adopted from Ghostty: its maintainer exemption (contrary to what this branch exists to settle) and its public denouncement list (calibrated for a flood of drive-bys we do not have).
• The Assisted-by: trailer follows the Linux kernel, which mandates it and forbids AI Signed-off-by. Kubernetes bans that exact trailer, because AI cannot sign a CLA. Both reason from a signing instrument; zarr-python has neither a DCO nor a CLA, so ours is attribution and nothing more. The guide says so.

Policy prose belongs in contributing.md, not AGENTS.md. arXiv:2601.20404 (ICSE'26) found agents obey direct mechanical instructions but are unreliable on judgment calls, and that LLM-generated context files made outcomes worse; SciPy's maintainers reached the same conclusion and kept theirs to non-inferable mechanics. So AGENTS.md points at the contributing guide as authoritative and adds only short imperatives, as Airflow and pandas do. The real enforcement is the PR template checkbox.

Verification

• tests/test_docs.py — 57 passed, 2 skipped (the usual cupy/GPU and nonexistent-module skips)
• mkdocs build --strict — clean
• prek — clean (codespell, trailing-whitespace, mypy, sp-repo-review)
• Rendered site inspected: both label variants render inside code blocks, no dangling in-page anchors, and the PR template's #contribution-guidelines target resolves

Along the way this picked up zarr-developers#4132's own corrections to contributing.md (site/ build dir, serve URL, zarr.__version__ is an attribute not a property), which the branch predated and would otherwise have reverted.

Open questions

• docs: add AGENTS.md for AI-assisted development zarr-developers/zarr-python#4041: supersede, or rebase after it lands?
• Disclosure: the guide requires labeling (mark the block, name the tool, say if you read it) but not a blanket "did you use AI at all" declaration. NumPy rejects PRs lacking one; Ghostty requires one; Astropy deliberately requires none. This sits with Astropy, now stated on purpose rather than by omission. Reasonable to reverse.
• changes/4140.doc.md is named for a guessed PR number. Rename if this lands as something else.

TODO

• Add unit tests and/or doctests in docstrings — n/a, docs only
• Add docstrings and API docs for any new/modified user-facing classes and functions — n/a
• New/modified features documented in docs/user-guide/*.md — n/a
• Changes documented as a new file in changes/
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

[d-v-b]

@maxrjones i'd appreciate your eyes when you have time. this PR brings in your commits that add AGENTS.md etc and apply changes to our contribution policy on top of them. If you are OK with that process (a thumbs-up indication is enough), then I will move this as a PR against zarr-python itself, and we can hash out content-based discussions there.