Commit e9700729a79 for woocommerce
commit e9700729a79280f4ee07e377fe64d3ef08c74c0e
Author: Cvetan Cvetanov <cvetan.cvetanov@automattic.com>
Date: Thu Aug 6 09:54:22 2026 +0300
Add common failure scenarios to the release troubleshooting guide (#67304)
* Add common failure scenarios to the release troubleshooting guide
* Add code freeze, build blocker, and stable tag revert scenarios
* Replace em dashes in the new troubleshooting scenarios
* Update troubleshooting scenarios to current release automation
diff --git a/docs/contribution/releases/troubleshooting.md b/docs/contribution/releases/troubleshooting.md
index 0c0ff8a5421..b6eb2944ee9 100644
--- a/docs/contribution/releases/troubleshooting.md
+++ b/docs/contribution/releases/troubleshooting.md
@@ -24,13 +24,25 @@ This page provides guidance for troubleshooting and recovering from issues that
⚠️ _Do not re-run any workflows until you understand the cause of the failure._ Re-running without fixing the root issue can make things more complicated.
+### The changelog workflow fails with "Your local changes would be overwritten"
+
+Backport the updated `tools/monorepo-utils/dist/index.js` from `trunk` to the release branch and re-run the workflow. This happens on the rare occasions that file (a committed build artifact) is updated on `trunk`, making the two branches diverge during the workflow's checkout.
+
### CI is failing on a release-related PR
During the release process, you may encounter CI test failures on release-related PRs. These failures sometimes occur because test fixes were merged to trunk but not backported to the release branch before it was cut.
-1. **Identify the cause**: Check if the failing tests pass on trunk. If they do, the fix likely needs to be backported.
-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.
+1. **Check [GitHub's status page](https://www.githubstatus.com/) first**: PRs stuck on _"Waiting for status to be reported"_ or entire batches of failing jobs are often caused by a GitHub Actions incident, not by the release.
+2. **Identify the cause**: Check if the failing tests pass on trunk. If they do, the fix likely needs to be backported.
+3. **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.
+4. **Re-run before assuming a regression**: If nothing relevant changed since the last green run, the failure is likely flakiness. If a test keeps flaking on the release branch, file an issue for the owning team and don't let it block the release.
+5. **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.
+
+Note that a failing check that is not required and is clearly unrelated to the change (for example, a comparison job that references code only present on trunk) does not have to block merging a release-related PR. When in doubt, ask in the release Slack channel before merging over a failure.
+
+### The "Build ZIP file" workflow refuses to build because of open PRs
+
+The workflow checks two criteria: open PRs based on the release branch, and open PRs carrying the release milestone (on any base branch). Draft PRs are ignored, so switching a PR to draft is a quick way to bypass the check temporarily. The workflow's error message lists the offending PRs: merge the ones that belong in the release, and close stale or redundant ones (including auto-generated backport PRs whose changes are already on the release branch).
### Something looks wrong in the final release ZIP. Can I start over?
@@ -50,6 +62,13 @@ 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.
+### The "Upload release to WordPress.org" workflow failed
+
+When this workflow fails, it reports the state of the SVN side in the run summary; check it before doing anything else. Two things worth knowing:
+
+- **If the SVN tag for the version exists, the upload succeeded** even though the run is red: continue with the release process. Re-running against an existing tag fails validation.
+- **`E175013: Access to '/!svn/me' forbidden` means invalid SVN credentials**: update the SVN credentials secret from the secret store and re-run.
+
### 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:
@@ -75,9 +94,17 @@ If a severe regression or bug is discovered (e.g., checkout failure or unrecover
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.
+ - Merge any auto-generated PRs right away: the revert opens PRs updating the `Stable tag` in `readme.txt` on `trunk` and the affected release branches, and the next build and upload will fail if the stable tag doesn't match SVN.
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 is out, but sites don't see the update yet
+
+This is usually not a problem:
+
+- WordPress checks for plugin updates roughly every 12 hours by default, so it can take a while for a newly published release to be offered on any given site.
+- WordPress.org now also applies a delay of up to 24 hours before offering new releases ([announcement](https://wordpress.org/news/2026/06/pts/)), so the update may not appear immediately even after a site's update check runs.
+- Only the `Stable tag` in the `readme.txt` on WordPress.org's SVN `trunk` controls what the updater offers. The `readme.txt` bundled inside a released ZIP always shows the previous version as stable: that's expected, since published releases are frozen and can't be edited.
+
### The release needs to be delayed. What should we do?
1. Create an internal Slack thread to communicate with the engineering teams as well as Dev Advocacy. This also provides an opportunity for teams to share any additional context and verify or challenge schedule changes.