Skip to content

Docs: Expand the back-porting to WP Core guide #80593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
scruffian merged 4 commits into from
Jul 27, 2026
Merged

Docs: Expand the back-porting to WP Core guide #80593

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7799240
Docs: Expand the back-merging to WP Core guide
scruffian Jul 22, 2026
06fe513
Apply suggestions from code review
scruffian Jul 22, 2026
4fe8f2b
Potential fix for pull request finding
scruffian Jul 22, 2026
3ba4996
Potential fix for pull request finding
scruffian Jul 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions docs/contributors/code/back-merging-to-wp-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,69 @@ There are however certain exceptions to that rule. PRs with the following criter
- Does not contain changes to PHP code.
- Has label `Backport from WordPress Core` - this code is already in WP Core and is being synchronized back to Gutenberg.
- Has label `Backported to WordPress Core` - this code has already been synchronized to WP Core.
- Has label `No Core Sync Required` - the changes do not need to be synced to WP Core.

## How to back-merge a PR

The back-merge itself is a pull request against [`WordPress/wordpress-develop`](https://github.com/WordPress/wordpress-develop) that mirrors the PHP changes from the Gutenberg PR. This can be prepared from a local checkout, or by using the GitHub API from your own fork of `wordpress-develop`.

### 1. Identify the files to back-merge

Fetch the changed files from the Gutenberg PR and filter for the paths listed under [Criteria](#criteria) above. Skip anything that matches the ignored files/directories.

### 2. Map each Gutenberg path to a WP Core path

Most files fall into one of these patterns:

**Direct-sync files** — kept byte-for-byte identical to their WP Core counterparts. Copy the file across.

| Gutenberg | wordpress-develop |
| --- | --- |
| `lib/<subpath>/*.php` | `src/wp-includes/<subpath>/*.php` |

For example, `lib/block-supports/layout.php` maps to `src/wp-includes/block-supports/layout.php`.

**Compat shim files** — files under `lib/compat/wordpress-X.Y/` contain compatibility shims for older WordPress versions. Do not copy the whole file. Instead, port the relevant change into the equivalent WP Core file (often under `src/wp-includes/`):

| Gutenberg | wordpress-develop |
| --- | --- |
| `lib/compat/wordpress-X.Y/<filename>` | `src/wp-includes/<filename>` (common case) |

The destination sometimes lives in a subdirectory that isn't reflected in the Gutenberg path. Search WP Core for the file or class name to locate it.

**Class files with `-gutenberg` in the name** — strip the Gutenberg-specific naming when translating:

| Gutenberg | wordpress-develop |
| --- | --- |
| `lib/class-wp-<name>-gutenberg.php` | `src/wp-includes/class-wp-<name>.php` |
| `lib/media/class-gutenberg-rest-<name>.php` | `src/wp-includes/rest-api/endpoints/class-wp-rest-<name>.php` |

**Aggregator files** — files like `lib/media/load.php` have no direct WP Core counterpart. Each change fans out to the appropriate WP Core file (a filter added on `admin_init` may land in `src/wp-includes/default-filters.php`, a function body change in `src/wp-includes/media.php`, and so on). Read the diff and apply each piece where it belongs.

**PHP unit tests**:

| Gutenberg | wordpress-develop |
| --- | --- |
| `phpunit/<subpath>/<name>-test.php` | `tests/phpunit/tests/<subpath>/<name>.php` |

Strip the `-test` suffix. Class-based test files (`class-wp-<name>-test.php`) may land in a different subdirectory than their Gutenberg location; search WP Core by class name.

### 3. Find the appropriate Trac ticket

Every WP Core PR must reference a [Trac ticket](https://core.trac.wordpress.org/). Reuse an existing ticket if one applies, or create one before opening the PR.

### 4. Open the wordpress-develop PR

Push the changes to a branch on your fork of `wordpress-develop` and open a pull request against `trunk`. A common naming convention is:

- Branch: `backport/<gutenberg-pr-number>-<short-description>`
- Title: `<Component>: <Description> (backport GB #<gutenberg-pr-number>)`

The PR body should reference the Gutenberg PR and the Trac ticket. See existing examples such as [WordPress/wordpress-develop#12324](https://github.com/WordPress/wordpress-develop/pull/12324) or [WordPress/wordpress-develop#12516](https://github.com/WordPress/wordpress-develop/pull/12516).

### 5. Add a backport-changelog entry

After the wordpress-develop PR is open, add a corresponding markdown file to the Gutenberg PR at `backport-changelog/<wp-version>/<wp-develop-pr-number>.md`. See [backport-changelog/readme.md](https://github.com/WordPress/gutenberg/blob/trunk/backport-changelog/readme.md) for the exact format. The CI check on the Gutenberg PR will fail until this file exists (or a skip label is applied).

## Further Reading

Expand Down
Loading