Commit 64dff9a49f5 for woocommerce
commit 64dff9a49f5288505f1baab3edffc6a7838fd930
Author: Rafael Meneses <meneses.tio@gmail.com>
Date: Thu Aug 27 15:24:47 2026 -0300
Add a release decision matrix to the release docs (#67084)
* docs(releases): add release decision matrix
The readiness review and go/no-go ask for verdicts on open findings,
but nothing defined the criteria - each release re-litigated what
blocks and what waits. This page maps impact classes to default
verdicts, with modifiers, response times, and decision rules, using
the verdict vocabulary the readiness guide already established.
Refs ARC-1855
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(releases): link the decision matrix from existing release docs
Three pages already carried fragments of release criteria in
different words, which is how taxonomies drift apart. Point each at
the decision matrix so the criteria live in one place: the readiness
verdict list gains the next-release verdict, the monitoring guide
checks the matrix before opening a Slack discussion, and the
point-release evaluation criteria note the alignment.
Refs ARC-1855
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(release-templates): use decision-matrix verdicts in kickoff checklists
The RC readiness checklist and the patch go/no-go record verdicts but
linked no criteria. Both now link the decision matrix and include the
next-release verdict, so the criteria are one click away at the moment
verdicts get recorded.
Refs ARC-1855
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(releases): tighten decision-matrix examples
Review pass against the incident record: the #66822 restore merged the
next morning, not the same day; the 11.0 flag-off finding was judged
non-blocking but nothing has shipped; the 10.9.1 outcome was that no
point release was needed. The example column now holds only examples.
Refs ARC-1855
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(releases): clarify decision-matrix wording from review
The reproducibility rule read as demoting any finding not reproduced on
two stacks - including floor-class findings reproduced on one. It now
only governs findings nobody can reproduce. Also unambiguous phrasing
for the no-automated-blocking line, and the RC checklist's binary sweep
verdict now points at the full-verdict step it feeds.
Refs ARC-1855
* docs(releases): align release docs with the decision matrix
Review found the docs answering the same question differently: the
monitoring guide kept a three-condition point-release test under which
a workaround demotes a checkout bug, two low-impact rows routed
non-critical findings toward point releases, and the flag row could
stack with the flag modifier for a double demotion. The matrix is the
canonical criteria set, so the docs now defer to it: monitoring points
at the matrix and restates the floor, the two low-impact defaults
become next-release, demotion caps at one level, unreproducible
findings get a next-release verdict with a named owner, the response
times cover all four verdicts pre- and post-ship, AGENTS.md is a link,
and the RC checklist names QIT sweep findings.
Refs ARC-1855
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(releases): keep the one-level modifier cap in monitoring guidance
The reworded Handling Critical Issues sentence could be read as stacking
scope, commonality, and workaround into separate demotions down to Next
release. The matrix allows one level in total, so a non-floor
release-blocking finding with a workaround lands at a point release.
Refs ARC-1855
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
diff --git a/.linear/release-kickoff-patch.md b/.linear/release-kickoff-patch.md
index 7a9f3678d58..9a84d2aa828 100644
--- a/.linear/release-kickoff-patch.md
+++ b/.linear/release-kickoff-patch.md
@@ -18,7 +18,7 @@ For scheduled stable releases, hold this 24-48 hours before the release date wit
- [ ] No new blocking findings since the readiness review (check `#woo-core-releases` threads and the [newest issues]({repository_url}/issues?q=is%3Aissue%20state%3Aopen%20sort%3Acreated-desc)).
- [ ] Decision recorded as a comment on this issue - **go**, **no-go**, or **go with conditions** - with the names behind it.
-For scheduled releases, the readiness review is the one in the RC sub-issue. Point releases have no RC: run the [readiness criteria](https://developer.woocommerce.com/docs/contribution/releases/readiness/) over the changes being shipped as part of this go/no-go. For unscheduled point releases shipping an urgent fix, a quick go/no-go with `@woo-core-release` in `#woo-core-releases` is enough - record the outcome here all the same.
+For scheduled releases, the readiness review is the one in the RC sub-issue. Point releases have no RC: run the [readiness criteria](https://developer.woocommerce.com/docs/contribution/releases/readiness/) over the changes being shipped as part of this go/no-go, with verdicts per the [release decision matrix](https://developer.woocommerce.com/docs/contribution/releases/decision-matrix/). For unscheduled point releases shipping an urgent fix, a quick go/no-go with `@woo-core-release` in `#woo-core-releases` is enough - record the outcome here all the same.
### 2. Pre-build checks
diff --git a/.linear/release-kickoff-rc.md b/.linear/release-kickoff-rc.md
index 37695d555a7..fcc6ed1353c 100644
--- a/.linear/release-kickoff-rc.md
+++ b/.linear/release-kickoff-rc.md
@@ -14,8 +14,8 @@ Keep the _[Release Troubleshooting & Recovery](https://developer.woocommerce.com
Go through this checklist together with the Product DRIs named on the parent tracking issue before starting the build - ping `@woo-core-release` in Slack if you need to reach them or aren't sure who's available. The goal is a deliberate "this RC is ready to go out" call, with the evidence in one place. See the [readiness guide](https://developer.woocommerce.com/docs/contribution/releases/readiness/) for details on each item.
-- [ ] Review the QIT compatibility regression sweep report for this prerelease. Every introduced issue has a verdict: blocking or not.
-- [ ] Every open finding against this release (bug reports, testing threads, monitoring alerts) has a linked issue and a verdict: release-blocking / fix in a point release / not a bug.
+- [ ] Review the QIT compatibility regression sweep report for this prerelease. Every introduced issue has a verdict: blocking or not; non-blocking findings get their full verdict in the next item.
+- [ ] Every open finding against this release (bug reports, testing threads, monitoring alerts, non-blocking QIT sweep findings) has a linked issue and a verdict per the [release decision matrix](https://developer.woocommerce.com/docs/contribution/releases/decision-matrix/): release-blocking / fix in a point release / next release / not a bug.
- [ ] The rollback path for this release is known: who reverts, how, and what revert means for this version (see the [troubleshooting guide](https://developer.woocommerce.com/docs/contribution/releases/troubleshooting/)).
- [ ] Comms are ready: the changelog is in shape and there's a known-issues list if the verdicts above left anything open.
diff --git a/docs/contribution/releases/README.md b/docs/contribution/releases/README.md
index 814cd164ff1..abf08bbc3cf 100644
--- a/docs/contribution/releases/README.md
+++ b/docs/contribution/releases/README.md
@@ -11,6 +11,7 @@ The WooCommerce release process is managed by a rotating release lead, alongside
* [Building and Publishing](/docs/contribution/releases/building-and-publishing)
* [Readiness and Go/No-Go](/docs/contribution/releases/readiness)
+* [Decision Matrix](/docs/contribution/releases/decision-matrix)
* [Troubleshooting](/docs/contribution/releases/troubleshooting)
* [Point Releases](/docs/contribution/releases/point-releases)
* [Security Support](/docs/contribution/releases/security-support)
diff --git a/docs/contribution/releases/decision-matrix.md b/docs/contribution/releases/decision-matrix.md
new file mode 100644
index 00000000000..c984a06aa07
--- /dev/null
+++ b/docs/contribution/releases/decision-matrix.md
@@ -0,0 +1,66 @@
+---
+post_title: Release Decision Matrix
+sidebar_label: Decision Matrix
+sidebar_position: 5
+---
+
+# Release Decision Matrix
+
+Every finding against a release gets a verdict - at the readiness review, at the go/no-go, and when weighing whether an already-shipped issue warrants a point release. This page is the criteria for picking that verdict. The decision points themselves are described in [Readiness and Go/No-Go](/docs/contribution/releases/readiness); the criteria apply to Core and Woo-owned extension releases, for all release types.
+
+The matrix guides the people making the call - the release lead and the Product DRI. It does not change which automated checks gate a build.
+
+## Verdicts
+
+| Verdict | Meaning |
+| --- | --- |
+| **Release-blocking** | The release does not ship with this issue in it: hold the date or remove the change. Found after shipping: point release now. |
+| **Fix in a point release** | Ship on schedule. The fix has an issue, an owner, and a target release *before* the go decision - without those, it re-enters as release-blocking. |
+| **Next release** | Ship. The fix rides the next scheduled release. |
+| **Not a bug** | Expected behavior, or an invalid finding. |
+
+A finding no one can reproduce - tried on at least two independent stacks - gets **Next release, with a named owner**: it does not block the release, and the issue stays open rather than being closed as not a bug. A finding that reproduces anywhere keeps its impact-class verdict.
+
+## Default verdict by impact class
+
+| Impact class | Default verdict | Example |
+| --- | --- | --- |
+| Checkout or revenue interruption - a store cannot take payments | Release-blocking; no modifiers apply | - |
+| Site down or fatal on load, in Core or any Woo-owned extension - including older extension versions running with the new Core | Release-blocking | [#64394](https://github.com/woocommerce/woocommerce/pull/64394) forced the revert after 10.9.0; [#65957](https://github.com/woocommerce/woocommerce/pull/65957) rescheduled 11.0.0 after a fatal surfaced on an early deployment |
+| Data loss or corruption | Release-blocking | - |
+| A break in a public contract or shared surface with consumers in the wild - PHP API, hooks, REST, datastore behavior | Release-blocking | [#65595](https://github.com/woocommerce/woocommerce/pull/65595) changed datastore behavior extensions relied on and forced a revert; [#66382](https://github.com/woocommerce/woocommerce/pull/66382) removed released public methods, restored within a day by [#66822](https://github.com/woocommerce/woocommerce/pull/66822) |
+| A contract change whose surface has no known consumers, or that went through the deprecation path in the repository's [`AGENTS.md`](https://github.com/woocommerce/woocommerce/blob/trunk/AGENTS.md) | Next release | - |
+| WordPress forward-compatibility - the release breaks under a WordPress version shipping before our next release | Fix in a point release scheduled before the WordPress date; release-blocking if the breakage is site-down class | [#67061](https://github.com/woocommerce/woocommerce/pull/67061) shipped WordPress 7.1 fixes inside the 11.0.0 rebuild, because 7.1 lands before 11.1.0 |
+| Broken upgrade path - the update itself fails or leaves a site inconsistent | Release-blocking if deterministic; fix in a point release if transient and self-healing | The 10.9.1 upgrade race self-healed on cache refresh and produced a single report - no point release was needed |
+| A regression in a default-on, merchant-facing feature | Release-blocking without a workaround; fix in a point release with one | - |
+| A regression behind a flag that is off by default | Next release | An 11.0 REST API field inconsistency was judged non-blocking because the flag is off by default, with the rename scheduled for a later release |
+| A performance regression | Release-blocking at scale with no mitigation; otherwise fix in a point release with the mitigation named | [#66088](https://github.com/woocommerce/woocommerce/pull/66088) had a filter mitigation available immediately; the fix ([#66786](https://github.com/woocommerce/woocommerce/pull/66786)) was backported into the next build |
+| Cosmetic and UX papercuts | Next release | - |
+
+Security issues follow the security team's process, not this matrix. Sensitive fixes may ship as a dedicated point release immediately after stable - coordinate with the security team.
+
+## Modifiers
+
+A modifier moves a verdict one level, never past the floor: **checkout, data, and site-down verdicts do not demote.** A verdict moves at most one level in total: when a row already prices in a modifier's condition - as the off-by-default flag row does - that modifier does not apply again; the more specific row wins. A fatal with a documented workaround is still a fatal for every store that hits it before reading the workaround.
+
+- **Feature flags, by trajectory.** A flag that is off by default demotes the verdict one level - unless the flag is scheduled to default on in the next release, in which case no demotion applies: for release purposes it is already on. When nobody can state the flag's trajectory, the demotion applies, the verdict records the assumption ("assumes the flag stays off through next cycle"), and the unanswered question goes to the feature's owner.
+- **Blast radius.** How many stores are exposed, and how fast. Managed hosting platforms can deploy an update to every site at once rather than following WordPress.org's staged rollout, so managed-fleet exposure weighs heavier than install counts alone. This extends the scope and commonality criteria in [Point Releases](/docs/contribution/releases/point-releases).
+- **Workaround.** A documented workaround that merchants can apply themselves demotes one level - never past the floor. This matches the workaround criterion in [Point Releases](/docs/contribution/releases/point-releases).
+
+## Response times
+
+| Verdict | Response time |
+| --- | --- |
+| Release-blocking | The verdict is recorded the same day the finding is raised; the release does not proceed to the next run-book step until it is. |
+| Fix in a point release | The fix is scheduled - issue, owner, target release - before the go decision. For findings that surface after shipping: within the [monitoring window](/docs/contribution/releases/monitoring) (3 days after a major release, 1 day after a point release). |
+| Next release | The issue is filed and milestoned when the verdict is recorded: before the go decision for findings against an unshipped release, within the same monitoring window for findings that surface after shipping. |
+| Not a bug | The verdict and the reasoning are recorded on the linked issue when it is closed. |
+
+These are verdict-and-scheduling times, not fix-delivery guarantees.
+
+## Decision rules
+
+1. **Revert over rush.** When a fix cannot get the same validation the original change had before the release date, remove the change instead of patching under pressure.
+2. **Silence is not a pass.** Every signal read at the readiness review and go/no-go has a named responder. An unreviewed signal counts as missing, not green.
+3. **Verdicts are recorded, with names.** The release lead and the Product DRI record each verdict on the linked issue. Disputes over a classification are argued and settled on that issue, so the reasoning is written down where the verdict lives.
+4. **The same matrix applies to extensions**, in both directions of the Core-extension version pairing. Extensions maintained by partners route through the owning team's channel.
diff --git a/docs/contribution/releases/monitoring.md b/docs/contribution/releases/monitoring.md
index 05cddd6cac6..eb35ae73ab7 100644
--- a/docs/contribution/releases/monitoring.md
+++ b/docs/contribution/releases/monitoring.md
@@ -8,7 +8,7 @@ sidebar_position: 7
After the release, the release lead should continue to monitor the following for any bugs directly related to the latest version. Monitoring should continue for 3 days after a major release and 1 day for a point release.
-If there are questions whether a specific issue is critical enough to warrant a new point release, please start a discussion in the `#woo-core-releases` Slack channel.
+If there are questions whether a specific issue is critical enough to warrant a new point release, check the [release decision matrix](/docs/contribution/releases/decision-matrix) first; for genuine ties, start a discussion in the `#woo-core-releases` Slack channel.
## WordPress.org Forums
@@ -28,10 +28,6 @@ An old extension version can point to a compatibility issue, but it does not pro
## Handling Critical Issues
-If monitoring uncovers a bug that **cannot wait** for the next scheduled release, plan a point release. Before doing so, confirm that the issue:
+If monitoring uncovers a bug that **cannot wait** for the next scheduled release, plan a point release. The [release decision matrix](/docs/contribution/releases/decision-matrix) is the criteria set for that call: look up the finding's impact class and apply the modifiers from there. Checkout, data-loss, and site-down issues warrant a point release even when a workaround exists; below that floor, limited scope, low commonality, and a documented workaround can support a lower verdict, subject to the matrix's one-level modifier cap.
-1. **Impacts core store functionality** (e.g., checkout, orders, taxes).
-2. **Affects a significant number of sites** or stems from a widely-used extension or theme.
-3. **Lacks a reasonable workaround** that merchants can apply themselves.
-
-If these conditions are met, follow the [Point Releases guide](/docs/contribution/releases/point-releases) to create a tracking issue, prepare the fix, and ship the patch.
+If the verdict is a point release, follow the [Point Releases guide](/docs/contribution/releases/point-releases) to create a tracking issue, prepare the fix, and ship the patch.
diff --git a/docs/contribution/releases/point-releases.md b/docs/contribution/releases/point-releases.md
index d6fc4090752..0a7131fca91 100644
--- a/docs/contribution/releases/point-releases.md
+++ b/docs/contribution/releases/point-releases.md
@@ -35,13 +35,13 @@ In all cases, point releases must remain backward compatible. No breaking change
## Evaluating whether to ship a point release
-Use your best judgement based on the urgency and severity of the outstanding issue. The release lead and the reporter should weigh:
+Use your best judgement based on the urgency and severity of the outstanding issue. These criteria align with the [release decision matrix](/docs/contribution/releases/decision-matrix), which maps impact classes to default verdicts. The release lead and the reporter should weigh:
| Criterion | Guidance |
| --- | --- |
| **Scope of impact** | How many stores are already affected? Larger reach increases urgency. |
| **Error commonality** | Does the problem stem from a widely-used core flow, plugin, or theme? Issues in common components usually merit faster action. |
-| **Workarounds** | Is there an easy, documented workaround (a filter, setting toggle, or temporary feature disable) that store owners can apply? Readily available workarounds lower the need for a point release. |
+| **Workarounds** | Is there an easy, documented workaround (a filter, setting toggle, or temporary feature disable) that store owners can apply? Readily available workarounds lower the need for a point release - except for checkout, data-loss, and site-down issues, where the matrix calls for a point release regardless. |
| **Impact severity** | Does the bug block critical commerce functionality (checkout, payments, product visibility)? The more business-critical the failure, the higher the priority. |
Some practical timing notes:
diff --git a/docs/contribution/releases/readiness.md b/docs/contribution/releases/readiness.md
index 1f510c2baf6..489f61fa29a 100644
--- a/docs/contribution/releases/readiness.md
+++ b/docs/contribution/releases/readiness.md
@@ -26,7 +26,7 @@ The RC is the last point where finding a problem is cheap: nothing has shipped,
The checklist covers four areas:
* **Compatibility evidence.** The QIT compatibility regression sweep runs automatically against each prerelease and reports which extension versions the release would break. Introduced issues need a verdict, not just a look.
-* **Open findings.** Bug reports, testing threads, and monitoring alerts against the release each get a linked issue and a verdict: release-blocking, fix in a point release, or not a bug.
+* **Open findings.** Bug reports, testing threads, and monitoring alerts against the release each get a linked issue and a verdict per the [release decision matrix](/docs/contribution/releases/decision-matrix): release-blocking, fix in a point release, next release, or not a bug.
* **Rollback path.** Who reverts, how, and what revert means for this version - answered before it's needed, not during an incident.
* **Comms.** Changelog in shape, and a known-issues list when verdicts left something open.