The WordPress coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:
Found a bugbugA bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.?Create a ticket in the bug tracker.
This guide will clarify how to handle the Editor (GutenbergGutenbergThe Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/) portion of a major WordPress release. This is a living document. You are encouraged to leave feedback and provide updates.
Here’s a list of the significant time-critical tasks, sorted by when they should be completed. More details about each task are available later in this document.
Two months before BetaBetaA pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 1
Set up the release project board on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Audit experimental APIs in Gutenberg
Create an overview issue of PHPPHPThe web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher changes that need to be manually added in CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress.
One month before Beta 1
Update trunktrunkA directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. with the latest Gutenberg packages and PHP changes
Create a tracking issue for dev notesdev noteEach important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase., which should be published by RC1 and require plenty of time to wrangle
Between Beta 1 and the last RCrelease candidateOne of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta).
TriagetriageThe act of evaluating and sorting bug reports, in order to decide priority, severity, and other factors. recent bugbugA bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. reports and unlabelled issues for critical regressions
Fix all critical regressions and as many bug fixes related to the release as possible
Start package update/core patchpatchA special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. process
At the start of each release cycle, a planning roundup post should be published (example from 6.3) that details key milestones leading up to the major WordPress release. This post includes deadlines for all Beta and RC releases and the names of all release team members.
Gutenberg releases happen biweekly, so you can determine which Gutenberg release is scheduled closest to Beta 1 and, if necessary, rearrange the pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party release date to align better with Beta 1.
Ideally, this last Gutenberg RC should be released 4-5 days before Beta 1. This schedule will give plenty of time for any bugs to be identified and fixed while allowing the team to publish npm packages and update their versions in Core.
If a contributor wants to include a new Editor feature in the major releasemajor releaseA release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope., it must be included in this last Gutenberg RC. Therefore, once you have identified the final Gutenberg release, share it in the #core-editorSlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel and during the weekly Editor Weekly Chat meeting to allow contributors to prepare appropriately.
A Roadmap post identifies the features, enhancements, and bug fixes slated for the current major release (example from 6.3). The creation of this resource is a collaborative effort between release leads and contributors.
You should become familiar with this post if you are an Editor Tech or Triage lead. It’s an excellent resource for knowing what should be included in the release. It’s also invaluable for determining which reported issues are related to the release and which need to be added to the project board. More on that below.
Creating a “project board” for the major release in Gutenberg’s GitHub repository has become a best practice. This board helps coordinate tasks and should contain all issues and PRs related to the release.
Click on the “Use this template” buttonto create a new board
Update the title of the board using the format “WordPress X.X Editor Tasks”
Update the “Punted to 6.X.1” and “Punted to 6.Y” column titles
Navigate to the Gutenberg Projects page and click the “Link Project” to link the newly created project to the Gutenberg repository.
The template will contain the following columns:
Triage – All new issues enter the board in this column. Release leads then decide if the issues belong in the “Todo”, “In discussion / Needs decision” or other columns as needed. Issues can also be removed from the board completely if there is a general consensus among leads.
In Discussion / Needs Decision – Contains issues or PRs that the team needs more time to consider for the release. Some possible reasons for not having a conclusion are:
The problem was critical but was impossible to replicate, so it’s a matter of waiting for more information to understand the specific conditions where the problem happens.
It still needs to be clarified if the issue is a regressionregressionA software bug that breaks or degrades something that previously worked. Regressions are often treated as critical bugs or blockers. Recent regressions may be given higher priorities. A "3.6 regression" would be a bug in 3.6 that worked as intended in 3.5. or not, or it is not clear if the issue is a bug or desired behavior.
The issue requires a complex testing setup, and replicating it takes time. In this case, you should write a comment upon finding the issue, saying what must be done to test it. This helps make it easier for others to help with testing. If needed, you may need to add the “needs-testing” label as well. Once the issue is tested and confirmed, move it to the “Todo” column.
Todo – Contains issues that the team has determined should be fixed by the release but do not have a PR associated with them.
In Progress – Contains issues that the team has determined should be fixed by the release and have a PR associated with them.
Needs Review – Contains PRs associated with issues in the “In Progress” columns that are not yet merged and need review.
Needs Core Commit – Contains PRs that need an additional Core commit, which the Editor Tech Leads determine.
Done – Contains issues and PRs that are complete.
Punted to 6.X.1 – Contains issues and PRs that the team has determined should be punted to the next minor releaseMinor ReleaseA set of releases or versions having the same minor version number may be collectively referred to as .x , for example version 5.2.x to refer to versions 5.2, 5.2.1, 5.2.3, and all other versions in the 5.2 (five dot two) branch of that software. Minor Releases often make improvements to existing features and functionality..
Punted to 6.Y – Contains issues and PRs that the team has determined should be punted to the next major release.
After you have created the project board, make sure to review the project board from the prior release and migrate over all punted issues and PRs. Remove each from the old project board once you have moved everything over.
Note that “punting” is a sports metaphor from American football. If you puntpuntContributors sometimes use the verb "punt" when talking about a ticket. This means it is being pushed out to a future release. This typically occurs for lower priority tickets near the end of the release cycle that don't "make the cut." In this is colloquial usage of the word, it means to delay or equivocate. (It also describes a play in American football where a team essentially passes up on an opportunity, hoping to put themselves in a better position later to try again.) something, you decide not to include it in the current release, and it’s “punted” to the next minor or major release.
Since the project board will be a place that meetings reference and people bookmark, it’s important to take steps to keep it current and useful for others. The following actions are recommended and can be divided up:
The release leads, and members of the Gutenberg Triage Team should regularly review new Gutenberg issues and add those relevant to the current release to the project in the “Triage” column.
Sort items in “Todo” column by priority. Keep the highest priority items at the top so more people will see them. Issues with the Regression label should always be at the top.
When an issue gets a PR associated, move the issue to the “In Progress” column and add the PR to the “In Review” column.
PRs associated with issues on the board also need to be added to the project board.
Ensure all issues and PRs are properly labeled.
Share the link to the project board regularly in the Editor Weekly Chat meetings and the #core-editor Slack channel as helpful. This will get people in the habit of checking the project board and for them to share it in turn. You can also encourage contributors with permission to add issues they think are important to the “Triage” column. The Editor Triage leads will handle it from there.
During the Beta release cycle, the weekly triage sessions in the #core-editor Slack channel are suspended. They are replaced with asynchronous triage sessions to specifically handle the project board, especially the “Triage” and “In Discussion / Needs Decision” column. These meetings allow the Editor Tech and Triage leads to efficiently “vote” on how issues and PR should be prioritized and managed.
Often a release team consists of members across various time zones, so an asynchronous meeting allows everyone to participate when convenient.
You create an initial announcement for the meeting in the #core-editor Slack channel and add each PR and issue in a thread. The leads then vote using emojis and can add additional comments in the thread.
These meetings are held publicly so all other contributors can see the decisions being made. Below is an example of a meeting for 6.3, but feel free to modify it as needed.
For items in the “Todo” column, it’s recommended that you find someone assigned in time before the release milestones. The easiest way to do this is to ask in the #core-editor channel for volunteers to pick tasks from that column. If no one volunteers, you will need to research to find contributors familiar with the items needing help (checking previous Gutenberg PRs can be helpful here) and ask them if they can take on that work or help another person do so.
If issues seem critical to the release but nobody is picking them up, alert the Editor Tech Leads as soon as possible.
The release roadmap post lists the features considered a top priority for each release. Special attention should be given to these to ensure they land in Core in a timely and stable manner.
It’s good to review Gutenberg release posts too. They will give you a sense of all the features currently being worked on, as well as smaller enhancements and bug fixes.
For experimental features in particular, it helps to pingPingThe act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” the developers working on them and discuss whether they are ready to be included in Core.
Outside of the main features of a release, there are often in progress additional features that are still helpful to include to help complement the release as a whole. This might include features that were missed in the last major release as well as simply more minor updates to include. Whether you can include these depends on various factors, including but not limited to the following:
What features might be important to finish?
What is the complexity/risk of each feature?
How complementary they are to the main features of the release.
Are there contributors actively working on the feature?
For any feature you do decide to add, remember to add it to the release project board in GitHub. Do your best to help move these features along, whether through helping with PRs, unblocking the original authors, etc.
If there’s an additional feature you want to include that you don’t have anyone actively working on, please ask for volunteers in the #core-editor meetings. If you know of any developer who may be a good person to work on a given feature, it’s often best to ping them directly and ask if they can do so. Even if they can’t, they may be able to point you to someone who can.
As with any release, there will be tough calls that must be made. What follows are the best steps you can take to communicate effectively and, if needed, make the call to not include a feature in a release:
Communicate as early as you can with the people working on the feature that it is at risk of not being included and clearly state what needs to be done by when in order to change that.
Give updates to the release squad as things do or do not progress alongside updates in #core-editor meetings.
Since the private-apis system was created in early 2023, the system for managing experimental APIs has changed. Everything that is unstable or not meant to be available as a public APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is kept private.
However, there are still many older experimental APIs in Gutenberg that can be recognized by the __experimental prefix. These can be functions, properties, or variables found throughout the codebase. For every release, it’s customary to audit these and check if any are ready for stabilization. Stabilization must be done before the Beta 1 release (ideally at least two weeks beforehand), as renames during the Beta phase are not possible.
It can help to group related experimental APIs from the report and any information manually collected to get a sense of what’s currently in place. From there, use git blame to know which contributors were involved in each API to ping them and inquire if the API can be stabilized. You can then create a new overview issue in GitHub that lists out a checkbox for each API where you can easily see whether a decision has been made around stabilizing the API.
Check out this handbook page for more context on dev notedev noteEach important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. best practices.
You can check all PRs labeled with Needs Dev Note to know what needs a dev note. You might find that there are more PRs than you can feasibly write individual posts for without overwhelming the community with information. In this case, group PRs with the same label and propose a dev note for each group.
Once you have a sense of the needed dev notes, create a GitHub issue (previous example) detailing the plan:
What posts need to be done
What are the essential sections of each post
What PRs should be included in each
When doing so, ping the people with PRs needing dev notes to contribute to this effort. Ideally, your job should be to wrangle the updates from each PR author and plan the timeline for sharing each dev note so that you don’t share too many in a short time. Sharing target dates is recommended to help space out and plan appropriately.
Keep in mind that dev notes are extremely collaborative efforts requiring help from many people. This might mean that some people you need information from didn’t see the ping the first time or are unavailable to write a note. It’s okay and expected that follow-up will be required, likely in the form of additional pings or even DMs in Slack to get updates. When each section is done for each dev note, you can check the checkbox to show progress and help others see what’s left.
As you compile each dev note, particularly if you combine multiple PRs into one dev note, ensure you share the posts with those involved for review so everyone is on the same page. Once there’s consensus, share the dev notes with those involved in the major release squad for a final review.
Because months pass between Core releases, it’s important to regularly check in on GitHub to triage issues (ideally weekly), particularly new ones that are unlabeled. The key is not to miss anything that might be critical.
Outside of reviewing unlabeled issues, it’s important to review all reported issues since a major release occurred to spot any critical issues that need to be resolved. While this is primarily the job of the Editor Triage Leads, this is a great task to divide up among other contributors.
When reviewing bug reports and trying to determine how critical they are, it becomes even more important to know the version that introduced the particular bug. For example, you might find a bug introduced many WordPress versions ago, but it doesn’t have many recent comments. This is a good sign that the bug is not critical to fix.
After the first Beta, you can only include bug fixes for issues that regressed during the Alpha phase. It’s essential to know if the bug you are reviewing affects the latest stable release of WordPress. This might require multiple testing environments with different setups to determine the impact, for example, the current version of WordPress, the Beta version, and the latest version of Gutenberg. It might also mean following up with those who reported issues to get more information about their particular setup, like if they are using Gutenberg and, if so, what version.
No additional features or enhancements can be included after this milestone. Exceptions for enhancements to new features can be made, but these must be discussed with the release team. If approved, a TracTracAn open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.ticketticketCreated for both bug reports and feature development on the bug tracker. should be created for each feature with the type “task (blessed)”. All enhancements to these tasks must be finished before RC1.
To make the Beta 1 release process easier, start updating trunk as early as possible.
As the volume of changes for each release is quite high, it helps to start adding new features to Core trunk as early as possible in the cycle. This means both updating the @wordpress npm packages used by Core and manually syncing any PHP changes from the lib and phpunit folders in Gutenberg.
Make sure any experimental features are behind feature flags in Gutenberg, so they don’t accidentally get included in Core.
In order to safely update the npm packages in Core, experimental Gutenberg features that aren’t slated for inclusion in Core must be safely behind feature flags. IS_GUTENBERG_PLUGIN flag is commonly used for this purpose, or a specific feature filterFilterFilters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. may be used, such as in this example for the interactivity API.
List PHP changes to be manually synced.
Create an overview issue of all the changes from the lib and phpunit folders that need to be manually synced. Using git blame, find the authors of those changes and ping them to create Core PRs for each change.
The PHP files in block-library package don’t need to be manually synced, as they are auto-generated in Core based on the npm package.
After the first Beta, there are weekly Beta releases leading up to the Release Candidaterelease candidateOne of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta). (RC). At this point, there are three main tasks to take care of: triage new issues, cherry-pick PRs for inclusion in the release, and update both package and Core paths.
Throughout the week, you should closely monitor all new Gutenberg issues since the last release to ensure no regressions have been found. If you identify regressions, immediately add those issues to the “WordPress X.X Editor Tasks” project board in the “Triage” column for further investigation.
When PRs are submitted for issues on the project board, add the Backport to WP Beta/RC label to the PR so you can track what needs to be included in the next Beta release.
Outside of looking for issues that need to be added to the project board, it’s important to ensure all issues on the board are assigned to someone to resolve, especially with Beta releases occurring on a weekly schedule.
Once PRs on the project board are completed, they must be backported into the Core to be available on the next Beta or RC version. Follow this process:
If a wp/x.x (use the correct WordPress release number) has yet to be created, create it and push it to the remote repository.
Review all PRs labeled Backport to WP Beta/RC. Verify that everything looks good and that the PRs are not “too risky” to go into a Core release. Refer to the Editor Tech Leads and Core Tech Leads for guidance.
Remove the label from any PRs that were closed without merging. Otherwise, they’ll mess with the automated cherry-pick script.
Create a branchbranchA directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". based on the format of wp/x.x
Cherry-pick each PR into the newly created branch.
There is cherry-picking automation available via npm run other:cherry-pick. It finds all merged PRs with the Backport to WP Beta/RC label, cherry-picks them, and asks whether to automatically comment on the relevant PRs and push the branch to GitHub. You can also pass another label as the first argument.
You can also do it manually. The hash of the commit is extracted from the GitHub pull request page. To avoid merge conflicts, cherry-pick the commits in the same order they were made in trunk. The order will likely not be the same as the PRs appear in the label view, so double-check the merge date and refer to the commit history. You can combine multiple commits in a single command, like so: git cherry-pick c82094d8389b1756f05d4079ba98e4ee25961502 && git cherry-pick 548e600f14924d7fcfdb5250f45f718d3759d022 && git cherry-pick b72b41e27f008540410c45023b655c8ee20b67ae
Merge conflicts may still happen. If they do, you will have to resolve them. If you need help with this, message the PR author for assistance.
Sometimes a conflictconflictA conflict occurs when a patch changes code that was modified after the patch was created. These patches are considered stale, and will require a refresh of the changes before it can be applied, or the conflicts will need to be resolved. happens because the cherry-picked commit depends on another commit that wasn’t included in the release branch. This may be an accidental omission, so it’s good to double-check by pinging the authors of the PRs.
After manually solving a conflict, return to the original PR and remove the Backport to WP Beta/RC label.
Create a pull request on GitHub from the branch you created into the wp/x.x branch.
Verify that continuous integration is executed with success for the PR.
If there were merge conflicts to solve, you should ping the authors of the conflicting commits to double-check they were solved correctly. Otherwise, if all tests pass on CI, merging the PR to the release branch is fine.
After merging, run the package publish task from the release branch:
On this page, click the “Run workflow” button and choose the release branch. The release type should be wp, and the release version should be added underneath.
Once the workflow appears in the list below, click through to authorize it. If you don’t have gutenberg-core access, ask someone who does to approve it for you.
This workflow will publish the npm packages with a dist tagtagA directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) corresponding to the release, which can then be used to select the correct package versions in Core.
Once the npm packages are published, they can be updated in the wp-develop repo using the automated script: npm run sync-gutenberg-packages -- --dist-tag=wp-<VERSION>. Remember to use the same dist-tag as the newly released @wordpress packages, e.g. wp-6.2 for the 6.2 major version.
Then run npm run postsync-gutenberg-packages in the wordpress-develop folder. It includes any new Gutenberg blocks in Core and runs the required builds.
If any new front-end scripts have been added to dynamic blocks, these need to be referenced manually in the webpack block config.
In your local WordPress development environment, check that the issues that were supposed to be resolved are in fact resolved.
Create a Trac ticket for the package updates in Core.
Submit a PR against wordpress-develop to ensure the continuous integration tests pass, and add the Trac ticket number to the description. This ensures the PR gets linked to the ticket, and the patch will then be created automatically (previous example).
Ask for reviews. During the Beta stage, a review is recommended but not mandatory. A double signoff by two different committers is required during the RC process. If you are a committercommitterA developer with commit access. WordPress has five lead developers and four permanent core developers with commit access. Additionally, the project usually has a few guest or component committers - a developer receiving commit access, generally for a single release cycle (sometimes renewed) and/or for a specific component. and are confident with the changes, you can be one of the approvers and add the “dev-feedback” keyword.
When approved, commit the patch or coordinate with a committer to ensure it’s committed if you are not a committer.
If a branch for the WordPress release already exists, backporting the commit from trunk to the release branch is required.