Proposal: Make/Core Post Guidelines

During the 4.3 retrospective, one commonly mentioned theme was make/coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 Blogblog (versus network, site) (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 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. changes should have a post written on the make/core blog, ideally no later than the first week of the 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. period.   Examples of API changes that should be announced include, but are not limited to: new filters, new actions, changed order of hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., substantial enhancements to queries (The Boone Gorges Rule), Doing a ticketticket Created for both bug reports and feature development on the bug tracker. 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 “CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. 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 TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. tickets. This feedback is important to the development process.

Peer Review

It is strongly encouraged to ask a 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. 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 leadRelease Lead The community member ultimately responsible for the Release. (or a designee) before posting. Release 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. 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 slackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel the meeting will take place in.

Tags

Almost all posts are related to a specific component, please 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.) 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