Title: Writing developer notes Author: Jonathan Desrosiers Published: August 28, 2020 Last modified: September 3, 2020 --- # Writing developer notes ## In this article * [How do you know what needs a dev note?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#how-do-you-know-what-needs-a-dev-note) * [Who should write dev notes?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#who-should-write-dev-notes) * [What should a dev note include?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#what-should-a-dev-note-include) * [Should dev notes be reviewed?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#should-dev-notes-be-reviewed) * [When should a dev note be published?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#when-should-a-dev-note-be-published) * [Other Tips](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#other-tips) - [Tone and style](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#tone-and-style) - [Tagging and categorizing](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#tagging-and-categorizing) * [Attribution](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#attribution) [↑ Back to top](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#wp--skip-link--target) A Developer note (or “dev notedev note Each 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](https://make.wordpress.org/core/) blog that details a technical change in an upcoming release and what developers need to know about that change. Dev notesdev note Each 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 CoreCore Core 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. ## 󠀁[How do you know what needs a dev note?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#how-do-you-know-what-needs-a-dev-note)󠁿 For each release, tickets that may need developer notes are given the `needs-dev- note` keyword on TracTrac An 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 ticketticket Created 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. ## 󠀁[Who should write dev notes?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#who-should-write-dev-notes)󠁿 The hierarchy for who should author a dev note is as follows: * Someone with deep, working knowledge of the changes. This is usually the committercommitter A 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. ## 󠀁[What should a dev note include?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#what-should-a-dev-note-include)󠁿 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/APIAPI An 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 GitHubGitHub GitHub 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 by the repository owner. [https://github.com/](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. ## 󠀁[Should dev notes be reviewed?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#should-dev-notes-be-reviewed)󠁿 Every post on a [Making WordPress](https://make.wordpress.org/) 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. ## 󠀁[When should a dev note be published?](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#when-should-a-dev-note-be-published)󠁿 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 candidate One 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)](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#alpha-beta). for that release.** To help organize documentation about the upcoming release, a Field GuideField guide The field guide is a type of blogpost published on Make/Core during the release candidate phase of the [WordPress release cycle](https://make.wordpress.org/core/handbook/about/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](https://make.wordpress.org/core/handbook/about/release-cycle/releasing-major-versions/#release-candidate). Field Guides are a collection of all relevant dev notes and tickets for an upcoming release. All field guides for previous releases can be found here:[ make.wordpress.org/core/tag/field-guide](https://make.wordpress.org/core/tag/field-guide). ## 󠀁[Other Tips](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#other-tips)󠁿 Here are some additional resources and tips to help write developer notes ### 󠀁[Tone and style](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#tone-and-style)󠁿 When writing or reviewing any post on the [Making WordPress Core blog,](https://make.wordpress.org/core/) it’s important to remember the[ Post & Comment Guidelines](https://make.wordpress.org/core/handbook/best-practices/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. ### 󠀁[Tagging and categorizing](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#tagging-and-categorizing)󠁿 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 tagtag A 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. [dev notes for a particular release](https://make.wordpress.org/core/tag/dev-notes+5.5/), all the [dev notes written on the blog](https://make.wordpress.org/core/tag/dev-notes), or the [dev notes for a particular component](https://make.wordpress.org/core/tag/dev-notes+rest-api/). ## 󠀁[Attribution](https://make.wordpress.org/core/handbook/tutorials/writing-developer-notes/?output_format=md#attribution)󠁿 When the dev note is published, a “props” line at the very bottom should always be included. For example: “_Props_[_ _](https://wordpress.slack.com/team/U02SVSW3U) _@janedoe for technical review,_[_ _](https://wordpress.slack.com/team/U02RR5UTA) _@johndoe for proofreading._“ This ensures everyone that contributed to the post receives proper recognition, helps the reader know the voices behind the post, and who they are addressing if there are comments or questions. First published August 28, 2020 Last updated September 3, 2020 [ Previous: Running New Contributor Meetings](https://make.wordpress.org/core/handbook/tutorials/running-new-contributor-meetings/) [ Next: Publishing the Field Guide](https://make.wordpress.org/core/handbook/tutorials/publishing-the-field-guide/)