Purpose and future of WordPress-Extra and WordPress-Core

This ticket is a split from #1157 as suggested in https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1157#issuecomment-351753423.

History

In the beginning, there was just one WordPress ruleset. In #58 it was proposed that the sniffs be split into several subsets (something similar was also proposed in #42):

A lot of the sniffs are opinionated and may not be reflective of an actual problem. We should have a ruleset XML file that just contains the core sniffs for checking code formatting, and then another ruleset XML that has the extra sniffs (e.g. those labeled with extra in GitHub)

The WordPress-Core ruleset was created in #64 to be a set of "Non-controversial generally-agreed upon WordPress Coding Standards", and in https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/commit/8409c2748e4b95eb6aa9d027e5cf634518886f13#diff-4486463b25768f719431bc763baab473 WordPress-Extra was introduced, as "Best practices beyond core WordPress Coding Standards".

Ever since, the Core ruleset has essentially reflected the standards outlined in the handbook, while Extra contains additional "best practices".

Present Discussion

In #1157 it was proposed to split formatting and non-formatting rules into their own subsets. But in the process of the discussion, there was soon talk of renaming Extra and Core while we were at it.

The main relevant issues raised are:

1. The name Extra may not be ideal.
2. The Extra ruleset is just a catch-all for stuff not in Core.
3. The term Core implicitly ties the standard too closely to a single project, instead of the community standards in the handbook.

Confusion around Extra

One reason this came up is because the Extra ruleset is sometimes confusing.

To be honest, I never understood the Extra ruleset. To me, this always sounded like stuff that doesn't really belong somewhere else, or rather: you are not sure about where it does belong. https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1157#issuecomment-331635949

It was also noted that splitting it would just add confusion (https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1157#issuecomment-331636969). In the end, I suggested that clearing this up first may help to move forward with the rest of #1157. So here we are.

Why is the distinction needed?

This also led to some discussion of why the distinction between Core and Extra really matters. Why can't they just be combined? The answer is essentially because Core is tied to the handbook, and the handbook isn't comprehensive.

The Core ruleset is only supposed to cover that what's literally stated in the WP PHP Coding Standards handbook. Nothing more.

However, on the one hand the handbook is far from comprehensive, there are a lot of areas which are not covered or only implied. On the other hand, there are industry standards and both PHP as well as WP best practices.

Tongue in cheek, I would go as far as saying that Extra currently contains everything we wish would be covered by the handbook, but isn't. https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1157#issuecomment-331639562

Getting stuff into the handbook would partly alleviate this, and was further propounded:

Right now, WordPress-Extra is a more guiding ruleset based on the opinionated experience of a few of the admins here, but it doesn't need to be. For a long while, the flow of implementation has pretty much all been one way - from the Handbook into the WPCS. But, with WP Core now more involved, we have the opportunity to make that two-way, with WordPress-Extra feeding back into the Handbook. https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1157#issuecomment-351834628

It was noted that this is easier said than done though.

Core and Core

Ultimately, it was suggested that the name Core is also problematic, because the handbook is for

when writing PHP code for WordPress, whether for core programming code, plugins, or themes.

Therefore:

I'd rather see the Core bit dropped altogether, since WP Core is just one of many bits of software that is (meant to be) using the standards (which only happen to be documented in the Core Handbook out of convenience to it being anywhere else). https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1157#issuecomment-346306078

And:

Drop the term 'Core', since that is just one project in the WP community which is using these standards. If WordPress Core wants to (temporarily) do something different to what the Handbook says, then it has its own phpcs.xml.dist with which to make the adjustment. Plugin and theme authors should feel that they can follow what the community standards are, not what WP Core is doing at any moment in time. https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1157#issuecomment-331732520

However, the relationship between the handbook and core vs the community as a whole has been less clear in practice.

Analysis

Here is my analysis on the points that need to be addressed here, and my recommendations for how to address them.

The Handbook

WPCS started out covering just a few rules from the standards in the handbook, and has now grown to the point that the handbook is the thing running behind and becoming a bottleneck. This is a measure of success and shows that WPCS has reached an important milestone. 🎉

Continuing advancement on the part of WPCS is currently being affected by a pessimistic outlook on the further development of the standards in the handbook. We can work around the handbook's lagging, but in the end I think it will cramp WPCS and be less than ideal for the WP community as a whole.

It is time for WPCS and the handbook to decide exactly what they want to be when they grow up—because they have grown up. And yet at this point it still seems a little fuzzy, at least in my opinion.

It is clear that a tighter relationship is forming between WPCS and WordPress itself. However, despite recent advances, I don't think the relationship has fully matured. WPCS still seems, to me at least, more like the de facto standard (pun intended), rather than the "official" WP coding standards for PHPCS. (There is no mention of it in the handbook, for example.) Whether you call it "official" or not, and despite some overlap in leadership and contributors, the fact is that WPCS still seems distinct and autonomous. In particular, the handbook and WPCS are administered very differently; there is no clear process for changing the handbook.

The handbook describes itself as the community standards, but in practice the community doesn't have a clear avenue of offering input at present. If the coding standards are really going to be the community standards, then there needs to be a clear process for discussion and input on the part of the community. Because otherwise the community will go on with WPCS and Extra, and if, when the handbook finally "catches up", it ends up looking different than Extra, the community's ship will probably have already sailed. The result will likely be a disparity between what is in the handbook and what has come to be practiced by the community.

👉 There needs to be a clear process for community contribution to the handbook.
👉 The "official" status of WPCS needs to be made clear.

Extra, Extra, Read all about it

However, this will not erase the line between Core and Extra. As I see it, Extra contains several different classes of sniff:

• Additional generic "best practices" not in the handbook.
• WordPress-specific QA and Security checks.
• Modern codestyle checks.
• Other codestyle checks not in the handbook.

It is in this sense that it is a catch-all for everything not in Core.

The latter two groups could be absorbed into the handbook. And part of me says that ideally, Extra should go completely. But where I am less certain is some of the QA/best practices. I'd like to think that most of these ought to be official, but I suspect that not every QA check necessarily has universal applicability.

Basically it comes down to a question: Why do we need to provide anything that isn't in the handbook?

• Is it just because the handbook is lagging?
• Or, do some things not belong in the official standards? (If so, then why not?)

At this point though, it is hard to tell.

I've already suggested that we need to fix the handbook's lagging, above. But that still doesn't deal with remaining items which may not belong in the official standards for various reasons. At this point though, I think it is difficult to say exactly what will go in the handbook and what will not, and why. Until the processes around the standards are made clear, the future of Extra will remain murky.

Extra suffers from the fact that it isn't actually a standard. I think things are better when each ruleset has a single purpose, a single reason for existence. (E.g., Core exists to supply the rules outlined in the handbook.) In other words, there should just be one right and clear answer to this question:

• What is the Extra ruleset, and what is it intended to accomplish?

Right now, there are multiple possible answers to that question, and none real clear. I think the goal should be to get to a point where that is no longer true.

As a general outline, going forward, I would like to see the more things move from Extra to the handbook. Then, a discussion should happen about whatever remains (if anything) that cannot be moved to the handbook, for whatever reasons. It may then be useful to either, a) remove some of these things from WPCS entirely, and/or b) split Extra into several sub-sets around each reason for keeping things in WPCS that aren't in the handbook. Exactly what happens, though, will depend on what is left. This in turn, will depend on what the standards in the handbook will absorb, and what that process will look like.

