Aaron Jorbin 5:25 pm on September 30, 2015
Tags: make/core, proposal ( 36 ), this is so meta

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

Konstantin Obenland 5:42 pm on September 30, 2015

I appreciate your quest for better documentation and an improved experience around 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. for new releases. However I don’t think that it is feasible or even desirable to have every new filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., action, or function announced here. I fear it will lead to reading fatigue when important posts are buried in minor dev notes and adds a considerable burden to every commit (where these things are already documented) which in return has the potential to further increase 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. bottleneck that we’re trying to remove.

I’m generally against rules and guidelines and instead rather rely on common sense wherever possible. This seems like a good opportunity to remind people about values and the importance of the points you mentioned, but I would be disappointed if we used it to introduce rules and requirements around posting here.
- Helen Hou-Sandi 6:15 pm on September 30, 2015
  
  I don’t think this is saying that every new thing be documented on Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. individually – those are examples of the type of content you might find here. Most of those things (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., functions, parameters) are included in the weekly summary posts. The proposal does say “Grouping related changes into one post is fine.” – being related by time seems reasonable to me.
  
  I think it’s been demonstrated here and elsewhere that “common sense” is not actually “common” (as in shared). There have been numerous very distracting and draining issues stemming from poor communication, most of them avoidable. For instance, the 4.3 retrospective post did not make it clear that the bullet points listed out were direct quotes, not processed or prioritized information, or that the concluding paragraph was a personal note and not a team conclusion, and the few comments that followed reflected that. And those are mild comments.
  
  You could say that commit message contents are mostly “common sense”, but I was more than happy to write them out, and the commit messages ever since have been much more consistent and helpful. Including more extended information based on guidelines such as including the why/backstory of a change has really helped on many fronts, including easing in the introduction of changes that might otherwise be contentious.
  
  If we don’t document things like this, we continue to rely on the institutional knowledge of individuals, which is a fragile reliance, constantly shifting based on who’s around at a given moment, and also does not provide any view into the history of how something has evolved. This is a rather general set of guidelines – if nothing else, they’re a good introductory document that we can link to people who are writing on Make/Core for the first time.
- Aaron Jorbin 7:41 pm on September 30, 2015
  
  Thanks for the feedback Konstantin. I agree that reader fatigue is a concern, which is why the suggestion to group related changes into one post. This could be a component summary, or this could be a generalized “Minor 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 you should know about in WordPress 4.4” post.
  
  It also doesn’t need to be 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 writes these posts. I am happy to make any regular contributor[s] to WordPress a contributor [role] on this site.
  
  I also don’t like rules, which is why I didn’t frame these as rules. This isn’t a set of rules that you will be punished if you break them. This is documenting institutional knowledge that we don’t often do a good job of sharing. You and I who have been contributing and writing posts for a while know what we need to. Guidelines makes a lot more sense than “All the advice I have recieved or given”, but if you have a better idea of how to phrase it, I’d love a suggestion.
  - Mike Schroder 10:17 pm on September 30, 2015
    
    How about “Best Practices?”
Knut Sparhell 11:06 pm on September 30, 2015

1. This seems like a good start for a set of guidelines.

2. When to post, what to post, who to post this, should be a set of rules or best practices, separate from how to post and the guidelines for the content, tone and language of such a post.

3. This a coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. development blogblog (versus network, site), and the audience is developers (but not only coders). Don’t make it more simple than necessary. Non-developers, end users, will have other sources. See 4. below.

4. Please avoid acronyms not very common among developers globally. Example: 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. is ok, SXSW is not.

5. Important changes in workflow for end users should be announced or proposed on the wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org//news blog (too), may be with a link to a post on this blog. It seems the news blog is only used for release announcements. There’s never anything about what is, or may be, coming in the next release.
Ryan McCue 1:00 am on October 1, 2015

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.

While I agree in general with the guidelines, I disagree with this part. Generally, I think it’s pretty clear what group you’re part of, and it helps give it a lighter and more conversational tone.
- Dion Hulse 8:44 am on October 1, 2015
  
  Unfortunately it’s often very murky slope though.
  It’s often clear to those of us who are active, but for those who are not, or for whom English is a second (or third) language, it can be difficult to distinguish it from the person or team vs. “WordPress said this” – and that’s what the Guideline is hoping to avoid, cases where something is read out of context.
  
  Even I trip up on “we” being used elsewhere sometimes, I often don’t know who “we” is until I look up the persons background to work out what group the person is involved with.
  
  This isn’t designed to outlaw the usage of ‘we’, just to clarify that it should be avoided unless it’s abundantly clear to someone who knows little or nothing about you as to who is included in that we.
- Samuel Sidler 11:50 am on October 1, 2015
  
  What Dion said. 🙂
  
  I think there are situations when it will make sense to say “we” but it should always be preceded or followed by the group speaking. For example, “we, the Customize component maintainers, discussed…” If you’re referencing a meeting you can avoid “we” altogether with something like “those of us in attendance” and list those who were in attendance at the beginning or end of the post.
bobbingwide 9:21 am on October 1, 2015

Re: It is strongly encouraged … to proofread.
Suggest correcting the spelling of Guidelines in the subject.
Ryan Boren 2:44 pm on October 2, 2015

Most feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins. merge proposals have these tags. Some of the new posts do not have them.

https://make.wordpress.org/core/tag/feature-plugins+merge+proposal/

Merge proposals could use their own checklist that includes things like a detailed call for testing targeted at 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. testing audiences.