Proposal: Make/Core Post Guidelines

During the 4.3 retrospective, one commonly mentioned theme was make/core posts and improving their style and language. All active contributors should review this post and comment with your feedback. This is a DRAFT and a PROPOSAL, it is not a whack from above with Mjölnir. After revising, this document will live in the core handbook.

Introduction

The Make WordPress Core Blog (make/core) is the official blog of the WordPress core team. It is read by thousands of people, many of which don’t know the intricacies of WordPress core or that don’t fully understand the process of how core is developed. In order to ensure the best experience possible for the developer community, these guidelines are developed with the reader in mind. The goal of most make/core posts is two-fold: to generate feedback from the developer community (including testing) and to ensure developers know about changes and can plan accordingly.

When to write a post

All API changes should have a post written on the make/core blog, ideally no later than the first week of the beta period.   Examples of API changes that should be announced include, but are not limited to: new filters, new actions, changed order of hooks, substantial enhancements to queries (The Boone Gorges Rule), Doing a ticket binge on a component, changing the purpose of a parameter in a hook, and new general helper functions.

Grouping related changes into one post is fine. For example, a single post called “Customizer changes in WordPress 4.2” is fine, rather than individual changes about each commit. If in doubt, discuss your posting plans during the weekly dev chat.

Changes should be announced as early as feasible. There is almost always more feedback on make/core posts than in Trac tickets. This feedback is important to the development process.

Peer Review

It is strongly encouraged to ask a committer to proofread a post before publishing it. This is to ensure that you look your best when publishing a post. Merge Proposals should always be read by the release lead (or a designee) before posting. Release dev notes should be read by the release lead (or a designee) before publishing.

Style and Substance

First Person pronouns should be avoided. As the blog is the official voice of the core team, you should keep your personal thoughts out of the body of the post and instead put them in comments.

In general, the word “We” should be avoided without it being very clear who the group is you are speaking about being a member of.

Posts that are designed as Requests for Comments or are draft roadmap in nature should make sure to highlight that it is a draft proposal. Highlight this in the title and in the opening paragraph.

Many people reading make/core don’t speak English as a first language (or in the case of Jorbin, don’t read or write in any known language). Keep that in mind when choosing words. It’s better to keep it simple than it is to sound smart. In general, the tone should be similar to WordPress: Friendly.

Meeting Announcements

When announcing a meeting, you should always use the time shortcode so that visitors see when a meeting is in their local time. You should also include what slack channel the meeting will take place in.

Tags

Almost all posts are related to a specific component, please tag them with the component name.
For announcements related to a specific release, please tag them with the release number.
For announcements of API changes, including additions, please tag them with dev-notes.
For posts related individual projects and initiatives, please tag them consistently with a project name.

#makecore, #proposal, #this-is-so-meta