Docs: Expand the back-porting to WP Core guide - #80593
Conversation
Add a "How to back-merge a PR" section with the step-by-step procedure that was previously tribal knowledge: path mapping rules (direct-sync, compat shims, class renames, aggregators, tests), the Trac ticket requirement, the wordpress-develop PR conventions, and the backport-changelog step. Also add `No Core Sync Required` to the skip-label list; the label already exists but was missing from this doc.
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Co-authored-by: Ben Dwyer <ben@scruffian.com>
There was a problem hiding this comment.
Pull request overview
Expands the contributor documentation for back-merging Gutenberg PHP changes into WordPress Core by adding a step-by-step procedure and common path-mapping patterns, so contributors don’t have to reverse-engineer the process from prior backports.
Changes:
- Adds
No Core Sync Requiredto the list of labels that exempt a PR from requiring a Core sync/back-merge. - Introduces a “How to back-merge a PR” section with a numbered workflow (identify files, map paths, Trac ticket, Core PR, backport-changelog entry).
- Adds path-mapping tables and links to example
wordpress-developPRs for cross-checking.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
Flaky tests detected in 3ba4996. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29952567704
|
scruffian
changed the title
What?
Enrich
docs/contributors/code/back-merging-to-wp-core.mdwith the step-by-step procedure that experienced contributors have accumulated but that hasn't been written down anywhere.Why?
Today the doc explains when a PHP change needs a Core back-merge but not how to do it. Newer contributors have to reverse-engineer path mappings, PR conventions, and the backport-changelog step from prior PRs. This PR captures the procedure in one place.
How?
The doc gains:
No Core Sync Requiredadded to the skip-label list (the label already exists, it just wasn't mentioned here).lib/<subpath>/*.php→src/wp-includes/<subpath>/*.php)lib/compat/wordpress-X.Y/*.php→src/wp-includes/*.php, apply-diff only)-gutenbergin the namelib/media/load.php)phpunit/<subpath>/<name>-test.php→tests/phpunit/tests/<subpath>/<name>.php)No existing content is removed; the "Criteria" and "Pull Request Criteria" sections are unchanged.
Testing Instructions
Use of AI Tools
This PR was drafted with Claude Code (Anthropic's Sonnet 4.6). The doc content is derived from real backport PRs and the existing make.wordpress.org syncing guidelines. Per the WordPress AI Guidelines, the human author takes responsibility for the content.