Commit 4e46efe1a59 for woocommerce
commit 4e46efe1a59dcc87537e59f843187d1eddd23a9b
Author: Rafael Meneses <meneses.tio@gmail.com>
Date: Wed Sep 2 14:55:09 2026 -0300
Document when PRs need an independent human review (#68201)
* docs(contributing): document PR review requirements
Required approvals for trunk PRs were recently switched off and then
re-enabled after internal discussion. The outcome of that discussion
was an agreement that there is room for bypassing the approval
requirement on low-risk changes, but the exceptions were never written
down - the allowance existed only as tribal knowledge, so each author
had to guess when bypassing was acceptable and when an independent
human review was non-negotiable.
Add a "Review requirements" section to the PR impact assessment doc,
keying both rules off the High-Impact definitions the doc already
maintains: clearly low-impact changes may be merged without a formal
approval by those able to do so, while anything on the High-Impact
list always needs an independent human review. The section also makes
explicit that neither an AI review nor the author's own review of
AI-generated code counts as independent review - the author and their
agent are a single workflow - and that community PRs always require
an approval.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LJG8VKYsH9ZwoJv1BjU98t
* docs(contributing): link review requirements from contributor entry points
The new review requirements section only helps if authors find it at
PR time, not after a merge is questioned. Nothing pointed to it from
the places where PRs actually get written and submitted.
Surface it at both entry points: AGENTS.md gets a short summary plus
two agent-facing rules (never present an AI review as satisfying the
human review requirement, and always recommend an independent human
review for High-Impact PRs), and the PR template's Submission Review
Guidelines gain a line confirming the author assessed impact and
followed the applicable review requirements.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LJG8VKYsH9ZwoJv1BjU98t
* Update docs/contribution/contributing/deciding-pr-high-impact.md
Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>
* Update docs/contribution/contributing/deciding-pr-high-impact.md
Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>
* Update docs/contribution/contributing/deciding-pr-high-impact.md
Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>
* Update AGENTS.md
Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>
* docs(contributing): move review categories into High-Impact list
The review-requirements section named privacy, data integrity, backward
compatibility, and performance-sensitive paths as always requiring an
independent human review, but the High-Impact list above did not mention
them. Two lists describing the same risk drift apart.
Add the missing categories to the High-Impact list and reduce the
review-requirements sentence to a pure reference to that list.
* docs(contributing): cross-link community and review requirement docs
The community PR approval rule and the community contributions process
described each other without linking. The process doc also never stated
that a human approval is required to merge.
Link the community PR rule to the process doc, and point the process
doc's approval step back at the review requirements section.
* docs: link Automated Code Reviews to Review Requirements in AGENTS.md
The Automated Code Reviews section could be read as a substitute for
the review requirement. Point it at the Review Requirements section to
make explicit that automated reviews complement, never satisfy, the
human review requirement.
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index f3c815389f6..c7e88d17b41 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -3,6 +3,7 @@
- I have followed the [WooCommerce Contributing Guidelines](https://github.com/woocommerce/woocommerce/blob/trunk/.github/CONTRIBUTING.md) and the [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/).
- I have checked to ensure there aren't other open [Pull Requests](https://github.com/woocommerce/woocommerce/pulls) for the same update/change.
- I have reviewed my code for [security best practices](https://developer.wordpress.org/apis/security/).
+- I have assessed the impact of this change and followed the applicable [review requirements](https://github.com/woocommerce/woocommerce/blob/trunk/docs/contribution/contributing/deciding-pr-high-impact.md#review-requirements).
- Following the above guidelines will result in quick merges and clear and detailed feedback when appropriate.
<!-- You can erase any parts of this template not applicable to your Pull Request. -->
diff --git a/AGENTS.md b/AGENTS.md
index 547d0aa5ccd..5a7e8f505c2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -144,6 +144,15 @@ When creating PRs, **always use the template** from `.github/PULL_REQUEST_TEMPLA
For bug fixes, always reference the PR that introduced the bug using: `Bug introduced in PR #XXXXX.`
+### Review Requirements
+
+PRs against `trunk` require an approving review from a human by default. `docs/contribution/contributing/deciding-pr-high-impact.md` defines when that requirement may be bypassed (clearly low-impact changes: docs, typos, tests, tooling outside the release package) and when an independent human review is always required (anything on the High-Impact list, plus security, privacy, data integrity, backward compatibility, and performance-sensitive paths).
+
+Two rules matter for agents:
+
+- Never present an AI review, whether your own or another agent's, as satisfying the human review requirement. The author and their agents are a single workflow, not independent reviewers.
+- When a PR qualifies as High-Impact, say so and recommend requesting an independent human review; never suggest merging it without one.
+
## Testing Environment
- PHP tests run in Docker via `wp-env`
@@ -300,6 +309,8 @@ This is part of the WooCommerce monorepo:
For code review standards and critical violations to flag, use the **`woocommerce-code-review` skill**.
+Automated reviews complement the [Review Requirements](#review-requirements); they never satisfy the human review requirement.
+
## Notes for AI Agents
- This doc provides context; skills provide procedures
diff --git a/docs/contribution/contributing/community-contributions.md b/docs/contribution/contributing/community-contributions.md
index cec6e1ffb47..8d3ae53260f 100644
--- a/docs/contribution/contributing/community-contributions.md
+++ b/docs/contribution/contributing/community-contributions.md
@@ -38,7 +38,7 @@ After you submit a PR that meets these requirements:
1. A maintainer will triage your PR
2. You may receive additional feedback or change requests
-3. Once approved, your PR will be merged into an upcoming release
+3. Once approved by a maintainer (see [review requirements](/docs/contribution/contributing/deciding-pr-high-impact#review-requirements)), your PR will be merged into an upcoming release
If your PR needs changes, we'll add a `needs: author feedback` label. Please respond to feedback promptly to keep your contribution moving forward, as stale PRs with that label are automatically closed after a period of time.
diff --git a/docs/contribution/contributing/deciding-pr-high-impact.md b/docs/contribution/contributing/deciding-pr-high-impact.md
index ec1cd3ffc22..ca437796ec2 100644
--- a/docs/contribution/contributing/deciding-pr-high-impact.md
+++ b/docs/contribution/contributing/deciding-pr-high-impact.md
@@ -16,9 +16,12 @@ On this page, we will share some guidelines to help you assess the impact degree
- Modifies **critical functionality** that shoppers or merchants rely on to run a store.
- It fixes a **high-priority bug** (this includes Blocks fix releases core version bumps).
- It contains a **security fix**.
+- Changes affecting **privacy** (how personal or store data is collected, stored, or shared).
- Updates **SQL queries**.
- Touches any of the **$_REQUEST** family of variables.
-- Any kind of **data migration/update**.
+- Any kind of **data migration/update**, or other changes affecting **data integrity**.
+- Changes affecting **backward compatibility** (public APIs, hook signatures or timing, templates, or anything third-party code consumes).
+- Changes to **performance-sensitive paths**.
- Changes to **emails** sent from WooCommerce.
- Changes to WooCommerce **hooks/actions/filters**.
- Changes to **REST API endpoints**.
@@ -37,3 +40,26 @@ On this page, we will share some guidelines to help you assess the impact degree
## My PR is High-Impact. What's next?
If your PR is High-Impact, be sure to label it with `impact: high` and the WooCommerce Core team will keep special considerations for testing it.
+
+## Review requirements
+
+Pull requests against `trunk` require an approving review before merge. That is the default for every change, because an independent reviewer brings experience, product knowledge, and assumptions that the author does not have. AI tooling working from the author's context does not add that independence.
+
+The impact assessment above is also the reference for when that requirement can be relaxed and when it must not be.
+
+### When a PR may be merged without a formal approval
+
+Contributors with permission to bypass the review requirement may use their judgment to merge a PR without a formal approval when it clearly fits the "should not mark as High-Impact" list above: documentation, changelog, or typo changes; updates to automated tests; and tooling or infrastructure changes not shipped in the release package.
+
+Bypassing the requirement is an exception for low-risk changes, not an alternative default. If you are unsure whether your change qualifies, request a review from a human.
+
+### When an independent human review is always required
+
+A PR matching anything in the High-Impact list above must receive an independent human review before merge, no matter who (or what) authored it.
+
+Two things do not count as an independent human review:
+
+- **The author's own review of AI-generated code.** The author drives the agent, provides its context, and shapes its solution. The author and the agent are a single workflow, not two reviewers. A single workflow can produce a convincing implementation of the wrong approach and not notice.
+- **An AI review, automated or requested by anyone.** AI reviews are encouraged as an additional safety net, but they complement an independent human review rather than replace it.
+
+[Community PRs](/docs/contribution/contributing/community-contributions) always require a review and should only be merged with approval from a human.