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 our bug tracker.
A Developer note (or “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.” for short) is a blogblog(versus network, site) post on the Making WordPress Core blog that details a technical change in an upcoming release and what developers need to know about that change.
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. are an important part of the WordPress CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. release cycle. They keep the developer community informed by calling out changes that could impact how they build on WordPress, and supplements inline documentation by explaining the problems, solutions, best practices, and edge cases related to the change.
The best dev notes are clear, concise, and complete.
For each release, tickets that may need developer notes are given the needs-dev-note keyword on TracTracAn open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.. When a note has been published for a ticketticketCreated for both bug reports and feature development on the bug tracker., that keyword is replaced with the has-dev-note keyword and a link to the note is included in a comment.
It’s important to remember that not all tickets in a milestone marked needs-dev-note on Trac end up being committed and included in that release.
For that reason, care should be taken to only write notes for tickets and changes once it becomes clear that the changes will be included in the release. Usually, that means tickets with the closed status (and sometimes reopened) are where the focus should be.
The hierarchy for who should author a dev note is as follows:
Someone with deep, working knowledge of the changes. This is usually the 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. that made the change, a component maintainer that helped craft/test the changes, or any other contributor that helped push that change forward.
Someone with a good technical foundation that did not work on the change, but can review the code changes in detail to convey the right message.
Someone that is less technical, but is comfortable interviewing or asking someone in the above groups questions about the changes in order to have the information needed to write the note.
Each note will be unique, but every dev note should clearly define a problem that is being solved, how that problem was solved, and what developers need to know about the related changes. It usually contains a mix of the following:
Clear identification of a problem
Description of why this is problematic
Are developers currently solving the problem in a less than ideal way?
Are there established patterns in the wild within plugins and themes addressing this problem already?
Documents current practices or usage, and how the current state of the code base may contribute to the issue.
Describes what the ideal behavior would be and why,
Explains the changes made to achieve the desired behavior/outcome
Provides examples for how to correctly use the function/feature/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. after these changes (establish a best practice)
Identifies backwards compatibility considerations, explains how they were addressed in Core, and how they should be addressed within plugins and themes.
Details possible edge cases that have been identified
Links to additional reading materials about the change as necessary, such as Trac or 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/ tickets, changesets, past dev notes, past posts on Make blogs, etc.
Sometimes, there are a large handful of changes that deserve to be called out, but are not detailed enough to warrant individual dev notes. It is more than fine to group multiple changes together in a single dev note.
It is common for component maintainers to publish a single dev note for their component to detail several different changes. It’s also common for a more generic “Miscellaneous developer focused changes in X.X” dev note to be published collecting any other remaining smaller changes that should receive a call out.
After researching the ticket but before writing the dev note, ask “Is this a change that needs to be documented at length? Is a one sentence call out sufficient? Or does the change not have anything technical that actually needs to be called out”
The goal is to find a balance between post length, related changes and topics, and the number of dev notes published during a release. More dev notes are better than less. However, it is important to keep in mind that readers should not get tired of the notes and stop reading them.
Every post on a Making WordPress blog should be peer reviewed by at least one other person. For dev notes, each one must have at least two reviewers:
One technical review to verify the accuracy of the post and ensure no important details were missed.
One copy review to help spot grammatical, spelling, and other errors.
After receiving at least two reviews, reach out to the Documentation lead for the release. They will have a high level overview of all dev notes planned or in progress and can help recommend a publish window. It’s important to spread out dev notes to prevent “dev note fatigue”. For example, 3 or more dev notes should not be published on the same day.
A dev note can be published any time during the release cycle. If a change to the code base is committed today, the dev note could be published tomorrow. However, it’s usually best to wait a while after the changes are committed to allow several days for testing.
A handful of WordPress contributors run trunk on their websites in order to test every change after it’s made. On occasion, an issue does come up requiring adjustments to be made. Waiting to publish the dev note ensures that only one note is required for a change, avoiding the potential for confusion and making more work for developers.
However, all dev notes for a changes in a specific release should be published before the first 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). for that release.
To help organize documentation about the upcoming release, a Field GuideField guideThe field guide is a type of blogpost published on Make/Core during the release candidate phase of the WordPress release cycle. The field guide generally lists all the dev notes published during the beta cycle. This guide is linked in the about page of the corresponding version of WordPress, in the release post and in the HelpHub version page. collated and published for every major version of WordPress at the same time as Release Candidate 1. Field Guides are a collection of all relevant dev notes and tickets for an upcoming release.
When writing or reviewing any post on the Making WordPress Core blog, it’s important to remember the Post & Comment Guidelines. The Style and Substance section is particularly important. The guidelines on that page help ensure clear communication with a consistent tone and voice throughout all official WordPress channels.
After writing a developer note, it is also important to make sure it is tagged correctly. The tags that every dev note should have are dev-notes, and a specific version 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.) (5.5, for example). Additional tags can be added as necessary, and usually include specific component tags.
Properly tagging notes is important to make them easier to find and revisit later.