Commit 3d2efacaf01 for woocommerce
commit 3d2efacaf01e9374e37b0107a8442850641ad155
Author: Jorge A. Torres <jorge.torres@automattic.com>
Date: Sat May 30 08:43:09 2026 +0100
Consolidate point release pages and update cherry picking guide (#65344)
diff --git a/docs/contribution/releases/README.md b/docs/contribution/releases/README.md
index a010c628405..9498d3265d6 100644
--- a/docs/contribution/releases/README.md
+++ b/docs/contribution/releases/README.md
@@ -12,8 +12,7 @@ The WooCommerce release process is managed by a rotating release lead. The docu
* [Building and Publishing](/docs/contribution/releases/building-and-publishing)
* [Troubleshooting](/docs/contribution/releases/troubleshooting)
* [Point Releases](/docs/contribution/releases/point-releases)
-* [Backporting](/docs/contribution/releases/backporting)
-* [Point Release Requests](/docs/contribution/releases/point-release-fixes)
+* [Cherry-picking](/docs/contribution/releases/backporting)
* [Pre-releases](/docs/contribution/releases/prereleases)
* [Release Schedule](/docs/contribution/releases/schedule)
* [Release Monitoring](/docs/contribution/releases/monitoring)
diff --git a/docs/contribution/releases/backporting.md b/docs/contribution/releases/backporting.md
index fd739c1d073..78fb9e10d13 100644
--- a/docs/contribution/releases/backporting.md
+++ b/docs/contribution/releases/backporting.md
@@ -1,57 +1,59 @@
---
-post_title: Backporting in WooCommerce
-sidebar_label: Backporting
+post_title: Cherry-picking in WooCommerce
+sidebar_label: Cherry-picking
sidebar_position: 3
---
-# Backporting in WooCommerce
+# Cherry-picking in WooCommerce
-Backporting is the process of applying changes from `trunk` to a release branch. This ensures critical fixes reach customers in upcoming releases. Note that these flows apply only to UPCOMING RELEASES (not patches to already-released versions).
+Cherry-picking is the process of applying changes between `trunk` and a release branch (in either direction). This page is the canonical reference for the cherry-pick mechanics used by both pre-release stabilization (beta, RC) and patch releases.
+
+For the patch-release-specific process (when a patch is warranted, who creates the tracking issue, and how it ships), see the [Point Releases guide](/docs/contribution/releases/point-releases).
## Release Branch Lifecycle
-When a release branch is created, it's copied from `trunk` at the time of feature freeze. After creation:
+When a release branch is created, it is copied from `trunk` at the time of feature freeze. After creation:
-- The release branch no longer receives new feature updates
-- Only critical changes are allowed
-- Because we do not merge the release branches back into `trunk`, any fixes in a release branch must also be applied to `trunk`.
+- The release branch no longer receives new feature updates.
+- Only critical changes are allowed.
+- Because we do not merge release branches back into `trunk`, any fix landed on a release branch must also be applied to `trunk` (and, when applicable, to the next frozen release branch).
-## Qualifying Changes for Backporting
+### What "frozen release" means
-Changes qualify for backporting only if they are:
+A frozen release branch is the most recent `release/x.y` cut from `trunk` for the next upcoming version. While the previous release is still in maintenance, this branch is the one feature work has already moved on to. The `cherry pick to frozen release` label forward-ports a fix from the current maintenance branch to this branch so the same fix also ships in the next major version. Frozen releases only accept critical bug fixes, the same bar as any other release branch.
-- **Bug fixes** that affect the release
-- **Performance improvements** that impact WooCommerce functionality
-- **Time-sensitive features** that impact business goals
-- **Contractually required features** for WooCommerce
+## Qualifying Changes for Cherry-picking
-## Backporting Process for Contributors
+Changes qualify for cherry-picking only if they are:
-### Standard Workflow: Trunk to Release Branch
+- **Bug fixes** that affect the release.
+- **Performance improvements** that impact WooCommerce functionality.
+- **Time-sensitive features** that impact business goals.
+- **Contractually required features** for WooCommerce.
-**When to use:** Most backporting scenarios
+## Cherry-pick Workflows
-1. **Target `trunk`** as your base branch
-2. **Add milestone** matching your target release (e.g., `9.8.0`)
-3. **Get PR reviewed and merged** into `trunk`
-4. **Automated workflow** creates a cherry-pick PR for the release branch
-5. **The original contributor or merger** reviews and merges the backport PR
+### Standard Workflow: `trunk` to Release Branch
-> **Note:** For urgent fixes near release deadlines, contact the release lead directly.
+**When to use:** Most cherry-pick scenarios, including the preferred path for patch release fixes.
-### Alternative Workflow: Release Branch to Trunk
+1. **Target `trunk`** as the base branch.
+2. **Set the milestone** to the release series (e.g. `9.8.0`). WooCommerce milestones use the `.0` form for the whole `X.Y.x` series, so a fix targeting `X.Y.1` still uses milestone `X.Y.0`.
+3. **Get the PR reviewed and merged** into `trunk`.
+4. A cherry-pick PR against the release branch is opened automatically.
+5. **The author** (or whoever merged the original PR) reviews, tests against the release branch, and merges the cherry-pick PR. The cherry-pick PR shares the same milestone as the original fix and must land before the release is published.
-**When to use:** Critical fixes that must target the release branch directly
+For urgent fixes near release deadlines, reach out to the release lead in the `#woo-core-releases` Slack channel.
-1. **Target the release branch** as your base branch
-2. **Add label** `cherry pick to trunk` if the change should also go to `trunk`
-3. **Get PR reviewed and merged** into the release branch
-4. **Automated workflow** creates a forward-port PR for `trunk`
-5. **Merge the trunk PR** as soon as possible to avoid delays
+### Alternative Workflow: Release Branch to `trunk`
-## Important Notes
+**When to use:** The fix doesn't apply cleanly to `trunk`, or the branches have diverged enough that landing on `release/x.y` first is simpler.
-- Changes must meet backporting qualifications
-- Frozen releases only accept critical bug fixes
-- All backports require review and testing
-- Forward-ports to trunk should be merged promptly as these are tracked with the same milestone as the original PR.
+1. **Target the release branch** (e.g. `release/9.8`) as the base branch.
+2. **Apply labels** for any branches that need the forward-port:
+ - `cherry pick to trunk` to forward-port to `trunk`.
+ - `cherry pick to frozen release` to forward-port to the next frozen release branch (see [frozen release definition above](#what-frozen-release-means)).
+3. **Include a changelog entry** and set the milestone to the release series (`X.Y.0`).
+4. **Get the PR reviewed and merged** into the release branch.
+5. The cherry-pick automation opens follow-up PRs against `trunk` and/or the frozen branch based on which labels are present.
+6. **The author** reviews and merges the follow-up PRs promptly. They share the same milestone as the original fix and must land before the release is published.
diff --git a/docs/contribution/releases/building-and-publishing.md b/docs/contribution/releases/building-and-publishing.md
index 39c6251e505..6210dc9b0ca 100644
--- a/docs/contribution/releases/building-and-publishing.md
+++ b/docs/contribution/releases/building-and-publishing.md
@@ -61,7 +61,7 @@ This step only applies to `rc` or stable (`x.y.0` onwards) releases.
##### If a critical issue was detected while monitoring
- [ ] Request a revert in the staging environment.
-- [ ] Pause the release process and **do not continue with any steps on this issue**. Follow the procedure in the [troubleshooting guide](https://developer.woocommerce.com/docs/contribution/releases/troubleshooting/#deploy-serious-bug) instead.
+- [ ] Pause the release process and **do not continue with any steps on this issue**. Follow the procedure in the [troubleshooting guide](https://developer.woocommerce.com/docs/contribution/releases/troubleshooting/#a-serious-bug-was-detected-during-internal-checks--monitoring) instead.
#### 5. Publish the release
diff --git a/docs/contribution/releases/monitoring.md b/docs/contribution/releases/monitoring.md
index 6d5ec668ba6..228bf9b3eac 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 creating a new Point Release Fix, please start a discussion WooCommerce Slack [#core-development](https://woocommercecommunity.slack.com/archives/C4TNYTR28).
+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.
## WordPress.org Forums
@@ -18,17 +18,12 @@ Check newly created threads on the [WordPress.org Forums](https://wordpress.org/
Watch the [Newest Created Issues](https://github.com/woocommerce/woocommerce/issues?q=is%3Aissue%20state%3Aopen%20sort%3Acreated-desc) and verify that none are critical.
-## Handling Critical Issues: Point Release Requests
+## Handling Critical Issues
-If monitoring uncovers a bug that **cannot wait** for the next scheduled release, initiate a **Point Release Request (PRR)**.
-The PRR workflow lets the release lead fast-track a fix into the current maintenance branch and, when necessary, automatically cherry-pick it to trunk and the next frozen branch.
-
-[Read the full Point Release guide](/docs/contribution/releases/point-releases).
-
-Before opening a PRR, confirm that the issue:
+If monitoring uncovers a bug that **cannot wait** for the next scheduled release, plan a point release. Before doing so, confirm that the issue:
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 PRR guide to create the request, provide the required justification, and notify the release lead for approval and merge.
+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.
diff --git a/docs/contribution/releases/point-release-fixes.md b/docs/contribution/releases/point-release-fixes.md
deleted file mode 100644
index b6912d2c18d..00000000000
--- a/docs/contribution/releases/point-release-fixes.md
+++ /dev/null
@@ -1,69 +0,0 @@
----
-post_title: Point Release Requests in WooCommerce
-sidebar_label: Point Release Requests
-sidebar_position: 4
----
-
-# Point Release Requests in WooCommerce
-
-:::important
-The formal Point Release Request (PRR) issue template is not strictly required for all point release fixes. In practice, coordinating directly with the release lead is often sufficient to get fixes included in a point release. The rest of this document remains useful for understanding what types of fixes qualify for point releases and how to prepare them in the repository.
-:::
-
-Point releases address critical issues discovered in already-shipped WooCommerce versions. These are patch releases (e.g., 9.9.0 → 9.9.1) that contain only essential fixes for production environments.
-
-Note that this process applies only to ALREADY-RELEASED VERSIONS that are in customer production environments.
-
-## Point Release Lifecycle
-
-Point releases follow a different lifecycle than regular releases:
-
-- **Triggered by critical issues** discovered after a regular release ships
-- **Limited scope** - only critical bug fixes and security patches
-- **Expedited timeline** - faster review and release cycle
-- **Backward compatibility** - no breaking changes allowed
-
-## Qualifying Changes for Point Releases
-
-Changes qualify for point releases only if they are:
-
-- **Critical bug fixes** that cause data loss, security vulnerabilities, or major functionality failures
-- **Security patches** addressing identified vulnerabilities
-- **Performance fixes** for severe performance regressions
-- **Compliance fixes** required for regulatory or legal compliance
-
-**Excluded from point releases:**
-
-- New features or enhancements
-- Non-critical bug fixes
-- Code refactoring or cleanup
-- Documentation updates
-
-## Point Release Request Process
-
-### Standard Process: Critical Bug Fixes
-
-**When to use:** Most point release scenarios
-
-1. **Create a pull request** against the appropriate release branch (e.g., `release/9.9` for a fix targeting 9.9.x releases)
-
-2. **Create a point release request issue** using the [point release template](https://github.com/woocommerce/woocommerce/issues/new?template=new-prr-template.yml) in the main repository
-
-3. **Provide detailed justification** in the issue including:
- - Impact assessment (how many customers affected)
- - Business impact (revenue, compliance, security implications)
- - Risk assessment of the proposed fix
- - Evidence and reproduction steps
-
-4. **Wait for release lead approval** - the release lead will approve the request, which automatically adds cherry-pick labels to your PR
-
-5. **Adjust branch targeting** by modifying the automatically-added labels to specify which additional branches need the fix:
- - Keep `cherry pick to trunk` if the fix should go to trunk
- - Keep `cherry pick to frozen release` if the fix should go to the current frozen release
- - Remove labels for branches that don't need the fix
-
-6. **Get your pull request reviewed, tested, and merged** into the target release branch
-
-7. **Automation creates cherry-pick PRs** to other branches based on the labels still applied to your original PR
-
-8. **Review and merge cherry-pick PRs** as soon as possible to ensure they don't delay the next release. These cherry-pick PRs are tracked with the same milestone as the original critical fix and must be merged before the point release is published.
diff --git a/docs/contribution/releases/point-releases.md b/docs/contribution/releases/point-releases.md
index b47f5fcf904..85e7f3ac353 100644
--- a/docs/contribution/releases/point-releases.md
+++ b/docs/contribution/releases/point-releases.md
@@ -7,119 +7,65 @@ sidebar_position: 2
# Point Releases
:::important
-The formal Point Release Request (PRR) issue template is not strictly required for all point release fixes. In practice, coordinating directly with the release lead is often sufficient to get fixes included in a point release. The rest of this document remains useful for understanding what types of fixes qualify for point releases and how to prepare them in the repository.
+The formal Point Release Request (PRR) issue template ([`new-prr-template.yml`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/ISSUE_TEMPLATE/new-prr-template.yml)) is no longer required for point release fixes; it is preserved only for reference. In practice, coordinating directly with the release lead is sufficient to get fixes included in a point release, and is the most important step. The rest of this document covers what types of fixes qualify for point releases and how to prepare them in the repository.
:::
-## What Are Point Releases?
+Point releases are patch releases that address specific issues in an already-shipped WooCommerce version (for example `9.9.0 → 9.9.1`) without adding new functionality. They apply only to versions that are already in customer production environments.
-Point releases are patch releases that address specific issues without adding substantial new functionality. Point releases typically contain:
+## What qualifies as a point release
-- **Critical bug fixes** affecting store functionality or checkout processes
-- **Security patches** for urgent vulnerabilities
-- **Compatibility fixes** for WordPress, theme, or plugin conflicts
+Changes appropriate for a point release are:
-## Timing a Point Release
+- **Critical bug fixes** affecting store functionality (checkout, orders, payments, product visibility).
+- **Security patches** for urgent vulnerabilities.
+- **Severe performance regressions** introduced by the shipped release.
+- **Compliance fixes** required for regulatory or legal reasons.
+- **Compatibility fixes** for WordPress, theme, or plugin conflicts that are breaking stores.
-When considering the exact time to create a point release, use your best judgement based on the urgency and severity of outstanding issues:
+The following are **not** point release material and should ride the next regular release instead:
-- If the issue is not very urgent, consider waiting 3–4 days to see if additional related issues are reported before proceeding. This helps consolidate fixes and reduces the number of patch releases.
-- For high-severity or critical issues, prioritize releasing as soon as possible to minimize impact on users.
-- For security issues, coordinate with the team that implemented the security fix to help determine urgency if it is not clear.
-- Consider whether other known issues are already being worked on that could be included in the same release.
+- New features or enhancements.
+- Non-critical bug fixes.
+- Code refactoring or cleanup.
+- Documentation updates.
-## The Point Release Requests (PRR) flow
+In all cases, point releases must remain backward compatible. No breaking changes are allowed in a patch.
-The **Point Release Request (PRR) flow** is a structured process for requesting and managing critical fixes that need to be included in WooCommerce point releases. This process ensures that urgent bug fixes can be safely incorporated into current stable release and automatically forward-port them to trunk and any frozen branches, preserving code quality, enforcing thorough reviews, and preventing regressions.
+⚠️ Security vulnerability reports must **not** go through this flow. Report them privately via Automattic's HackerOne program: [https://hackerone.com/automattic/](https://hackerone.com/automattic/).
-**⚠️ Important:** Security Vulnerability reports must not go through the PRR flow. All potential security issues should be reported privately via Automattic’s HackerOne program: [https://hackerone.com/automattic/](https://hackerone.com/automattic/).
+## Evaluating whether to ship a point release
-### Step-by-Step Process
+Use your best judgement based on the urgency and severity of the outstanding issue. The release lead and the reporter should weigh:
-#### 1a. Initial Issue Creation
+| 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. |
+| **Impact severity** | Does the bug block critical commerce functionality (checkout, payments, product visibility)? The more business-critical the failure, the higher the priority. |
-To ensure the release lead is aware of all planned fixes to be included in the next point release, it is important to create either an issue or PR as soon as a bug is discovered and planned as a patch fix. This will help reduce the number of patch releases that need to be created.
+Some practical timing notes:
-If the initial PR may take more than a few hours to create, please create an issue and set the milestone of the issue to targeted release. E.g. use milestone `10.1.0` for a new point release request for `10.1.x`.
+- If the issue is not very urgent, consider waiting 3–4 days to see if additional related issues are reported before proceeding. This consolidates fixes and reduces the number of patch releases.
+- For high-severity or critical issues, prioritize releasing as soon as possible.
+- For security issues, coordinate with the team that implemented the fix to help determine urgency if it is not clear.
+- Consider whether other known issues already being worked on could be included in the same release.
-#### 1b. Initial Pull Request Creation
+## Process
-**Author Action**: Create a pull request against the release branch (`release/x.y`) instead of the trunk branch, following the standard PR creation process.
+The work is split between the **fix author** and the **release lead**. These tasks can happen in parallel. The author does not need to wait for the tracking issue before opening a PR, and the release lead can create the tracking issue independently once a point release is on the table.
-- The PR should target the specific release branch (e.g., `release/9.5` for an issue found on WooCommerce 9.5.x)
-- Include a regular changelog file as you would for trunk PRs
-- Ensure all standard PR requirements are met (description, testing, etc.)
-- Ensure that the PR has a milestone set to the target release so it can be tracked by the release lead, e.g. use milestone `10.1.0` for a new point release request for `10.1.x`.
+### For the fix author: prepare the fix
-#### 2. Point Release Request Submission
+Two paths are acceptable. The first is preferred when the fix applies cleanly to both branches.
-**Author Action**: Submit a PRR using the [Point Release Request template](https://github.com/woocommerce/woocommerce/issues/new?template=new-prr-template.yml).
+- **Preferred:** merge to `trunk` with the `X.Y.0` milestone set. The cherry-pick automation handles the rest. See the [Cherry-picking guide](/docs/contribution/releases/backporting) for the full flow, including your responsibility for reviewing and merging the auto-generated cherry-pick PR.
+- **Alternative:** PR directly against the `release/X.Y` branch when the fix doesn't apply cleanly to `trunk`. Use the [cherry-pick label flow](/docs/contribution/releases/backporting) to forward-port to `trunk` (and the next frozen release if applicable).
-Provide the required PRR template information:
+Once the PR and any cherry-pick follow-ups have been reviewed, merged, and milestoned, the rest is on the release lead.
-**Required Fields:**
+### For the release lead: create the tracking issue and cut the release
-- **PR URL**: The pull request URL against the release branch
-- **Justification**: Why this PR needs a point release
-- **Impact Assessment**: Consequences if the fix is not included (number of users affected and how)
-- **Contingency Plan**: What to do if defects are discovered after the point release
-- **Communication Plan**: How the change should be communicated in the release blog post
-- **Workaround**: Any available workarounds and how to communicate them
-- **Alternative Contact**: Who to contact if the author is unavailable
+Run the [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/actions/workflows/release-create-tracking-issue.yml) workflow for the target point release version (e.g. `9.9.1`). Do **not** reuse an existing tracking issue, even if a previous release in the same series was blocked. The workflow automatically nests the new Linear issue under the `[X.Y] Release tracking` parent for that release series, so the entire release series remains a single tree in Linear.
-#### 3. Release-Lead Review
-
-After a PRR is opened, the **release lead** evaluates it.
-When deciding whether to approve a PRR, the release lead should consider the following:
-
-| Evaluation 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 (e.g., a filter, setting toggle, or temporary feature disable) that store owners can apply? Readily available workarounds lower the need for a point release. |
-| **Impact Severity** | Does the bug block critical commerce functionality (checkout, payments, product visibility)? The more business-critical the failure, the higher the priority. |
-
-#### 4. Approval or Rejection
-
-| Outcome | Release-Lead Action | Workflow Triggered |
-| --------- | -------------------- | ------------------- |
-| **Approve** | Apply the **`Approved`** label to the PRR issue and optionally leave a short rationale referencing the criteria above. | Labels are automatically added to the PR (“cherry pick to trunk”, “cherry pick to frozen release”); the issue milestone is set to the current release; the PRR is commented with an approval note. |
-| **Reject** | Apply the **`Rejected`** label and briefly state the reason (e.g., limited impact, simple workaround available). | A workflow adds a comment, closes the PRR, and the author must retarget the PR to `trunk`, resolve conflicts, and merge through the normal path. |
-
-
-#### 5. Merge to Release Branch (Release Lead / Core Contributor)
-
-- **Verify cherry-pick requirements**
- - Check whether the fix is already included in `trunk` and/or the next frozen branch.
- - If the fix *should not* be forward-ported, remove the labels `cherry pick to trunk` and `cherry pick to frozen release`.
-
-- **Merge the PR**
- - After reviewing the labels, merge the PR into the current `release/x.y` branch.
- - Confirm that the changelog entry and milestone are correct.
-
-- **Resulting automation**
- - If either cherry-pick label remains, GitHub Actions opens follow-up PRs to `trunk` and/or the frozen release branch.
- - If both labels were removed, no cherry-pick workflows run.
-
-#### 6. Review & Merge Follow-up PRs (Release Lead)
-
-After the primary fix is merged into `release/x.y`, the labels that remain on the PR determine what happens next:
-
-| Label present | Automation result | What the release lead must do |
-| --------------- | ------------------- | ------------------------------ |
-| `cherry pick to trunk` | Action opens a new PR targeting `trunk` and adds the current milestone. | Review tests / CI and merge this PR. |
-| `cherry pick to frozen release` | Action opens a new PR targeting the **next frozen branch** (e.g., `release/9.6`) and adds the milestone. | Review and merge this PR as well. |
-
-Both follow-up PRs **must be merged before the point-release tag is cut**.
-If either cherry-pick is not required, ensure its label was removed during Step 5 so no unnecessary PR is generated.
-
-#### 7. Publish the Point Release (Release Lead)
-
-Once all required PRs are merged into:
-
-- `release/x.y` (current maintenance branch)
-- `trunk` (future feature branch)
-- *optional* frozen branch (`release/x.y+1`)
-
-the **release lead** creates and publishes the new point release that contains every approved PRR since the last shipment.
-
-Follow the established [WooCommerce release process](/docs/contribution/releases/building-and-publishing).
+The tracking issue contains the version-specific checklist for cutting and publishing the release. Follow it from there. For underlying mechanics (workflows, draft releases, stable tag updates), refer to [Building and Publishing](/docs/contribution/releases/building-and-publishing).
diff --git a/docs/contribution/releases/prereleases.md b/docs/contribution/releases/prereleases.md
index 4786be2dc34..e3b77df8254 100644
--- a/docs/contribution/releases/prereleases.md
+++ b/docs/contribution/releases/prereleases.md
@@ -10,13 +10,14 @@ WooCommerce pre-releases provide early access to upcoming features and improveme
This document outlines the different types of pre-releases available, their timing, and how they fit into the overall release cycle.
-| Release Name | Estimated Timing |
-|-------------------|------------------------------------------------------|
-| `nightly` | Every night |
-| `-dev` | At feature freeze |
-| `-beta.1` | 1 week after feature freeze |
-| `-beta.2`, ... | At least 1 more, as needed before `-rc.1` |
-| `-rc.1` | Shortly (~1 day) before final release |
+| Release Name | Estimated Timing |
+|-------------------|-----------------------------------------------------------------|
+| `nightly` | Every night |
+| `-dev` | At feature freeze |
+| `-beta.1` | 1 week after feature freeze |
+| `-beta.2`, ... | At least 1 more, as needed before `-rc.1` |
+| `-rc.1` | Shortly (~1 day) before final release |
+| `-rc.2`, ... | As needed, when a critical bug is detected during RC monitoring |
## Nightlies
@@ -55,3 +56,5 @@ These are pre-release versions that are feature-complete and considered stable e
They are versioned incrementally as `-rc.1`, `-rc.2`, and so on.
We aim to release at least one RC before the final release, which will not be publicly announced but will be tagged and available for download on both GitHub and WordPress.org.
+
+Additional RCs (`-rc.2` onwards) are only cut when monitoring uncovers a critical bug. Their tracking issues are not created by the regular release-assignment automation; they are created on demand by running [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/actions/workflows/release-create-tracking-issue.yml). See the [troubleshooting guide](/docs/contribution/releases/troubleshooting#a-serious-bug-was-detected-during-internal-checks--monitoring) for the full recovery procedure.
diff --git a/docs/contribution/releases/schedule.md b/docs/contribution/releases/schedule.md
index fc880e5e01f..5d11d96ee64 100644
--- a/docs/contribution/releases/schedule.md
+++ b/docs/contribution/releases/schedule.md
@@ -37,7 +37,7 @@ At this stage, various testing processes take place:
- (Internally) Regression testing with Woo-maintained extensions, regression testing in multiple environments, and exploratory testing (including by contributing teams).
- (Community) The pre-release is announced so the community can [begin testing](/docs/contribution/testing/beta-testing/).
-Any issues found during the beta period are addressed either directly against the release branch or by backporting fixes from `trunk` (preferred). Refer to the [backporting guide](/docs/contribution/releases/backporting) for more details.
+Any issues found during the beta period are addressed either directly against the release branch or by backporting fixes from `trunk` (preferred). Refer to the [cherry-picking guide](/docs/contribution/releases/backporting) for more details.
`release/x.y` remains the source of truth for anything going into the upcoming release.
@@ -58,12 +58,7 @@ At this point, the Developer Advocacy team publishes release highlights that are
### Point/Patch Releases
-Patch releases are used to ship important bug fixes to our users, which were detected after the final release. They are versioned `x.y.z` where `z` is non-zero.
-
-We follow the same convention as during the beta and RC phases for merging any fixes:
-
-- Bugs that are only present on the release branch are fixed against the release branch `release/x.y`.
-- Bugs that have a working fix on `trunk` are [backported](/docs/contribution/releases/backporting).
+Patch releases ship important bug fixes detected after the final release. They are versioned `x.y.z` where `z` is non-zero. See the [Point Releases guide](/docs/contribution/releases/point-releases) for the full process, including how a patch is evaluated, prepared, and shipped.
## Delays
diff --git a/docs/contribution/releases/troubleshooting.md b/docs/contribution/releases/troubleshooting.md
index 2afc8da26bc..bee5d04e546 100644
--- a/docs/contribution/releases/troubleshooting.md
+++ b/docs/contribution/releases/troubleshooting.md
@@ -27,7 +27,7 @@ During the release process, you may encounter CI test failures on release-relate
2. **Backport test fixes**: If possible, [backport](/docs/contribution/releases/backporting) the relevant test fixes from trunk to the release branch, then re-run the CI workflow.
3. **Handle complex cases**: If backporting isn't possible due to dependencies or the cause isn't clear, document what you've found and ask for help in the release Slack channel. The "Heart of Gold - Flux" team can assist with resolving CI issues that block release work.
-<h3 id="can-i-start-over-id">Something looks wrong in the final release ZIP. Can I start over?</h3>
+### Something looks wrong in the final release ZIP. Can I start over?
If, after downloading and unzipping the generated artifact, something seems off (e.g., missing files, incorrect changelog, or version mismatch), this usually means:
@@ -45,7 +45,7 @@ If, after downloading and unzipping the generated artifact, something seems off
**Once you know which step failed,** re-run only that step as described in the [Building & Publishing guide](/docs/contribution/releases/building-and-publishing). Make sure to run skipped workflows in the correct order and double-check all configuration (version number, release type, etc.) before proceeding.
-<h3 id="deploy-serious-bug">A serious bug was detected during internal checks / monitoring</h3>
+### A serious bug was detected during internal checks / monitoring
For RC and stable releases, deploying to our staging environment and monitoring for errors is required before the release is made publicly available. If a serious bug is detected during this monitoring period, follow these steps:
@@ -58,7 +58,7 @@ For RC and stable releases, deploying to our staging environment and monitoring
#### How to proceed once the bug fix is merged into the release branch?
-1. **Create a new tracking issue** for the new version (e.g., `-rc.2` if the bug was detected during `-rc.1`, or `x.y.2` if detected while monitoring `x.y.1`) by running the [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/actions/workflows/release-create-tracking-issue.yml) workflow. Do not reuse the existing tracking issue.
+1. **Create a new tracking issue** for the new version (e.g., `-rc.2` if the bug was detected during `-rc.1`, or `x.y.2` if detected while monitoring `x.y.1`) by running the [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/actions/workflows/release-create-tracking-issue.yml) workflow. Do not reuse the existing tracking issue. The new issue is automatically nested under the `[X.Y] Release tracking` parent in Linear.
2. **Follow the release procedure as normal** for the new version.
3. **Publish all draft releases** for the affected version series. Even if the prior version wasn't made publicly available, it must be published along with the valid version. Each version will have its own changelog section.
@@ -67,11 +67,11 @@ For RC and stable releases, deploying to our staging environment and monitoring
If a severe regression or bug is discovered (e.g., checkout failure or unrecoverable data loss):
1. Immediately notify the relevant engineering team(s).
-2. Prepare to do a [Point Release](/docs/contribution/releases/point-releases).
-3. Temporarily move the stable tag on WordPress.org back to the previous known-good version:
+2. If the severity warrants it (e.g., checkout failure, data loss, or other critical impact affecting many stores), temporarily move the stable tag on WordPress.org back to the previous known-good version, so new installs and updates stop landing on the broken version while the fix is being prepared:
- Identify the correct previous version and note its exact number.
- Use the [`Release: Update stable tag`](https://github.com/woocommerce/woocommerce/actions/workflows/release-update-stable-tag.yml) workflow, making sure to check the _Revert_ option to allow downgrading.
- Merge any auto-generated PRs right away.
+3. Follow the [Point Releases guide](/docs/contribution/releases/point-releases) to create a tracking issue, prepare the fix, and ship the patch.
### The release needs to be delayed. What should we do?
diff --git a/docs/contribution/releases/workflows.md b/docs/contribution/releases/workflows.md
index 7712f1059a3..b802115527d 100644
--- a/docs/contribution/releases/workflows.md
+++ b/docs/contribution/releases/workflows.md
@@ -16,7 +16,7 @@ These workflows run automatically on a daily schedule.
| Workflow | Schedule | What it does | When it acts |
| -------- | -------- | ------------ | ------------ |
-| [Release: Assignment](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-assignment.yml) | Daily at 18:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/), assigns the release lead, and creates the parent tracking issue with sub-issues for each release in the cycle. Calls *Create Tracking Issue* for each sub-issue. | ~8 weeks before feature freeze. |
+| [Release: Assignment](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-assignment.yml) | Daily at 18:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/), assigns the release lead, and creates the parent tracking issue along with the four standard sub-issues for the cycle: `beta.1`, `beta.2`, `rc.1`, and the final `.0` release. Calls *Create Tracking Issue* for each sub-issue. Tracking issues for patch releases, extra RCs, or extra betas are **not** created by this workflow; see the note below the "Tracking and analysis" table. | ~8 weeks before feature freeze. |
| [Release: Enforce Feature Freeze](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-code-freeze.yml) | Daily at 18:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/) and creates the release branch from `trunk`, bumps `trunk` to the next dev version, publishes a dev release, cleans up old milestones, and sends Slack notifications. Calls *Bump version number* and *Build ZIP file*. | On the feature freeze date. |
| [Release: Feature highlight notification](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-feature-highlights-notification.yml) | Daily at 09:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/) and sends a Slack reminder to teams about the upcoming feature freeze deadline. | ~1 week before feature freeze. |
| [Release: Open Issue Warning](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-open-issue-warning.yml) | Daily at 18:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/) and looks for open items in release milestones, sending a Slack notification listing them with assignees. | Within 72 hours of a release date. |
@@ -48,7 +48,6 @@ These workflows are triggered automatically by GitHub events such as pull reques
| -------- | ------- | ------------ |
| [Release: Release events proxy](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-release-events-proxy.yml) | Release published or prereleased | Delegates to [`release-new-release-published`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-new-release-published.yml) to run post-release actions: sends Slack notifications, updates the global changelog for stable releases, and calls *Generate Number of Commits and Contributors* for beta releases. |
| [Release checks run](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/tests-on-release.yml) | Release published or edited | Runs the CI test suite against published releases. Also runs nightly on a schedule. |
-| ~~[Release: CFE and PRR issue validation](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-cfe-prr-issue-validation.yml)~~ | Issue labeled with `code freeze exception`, `point release request`, `Approved`, or `Rejected` | ~~Validates Code Freeze Exception and Point Release Request issues, applies labels and milestones to the associated PR, and sends Slack notifications.~~ Being deprecated. |
## Manual workflows
@@ -71,3 +70,13 @@ These workflows are triggered by the release lead during the release process. Th
| [Release: Create Tracking Issue](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-create-tracking-issue.yml) | Creates a Linear tracking issue for a specific release version using the templates in `.linear/`. |
| [Release: Generate Number of Commits and Contributors](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-commits-and-contributors.yml) | Generates release statistics (commit count, contributors list) and sends a Slack notification. |
| [Release: analyze trends (CFEs and PRRs)](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-trends-analysis.yml) | Creates GitHub issues requesting AI analysis of Code Freeze Exceptions and Point Release Requests for a milestone. |
+
+:::note
+Tracking issues for **patch releases, extra RCs, and extra betas** are not created automatically by `Release: Assignment`. Run [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-create-tracking-issue.yml) manually for those. See the [Point Releases](/docs/contribution/releases/point-releases) and [Troubleshooting](/docs/contribution/releases/troubleshooting) guides for context on when each is needed.
+:::
+
+## Deprecated
+
+| Workflow | What it did |
+| -------- | ----------- |
+| [Release: CFE and PRR issue validation](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-cfe-prr-issue-validation.yml) | Validated Code Freeze Exception and Point Release Request issues, applied labels and milestones to the associated PR, and sent Slack notifications. The PRR/CFE process is no longer part of the standard flow; see the [Point Releases guide](/docs/contribution/releases/point-releases) for current practice. |