Technical Working Group Charter (DRAFT)

I have added this issue which is relevant to all the proposed working group charters #1934018: Formalize stakeholder roles in working group charters.

Humm... this is a lot of text for something that essentially just tries to say this:

1. The TWG maintains Drupal coding and documentation standards, policies, best practice documents, licensing, and related documentation materials on drupal.org.
2. The TWG only tries to form community consensus. It does not decide on new rules or guidelines on their own. At maximum, it provides recommendations for dispute resolution to Dries.
3. The TWG does not influence the technical roadmap, changes, or strategic decisions for Drupal core or contributed projects in any way.

Did I miss something?

In any case, I think it would be a good idea to simplify (and heavily shorten) this charter. To me it reads a bit like the first draft of the DCOC, which contained too much repetition and details, and we should get to a simple version instead that everyone can parse and understand within 60 seconds.

Lastly, it looks like the TWG will either intersect with the documentation maintainers, or remove responsibilities from them (since most of these policy and guidelines pages are more or less maintained by the documentation team right now).

Coding standards are currently decided on in the core queue, I don't see any reason to move them out of there to an 'official' working group. i.e. as a core developer I do not want to be expected to implement standards defined outside of the core process.

#3:
I would classify those specifically as "Core" coding standards, in which case your concern would be covered off by

The TWG does not set policies or standards for individual projects, including core.

However, we also have coding standards (or perhaps more accurately, 'best practices') which are applied more widely within the overall project ... the standards encouraged within the Project Applications queue being one example. The debates over db_query() versus db_select() is another example ... while the initial debate may have been focused specifically around core, it resulted in a recommendation (albeit contested) being made for contrib as well within the docs pages.

Personally, I also interpret the term 'coding standards' fairly loosely, to also include concepts such as the policy regarding inclusion of 3rd party code in contrib projects ... a quick look at the revision history of http://drupal.org/node/422996 demonstrates that we could benefit from an 'official' home for this as well.

@jthorson - I'm not sure it does cover it, the two paragraphs appear to explicitly contradict each other at the moment. You can't have a working group responsible for "only coding standards which don't cover core" - db_select() vs. db_query() is exactly the sort of issue which is a core standard which then gets picked up (or not) by contrib.

I think that what we really need is a group that will set up processes that actually work for adopting coding standards, and to shepherd that process to the point of being the ones to say "this is now adopted". Whether or not this is the Technical Working Group, I am not sure... but right now I would not say that the "core process" for adopting coding standards actually works, and one could argue that this process doesn't even exist (it isn't really written down anywhere, to my knowledge). And the coding standards that are adopted this way seem mostly to apply both to core and contrib, at least in principle (at least the discussions I've been involved with).

As to why I think we need this... I personally have had bad experiences over the past few years with following what I understand to be the process for adopting documentation-related standards, only to have certain members of the core dev community get very angry about the standards that were adopted... It's really not OK, and it makes me very leary of even getting into standards discussions, even when they're desperately needed.

#5:

I can see the potential contradiction there; perhaps the "With community input" aspect of this charter is under-represented. My internal interpretation of the sentence is more aligned with "The TWG does not [unilaterally] set policies or standards for individual projects, including core", while the current wording does leave itself open to varied interpretation.

Sticking with the core coding standards as an example, the intent is certainly not to replace the current process ... core coding standards would continue to be discussed and developed within the issue queues. What the TWG would add is a formalized mechanism to:

• Validate that policies actually do represent community consensus, rather than "policy by virtue of the largest personality" or "silo'd consensus amongst a small few" in an otherwise undiscovered thread,
• Serve as a facilitator for difficult or largely divisive issues, ensuring that all stakeholder concerns are considered before a policy is formalized, and following through on stalled discussions to avoid the 'smoking crater' syndrome,
• Ensure that policy and standards changes are communicated out to the greater community when they do occur, rather than depending on self-discovery and word of mouth, and
• Play the role of 'owner', from the perspective of a defined single point of contact for policy related questions and clarification requests from within the community.

The subtle distinction is that the above points speak more to a responsibility for established and 'newly defined' coding standards ... as opposed to a responsibility for 'defining new' ones.

Validate that policies actually do represent community consensus, rather than "policy by virtue of the largest personality" or "silo'd consensus amongst a small few" in an otherwise undiscovered thread,

Anything that applies to changes in core code generally goes through this one way or the other because the patches actually have to get committed. I have heard rumours about coding standards pages getting 'fixed' unilaterally but that feels like a different problem.

personally have had bad experiences over the past few years with following what I understand to be the process for adopting documentation-related standards, only to have certain members of the core dev community get very angry about the standards that were adopted... It's really not OK

Right I'm aware of those issues as well, but this is the case with almost any far-ranging core change - not everyone can be involved in every issue, sometimes things happen that you don't know about then you get very fed up with them months later, sometimes people get bitter inside, sometimes they re-open issues to try to change things back.

However while it's often a frustrating process, there is at least the potential for those who have to implement the standards in the code they contribute to make the decisions in the first place, even if they don't participate individually or sometimes issues go in ways they don't agree with. (i.e. I absolutely hate the acronym capitalisation standard we're about to adopt but am also resigned to it happening), and stuff isn't set in stone and can be revisited - like the string concatenation change in Drupal 7.

