CONTRIBUTING.md carries every requirement; AGENTS.md points to it - #303
CONTRIBUTING.md carries every requirement; AGENTS.md points to it#303mcfnord wants to merge 2 commits into
Conversation
Twelve requirements exist today in AGENTS.md with no counterpart anywhere in CONTRIBUTING.md, so they bind only the contributors who read the agent file: real-time cycle-time rule, never trust values from remote clients, never hand-edit generated files, never reformat libs/, regenerate docs/JSON-RPC.md after an RPC change, the priority order, AI disclosure, shellcheck + shfmt, QT_VERSION_CHECK guards, filling in the PR template, no reformatting of untouched code, and saying so when something was not verified. The duplication has already drifted: AGENTS.md asks every contribution for test evidence, CONTRIBUTING.md asked it of AI contributions only. That sentence is now unconditional here. Wording is kept close to the AGENTS.md source so this reviews as a move, not as twelve new rules. Four posting expectations from docs/agents/COMMENTING.md move in the same way, as "Commenting and reviewing". Three more land here rather than in AGENTS.md, where an earlier draft of jamulussoftware#3912 had put them: wire compatibility (never renumber PROTMESSID_*, retired IDs stay reserved), the clang-format lists that have to move together, and the rule that a claim in a comment, a document or a commit message is a claim like any other. No requirement is added or strengthened beyond what one of those files already states. AGENTS.md and docs/agents/COMMENTING.md are reduced to pointers in the next commit; this one must land first so nothing points at a section that does not exist yet. CHANGELOG: SKIP
Every requirement AGENTS.md carried is now stated in CONTRIBUTING.md, so this file keeps only what is not a requirement - where things are, how to build, how to run - plus one link per rule. A second copy drifts, and the drift had already happened: this file demanded test evidence of every contribution while CONTRIBUTING.md asked it of AI contributions only. 651 -> 480 words. All 16 CONTRIBUTING.md anchors linked from here resolve against the file as of the previous commit. docs/agents/COMMENTING.md gets the same treatment and keeps the two lines that would be wrong to ask of a human contributor: leave the starting of discussions to humans, and honour a maintainer's stated preference about engagement. CHANGELOG: SKIP
| Only these are specific to an agent: | ||
|
|
||
| - Leave the starting of new discussions to humans. | ||
| - If a maintainer states how they want to be engaged, that is the rule for that person and that thread. |
There was a problem hiding this comment.
We aren't kings. Arguing against it is welcome as it could show up misconceptions...
There was a problem hiding this comment.
🤖 AI: The line has a history worth stating. It came in through the Posting section suggested on #3785 as "treat a maintainer's stated preference about engagement as the rule", two days after a maintainer asked on #3898 that the AI not post on that thread. The intent was narrow: an agent must not relitigate a request like that on the same thread. The wording overshot into deference, and moving it up to one of two headline agent rules made that visible. Once disagreement is welcome, the rule is no longer specific to agents, so the proposal is one bullet in CONTRIBUTING.md § Commenting and reviewing, addressed to everyone:
If someone states how they want to be engaged on a thread - for example, no AI-written replies - follow it while it stands. Disagreeing is welcome: say so once, with your reason; a preference can rest on a misunderstanding on either side.
docs/agents/COMMENTING.md then keeps a single agent-only line, leaving the start of new discussions to humans. The change goes into the upstream PR rather than into this one.
ann0see
left a comment
ann0see
left a comment
There was a problem hiding this comment.
I think it's worth opening this as PR after you reviewed it once without AI to the main repo. But wait a few days please.
2 participants
🤖 AI: This targets
updateContributing, so merging it folds the change into jamulussoftware#3910 — offered as commits rather than review prose, following the point made there: "CONTRIBUTING.md is the primary source of truth. AGENTS.md should just be the guidance to the truth." If it widens the PR more than wanted, closing this and taking it as a separate PR after jamulussoftware#3910 merges works the same; the commits are independent and either can be dropped.Twelve requirements currently exist only in AGENTS.md, with no counterpart in CONTRIBUTING.md: the real-time rule, never trusting values from remote clients, generated files and
libs/, JSON-RPC doc regeneration, the priority order, AI disclosure, shellcheck and shfmt,QT_VERSION_CHECKguards, the PR template, no reformatting of untouched code, no unrelated cleanup, and saying so when something was not verified. The drift this produces is already visible on the lines jamulussoftware#3910 edits: AGENTS.md line 33 asks every contribution for test evidence, CONTRIBUTING.md line 108 asks it of AI contributions only.Commit 1 moves all of them into CONTRIBUTING.md, wording kept close to the AGENTS.md source so it reviews as a move rather than as new policy. It also picks up the posting expectations from
docs/agents/COMMENTING.md, and makes the test-evidence sentence unconditional. The AI-disclosure sentence carries the obligation exactly as AGENTS.md states it today — whether it stays a requirement or becomes an encouragement (the two open suggestions on jamulussoftware#3910 differ) is left to this review.Commit 2 reduces AGENTS.md to orientation — where things are, how to build and run — plus one link per rule into CONTRIBUTING.md, 651 → 480 words;
docs/agents/COMMENTING.mdkeeps only what would be wrong to ask of a human contributor. The order is load-bearing: four of the sections AGENTS.md links to exist only after commit 1, so commit 2 must not land without it.CHANGELOG: SKIP
🤖 This message was written by AI and reviewed by @mcfnord.