Proposal: An update to the Field Guide

This proposal comes out of an ad-hoc session at the WordPress Community Summit. This session grew out of discussions during the session on backward compatibility in GutenbergGutenberg The 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. where it was noticed that some WordPress changes are easily missed by the extendors of WordPress and WordPress site builders.


The Field Guides in WordPress started in 3.4 and have been consistently published since WordPress 4.1. In this time, they have grown in length due to an increase in both the number of 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. and the number of changes in each version.

Longer posts can be more difficult to read to completion and this can cause important information to be missed. Additionally, as much of the information is linked to rather than included in the post it takes effort to truly understand the breadth of changes in a WordPress release. All of the information that is published is valuable to the WordPress community, so discouraging the publishing of content would be antithetical to the goal of informing and helping the WordPress community and is not something that is desired.


The first part of this proposal is to continue publishing the existing 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. 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. on this site (make/coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.) but adjust the target for publishing it to the final scheduled betaBeta A 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.. Currently, the target is to publish the Field Guide at the same time as RC1. This doesn’t change the amount of work for the release team, but it does move the target up by approximately one week. Publishing this earlier will give some additional time to update documentation, encourage testing from the community, and also allow for time to prepare for part two of this proposal.

The second part is to start publishing a simplified Field Guide to the WordPress Developer Blog. The audience for this guide is primarily two groups: Extenders of WordPress such as pluginPlugin A 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 Plugin Directory or can be cost-based plugin from a third-party and theme authors and Developers building custom sites. This simplified guide will focus on the following things:

  • Large features that developers would want to tie into
  • Changes with a high potential of causing breakage
  • Features the core team wants developers to start using right away as the use of them will benefit WordPress end users.

As an example, a hyper-focused Field Guide for WordPress 6.3 could have highlighted the new command palate (a large feature that developers would want to tie into), Async/Defer in the script loader (a new feature that when developers start using, WordPress end users will benefit), and the post editor being iframed (a change with a higher potential of causing breakage).

The target length of this Field Guide should be 800-1000 words and it should link to but not embed any other documentation such as dev notes. The target will be to publish this post within one week of RC1. The same process for all content published on the developer blogblog (versus network, site) will be followed and the release documentation lead(s) or their designee will be expected to work with the WordPress Developer Blog team in the #core-dev-blog channel and the developer blog content GitHub repository to coordinate the content and publish date.

Provide feedback by 15 September 2023

This proposal is one step, but not necessarily the only step, at improving communication around WordPress releases and making it easier for WordPress updates to instill confidence. Feedback will be accepted until 15 September 2023

Thanks to @annezazu, @webcommsat, @ndiego, and @jeffpaul for feedback on this proposal prior to publication.