From 7c7765f970f04efda851cb1b2a639769728693b5 Mon Sep 17 00:00:00 2001 From: Paddy Byers Date: Sat, 26 Sep 2026 08:33:06 +0100 Subject: [PATCH] best-practices: add expanded policy for AI interactions with PRs --- best-practices/pull-requests.md | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/best-practices/pull-requests.md b/best-practices/pull-requests.md index 090b100..9120726 100644 --- a/best-practices/pull-requests.md +++ b/best-practices/pull-requests.md @@ -16,7 +16,8 @@ The policy here is the set of rules we use with that aim. Although there is a lo - the approval of a maintainer via a PR approval is a necessary condition for new code to be merged; - PR reviews should be conducted in a timely way so as not to impede the authors' work; -- PR feedback must be courteous, objective and clear, and should include guidance, suggestions and other constructive feeback where this helps to move everyone's work forward. +- PR feedback must be courteous, objective and clear, and should include guidance, suggestions and other constructive feeback where this helps to move everyone's work forward; +- AI authorship of, and interaction with, PRs does not dilute the human author's responsibility for a PR and adherence to these principles. AI interactions with a PR must not impede a human's ability to do this. ## Applicability @@ -108,14 +109,38 @@ After a PR is merged, the branch should be deleted. ## Use of coding agents and AI review bots -Code generated by coding agents is now the default way that much of our code is produced. Coding agents can raise PRs, so long as they follow the guidance in this document and in [commits.md](commits.md). +Code generated by coding agents is now the default way that much of our code is produced. Coding agents can raise PRs, so long as they follow the guidance in this document and in [commits.md](commits.md). The core principles that must be maintained when introducing AI-based workflows are as follows. -Raising a PR in non-draft state is an indication by the author that it is ready for independent review; this is just as true for AI-generated PRs as for any other. Therefore, if the author wishes to trigger an AI-assisted PR review as part of their own pre-submission process, this should be done with the PR in draft state. Once the author is satisfied that the PR is ready for independent review - which requires any prior review feedback to be resolved - it should be updated to a full (non-draft) PR. +- PRs continue to be owned by humans, and a human owns what their agents say on it. Human authors are responsible for appropriateness and validity of PRs, and compliance of their agents with this policy. + +- Codeowners own the workflow. Whether and how a repo uses auto-approval, bot-assisted review, draft-first workflows, or other automation is a decision for that repo's maintainers, provided the automation meets the principles here. Different repos have different needs and are not required to converge on identical tooling. + +PRs are a vehicle for humans to understand, discuss and approve changes. This means that: -By default, AI review comments and the resulting discussion and resolution should remain in the PR for future reference, unless the author believes that they constitute extraneous noise. In that case, consider re-raising a clean PR without the noise. It is the author's responsibility to ensure that the PR is in a fit state to review, and that extends to the PR discussion as well as to the code and history. +- PR conversations are for humans. A comment on a PR should mean a person said something to you. The conversation thread should consist of human contributions, plus only those bot contributions that specifically require human attention and action. + +- You can always tell a human from an agent. Automated accounts post as themselves, not as a human. Where an agent posts on a PR at a human's explicit direction (eg "reply to this comment"), the post must carry a clear indication that it was agent-authored (eg a footer), since the wording may not be exactly what the human would have written themselves. + +Raising a PR in non-draft state is an indication by the author that it is ready for independent review; this is just as true for AI-generated PRs as for any other. Therefore, if the author wishes to trigger an AI-assisted PR review as part of their own pre-submission process, this should be done with the PR in draft state. Once the author is satisfied that the PR is ready for independent review - which requires any prior review feedback to be resolved - it should be updated to a full (non-draft) PR. For the avoidance of doubt: as PR author you are expected to present a PR that is fit for peer, human review. A repo may have AI triage and/or review configured to take place post-submission that preempt independent human review, but the principle remains that it must be ready for human review. If an author presents a PR that looks like it was written by a coding agent and they have not reviewed it themselves, then the reviewer is expected to reject the PR. It is not acceptable to expect other humans to review code you are presenting that you have not reviewed yourself. +## Use of PR features + +AI interactions should be directed to the appropriate surface or feature in Github. This avoids polluting the comment thread, so it doesn't compete for attention with human discussion, but also means that the AI input is more structured and more explicitly linked to its purpose and the context that was used to generate it. + +| AI output | Appropriate surface | +|---|---| +| Preview / deploy URLs | A deployment with `environment_url` (shows as a "View deployment" button and on the deployments page) | +| Reports (coverage, size, scans) | Check run output / job summary | +| Per-line findings | Check annotations (inline in Files changed) | +| Pass/fail gates | Status checks (merge box) | +| PR status or metadata (stale, size, etc.) | Labels | + +Within the conversation thread itself a bot should only post a conversation comment to ask a human to do something, and should say so plainly (eg an indication that a human review is required after triage). It should not post comments that just narrate or confirm what already happened (verdicts, "review complete" comments, walkthroughs duplicating a check or deployment). Any bot comments should always be kept to the point. + +By default, AI outputs, review feedback and the resulting discussion and resolution should remain in the PR for future reference, unless the author believes that they constitute extraneous noise. In that case, consider re-raising a clean PR without the noise. It is the author's responsibility to ensure that the PR is in a fit state for humans to review, and that extends to the PR discussion as well as to the code and history. + ## Etiquette ### Reviewer Count