Skip to content

Commit

Permalink
Backport docs: update and format (#63830)
Browse files Browse the repository at this point in the history 
* updating docs surrounding backports and PHP changes

* minor edits

* Remove whitespace

* Update backport-changelog/readme.md

Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: noisysocks <noisysocks@git.wordpress.org>
  • Loading branch information
@ramonjd @andrewserong @noisysocks
4 people authored Jul 23, 2024
1 parent d625b3d commit c7b263d
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 12 deletions.
63 changes: 55 additions & 8 deletions backport-changelog/readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,63 @@
# Core Backport Changelog

Any PR that makes changes to be backported to [core](https://github.com/WordPress/wordpress-develop) should log a core PR here. It's possible to have multiple Gutenberg PRs link to a single core backport PR. The core backport PR can remain open as long as wanted/needed. The entries are sorted by core release (in folders), and each entry should be an md file with the core PR number as the file name, and the link to the Gutenberg PR in the file content. The file content should start with the core PR URL, followed by a Markdown list of Gutenberg PRs (see example). Files are used to avoid rebase conflicts.
If you've changed or added files to the Gutenberg plugin, you'll need to confirm whether the changes are to be backported to [WordPress Core](https://github.com/WordPress/wordpress-develop), and therefore featured in the next release of WordPress.

If you think a file path is wrongly flagged as needing a core backport PR, you can add it to the list of exceptions in `.github/workflows/check-backport-changelog.yml`.
On open Gutenberg PRs, changes to certain files are flagged as requiring backporting to WordPress Core, for example, PHP files in `/lib` and PHP unit tests.

## Example
These changes must have a corresponding Core PR before they can be merged to Gutenberg trunk.

To create a Core PR, first create a [new Trac ticket](https://core.trac.wordpress.org/newticket) and submit a pull request to the [WordPress Core GitHub repository](https://github.com/WordPress/wordpress-develop).

The Core PR can remain open as long as is required.

For more information on how to create a Core PR, see the [WordPress Core Handbook](https://make.wordpress.org/core/handbook/contribute/git/github-pull-requests-for-code-review/).

## How to add a Core Backport PR to the changelog

After you create Core PR, you'll need to create a corresponding markdown file, and place it within the appropriate release subdirectory.

The filename is the Core PR number.

For example, if your Core PR number is `1234` and is slated to be part of the WordPress 6.9 release, the filename will be `1234.md`, and will be placed in the `/backport-changelog/6.9` directory.

The content of the markdown file should be the Github URL of the Core PR, followed by a list of Gutenberg PR Github URLs whose changes are backported in the Core PR.

A single Core PR may contain changes from one or multiple Gutenberg PRs.

### Examples

Let's say the next WordPress release is 6.9. You have two Gutenberg PRs — `1111` and `2222` — whose changes are backported in a single Core PR, number `1234`.

First you would create a file named `1234.md` in the `/6.9` folder.

If the `/6.9` folder doesn't exist, create it.

Then you would add the following content to your new file:

Path: `{wp-release-number-x.x}/{core-pr-number}.md`, e.g. `6.6/1234.md`.
File content:
```md
https://github.com/WordPress/wordpress-develop/pull/{core-pr-number}
https://github.com/WordPress/wordpress-develop/pull/1234

* https://github.com/WordPress/gutenberg/pull/{first-gb-pr-number}
* https://github.com/WordPress/gutenberg/pull/{second-gb-pr-number}
* https://github.com/WordPress/gutenberg/pull/1111
* https://github.com/WordPress/gutenberg/pull/2222
```

If `1234.md` already exists, you would add the Gutenberg PRs to the list in the existing file.

## Why use individual files?

For the backport changelog, Gutenberg uses individual files as opposed to a single changelog file to avoid rebase conflicts.

## Exceptions

Some Gutenberg PRs may be flagged as needing a core backport PR when they don't, for example when the PR contains minor comment changes, or the changes already exist in Core.

For individual PRs, there are two Github labels that can be used to exclude a PR from the backport changelog CI check:

- `Backport from WordPress Core` - Indicates that the PR is a backport from WordPress Core and doesn't need a Core PR.
- `No Core Sync Required` - Indicates that any changes do not need to be synced to WordPress Core.

If there are specific file or directory changes that should **never** be flagged as requiring a Core backport PR, you can add it to the list of exceptions in [.github/workflows/check-backport-changelog.yml](https://github.com/WordPress/gutenberg/tree/trunk/.github/workflows/check-backport-changelog.yml).

## Where to get help

If you're unsure, you can always ask the Gutenberg Core team for help on the Gutenberg PR `@WordPress/gutenberg-core` or via the #core-editor channel in [WordPress Slack](https://make.wordpress.org/chat/).
8 changes: 4 additions & 4 deletions lib/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -192,12 +192,12 @@ Existing comments in `lib/load.php` should act as a guide.

## When to sync changes to Gutenberg PHP with Core and vice versa

If you've changed or added PHP files to the Gutenberg plugin, you'll need to confirm whether the changes are to be synced to WordPress Core, and therefore featured in the next release of WordPress.
On open Gutenberg PRs, changes to certain files are flagged as requiring syncing (also called "backporting") to WordPress Core, for example, PHP files in `/lib` and PHP unit tests.

The Gutenberg GitHub pull request in question should be labeled with the `Needs PHP backport` label if the changes are to be synced to Core.
The CI checks will indicate whether you need to create a Core PR. If you do, you'll need to create a corresponding markdown file and place it within the appropriate release subdirectory in the [Core backport changelog](https://github.com/WordPress/gutenberg/tree/trunk/backport-changelog/).

If so, it is recommended to create a [new Trac ticket](https://core.trac.wordpress.org/newticket) and submit a pull request to the [WordPress Core GitHub repository](https://github.com/WordPress/wordpress-develop) soon after your pull request is merged.
For more information, please refer to the [Core backport changelog documentation](https://github.com/WordPress/gutenberg/tree/trunk/backport-changelog/readme.md).

So too, if you've made changes in WordPress Core to code that also lives in the Gutenberg plugin, these changes will need to be synced (often called "backporting") to Gutenberg. The relevant Gutenberg GitHub pull request should be labeled with the `Backport from WordPress Core` label.
So too, if you've made changes in WordPress Core to code that also lives in the Gutenberg plugin, these changes will need to be synced to Gutenberg. The relevant Gutenberg GitHub pull request should be labeled with the `Backport from WordPress Core` label.

If you're unsure, you can always ask for help in the #core-editor channel in [WordPress Slack](https://make.wordpress.org/chat/).

1 comment on commit c7b263d

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Flaky tests detected in c7b263d.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/10054687162
📝 Reported issues:

Please sign in to comment.