Coding standards are currently decided on in the core queue, I don't see any reason to move them out of there to an 'official' working group.

I can think of all kinds of reasons. :)

1) Coding standards are currently decided by 5-7 people who happened to find an issue in amongst 10,000 other open issues, not a broader consensus of the core development team.

2) Coding standards are decided on a one-off basis, with no tie-in to a broader scope/vision. Witness all the various "Should we use e-mail or email?" type of issues.

3) We've invented coding standards for all kinds of things that have absolutely no business being coding standards. Like starting docblock comments with an active verb like "Blahs." This is needlessly pedantic and we don't need more reasons to mark a patch "needs work."

4) There's also none of the people inventing one-off coding standards caring for tools to ensure compliance with coding standards, like drupalcs. Couple that with the volume of new rules we invent every week, and as a result, I don't even know what all the rules are, and I'm a core committer!

I think it definitely makes sense for there to be core developer (as well as contrib developer) representation on the TWG (like Jennifer Hodgdon would be a great fit, if she were interested). But it definitely *does not* make sense to keep doing our coding standards like we're doing now.

However while it's often a frustrating process, there is at least the potential for those who have to implement the standards in the code they contribute to make the decisions in the first place. [...] stuff isn't set in stone and can be revisited.

Don't understand how that'd be less true with a TWG? In fact, it's arguably more true. You could petition to an actual decision-making body empowered to change things, as opposed to now where you need to find and convince a one-off volunteer contributor who may flit in and out.

The charters don't really get into the day-to-day workings of each of the individual teams, but the idea is they'd come up with policies to define how to make a change, etc. It might even look extremely similar to the process we use now, except a) the issues would probably be in their own queue rather than scattered around the biggest queue we have on an ad-hoc basis, and b) someone could actually make a decision at the end. Right now, that's a problem.

1) Coding standards are currently decided by 5-7 people who happened to find an issue in amongst 10,000 other open issues, not a broader consensus of the core development team.

How would a working group increase that number to be a broad consensus? Because it's an official group or is there an actual process not stated in the charter to attempt to increase participation? Also we know that issues with 50 people on don't necessarily get resolved any better than those with 5-7.

3) We've invented coding standards for all kinds of things that have absolutely no business being coding standards. Like starting docblock comments with an active verb like "Blahs." This is needlessly pedantic and we don't need more reasons to mark a patch "needs work."

There's nothing to say a working group will revoke lots of overly pedantic standards, or that we can't file issues to revert those standards now.

Most of the 3 pages of issues you linked to are "make x module pass coder review" sub-issues, not coding standards discussions at all. The very oldest issues also have only 2-3 comments on which suggests lack of interest rather than gridlock.

"How would a working group increase that number to be a broad consensus?"

It doesn't. :) That's why I'm confused why you see this as a loss of "democracy" (or maybe i'm misreading your comments?)

The key difference is it's the same 5-7 people rather than random ones with no continuity or plan among them. And the same crowd of ~30 people who care about these things can participate in those discussions the same as they do in the core queue today.

"There's nothing to say a working group will revoke lots of overly pedantic standards, or that we can't file issues to revert those standards now."

We can definitely file issues to revert them now. The problem is, no one is empowered to make a decision about it (or maybe rather everyone is empowered to make a decision about them :P). So they will sit there until they gather enough consensus to overrule the previous consensus, rather than being based on actual data, logic, etc. This isn't a good way to make decisions that affect tens of thousands of people.

The key difference is it's the same 5-7 people rather than random ones with no continuity or plan among them.

5-7 people who are appointed rather than 5-7 people who are self-selecting volunteers yes.

The problem is, no one is empowered to make a decision about it (or maybe rather everyone is empowered to make a decision about them :P).

Core committers have final say if there's a stand-off usually. Core committers are 'appointed' too (before anyone brings that up) but the only power really is veto rather than enforcement.