But basically, the end goal would be the Extra would either no longer exist, or at least no longer be murky (exist for just a single reason).

👉 We should move as much from Extra to the handbook as possible.
👉 The remaining ruleset (or subsets) should have a single clear purpose.

Summary

WPCS has grown, while activity around the standards in the handbook has perhaps waned. WPCS has eclipsed the handbook, but is still constrained by it. Going forward, changes need to be made so that the energy around WPCS can be channeled into the handbook rather than it acting as a resistor. Essentially, the relationship between WPCS and the handbook and the community and core needs to come to the next stage of maturity. That process is in progress, but on WPCS's end (at lest in my view) things are still fuzzy. WPCS is here to serve the WP community, but how it wants to/is expected to do that going forward has not been precisely pinned down and made explicit.

This is a discussion that I think needs to happen now rather than later, so that we can confidently move forward with the major changes that have been proposed for the rulesets that we offer.

In short, as I said above, WPCS and the standards in the handbook have grown up, and now they need to decide exactly what they want to be—and then be it.

Next Steps

This is a conversation that needs to involve more than just the WPCS contributors. Really, it is more about the WP community and project leads helping to set the direction here and clear the way for further growth. Discussion probably ought to take place in Slack and on the make blogs. The key things that need to be tangibly defined are:

• The intended relationship between the standards in the handbook and the community as a whole.
• The intended relationship between WPCS and the standards in the handbook and the community.
• Processes should then be more clearly established to better facilitate these.

Then, WPCS will be able to proceed within a better defined framework for the future.

#1157

I actually don't think this has to be a blocker for #1157. However, I also think that clearing this up will help us to move forward there more confidently. I suggest that if #1157 does proceed before this is dealt with, that it should not rename either the Extra or Core rulesets. This would be with the understanding that we might still rename/restructure Extra and Core, depending on how this issue pans out. And since Extra is mostly best practices rather than codestyle anyway, I'd say for now it should stay that way, and the focus would be on splitting the Core ruleset.

Feedback

I apologize for being introspective and philosophical. If you think this conversation would just be a distraction, feel free to make that case. 😄

Otherwise, I guess what we need to hear is:

• Do we agree that we'd like clearer definition around the relationship between WP and WPCS? (Or am I just not paying attention?)
• Do we agree that we'd like a clearer process around updating the handbook?
• What kind of process and relationship would we like to see?
• How should we go about making that happen?
• Can it be done in a timely manner/is it worth blocking #1157 over?
• How would you define the purpose of Extra, and do you think this should be clarified/refined in the future?
• What are your thoughts on changing the name of Core to better reflect its relationship with the community vs just core? (Especially if the status of the handbook standards is clarified.)

In my view, ideally, we end up with a standard that is truly a community standard, and not just for core. Core could then be renamed, and Extra would either no longer exist or have a more clearly defined purpose and direction (and could likewise be renamed to better fit that purpose).

And finally, since this is so long, you also have permission in advance to slap me. But not too hard. 😄

Start by reading this issue alongside the linked discussion in #1157 and the WordPress PHP Coding Standards handbook. Map the unresolved questions about the handbook relationship, community process, and the purpose of WordPress-Core and WordPress-Extra. Done means reaching a decision that gives the rulesets clear, single purposes and defines the next steps.