So they will sit there until they gather enough consensus to overrule the previous consensus, rather than being based on actual data, logic, etc. This isn't a good way to make decisions that affect tens of thousands of people.

I actually don't remember any coding standards issues that were in heated deadlock very recently, are there particular ones you have in mind (I can remember some from a year or three ago of course).

Coding standards issues aren't immune from data and logic, and plenty of core issues that are nothing to do with code style have an element of taste about them. See #1906474: [policy adopted] Stop documenting methods with "Overrides …" and #1627350: Patch for: Case of acronyms in class names (SomethingXSSClassName versus SomethingXssClassName) for two issues which have are 'coding standards' but are almost 100% technical discussions with extremely little bikeshedding.

No one claims the core queue is perfect, but taking decisions that affect core development out of it is a slippery slope to many other kinds of decisions also moving to appointed groups.

Ok cool, thanks. That makes your concerns more clear.

I can only imagine that the people appointed to these various groups will largely be the same self-selecting volunteer group we have today, just formalizing it more for transparency, so that people not in the core queue every day will understand who's who. But since this isn't spelled out in the charter (and really can't/shouldn't be), I can understand being nervous about it.

On the coding standards front, two points:

1) I see the main change here being from "consensus of whichever 30 people happened by the issue this week, which often include someone who is just stubborn and blocks consensus" (which is a well-known design flaw of *any* consensus-based process) to "consensus of 5 people who pay close attention to these topics, informed by the input of whichever 30 people happened by the issue queue this week". I see that as a definite improvement. Currently we de facto often end up with "consensus of Jen Hodgdon after she's been beaten down by varying strong opinions in the issue queue and just wants it to end...", which is really not a good situation for anyone, particularly Jen.

It's been my experience, both personal and professional, that when you move someone from a de facto position of quasi-authority (based on their karma) to a position of de jure authority with an expectation of taking input, one or two things happens:

A) They go "ah ha, I can make decisions now and ignore all that riff raff", and close up.
B) They become *more* sensitive to outside input, and will accept more and more varied input, because they are comfortable that at the end of the day they have the room to take that input and make a decision, even if it annoys someone, because they *are* empowered to look at a bigger picture and not get lost in the weeds.

The challenge of course is ensuring that such a committee gets populated by group B type people, not group A type people. That's on Dries to pick B-group people. :-) But with the right people in that role, having people actually Empowered To Decide(tm) can lead to more consensus and less contention, not to a white-tower situation (which I suspect is the fear). That doesn't mean "taking decisions out of the issue queues". It means clarifying who gets to set those issues to RTBC or fixed.

The same logic applies to most of this document, and (I imagine) the other WG charters. (I'm off to read those next.)

2) All that said, I agree that the scope of TWG is not entirely clear. What falls under "coding standards"? Reading it, my first thought was "all that formatting and documentation stuff on that node with the magic number that Jen has memorized". However, several people here jumped immediately to db_query() vs. db_select(), which is a very technical question with hard data behind it (or there should be hard data, anyway). Where do "coding standards" end and "best practices" begin, and where do they both run into "dude, X is not now the system is architected, don't do that"? It's not clear to me where those lines are.

Another question: Would the TWG be responsible for things like technical relationships with other bodies? I'm thinking specifically of the Framework Interoperability Group, to which I am the Drupal representative. Mostly that's by virtue of me stepping forward and Dries never telling me not to. :-) (I think I emailed him once and he said "yeah, keep doing it", but I don't recall for sure.) Would that be separate, or would FIG Representative be a part of the TWG (meaning I'd have to either be part of TWG or step down from FIG; in which case I'd prefer the former as I think we're doing really good work over there).

RE #16 - It seems to me that the TWG is supposed to kind of *oversee* stuff and make sure things are going in the right direction, by making group decisions on policy, not *do* everything.

So they might be responsible for making sure we have an official Drupal rep in these kinds of bodies, and maybe they would be responsible for saying who our official rep is (rather than it being "email Dries and keep doing it"), but since I think all these charters say members of working groups do not act as individuals, I don't see why the rep would have to be a member of the TWG or why anyone would want you to step down from a role that I imagine is a good fit for you and a benefit for the Drupal project and the FIG working group.

I'm not so much concerned about getting replaced when this goes into effect; more trying to work out, e.g., how we'd go about selecting a new rep should I get hit a by a bus. Knowing what the process is for "naming ambassadors" before we need to name them is generally a good thing, and of the various charters FIG seemed to fit here the least-bad. :-)

Added initial draft