As the Documentation Team lead, Jennifer "jhodgdon" Hodgdon has done a fantastic job of not only keeping Drupal core's API documentation high-quality and consistent, but also of on-boarding new Drupal core contributors through the "Novice" issue queue.

Since documentation improvement patches are always welcome, and since they are unlikely to break other parts of the system, I'm happy to announce the promotion of Jennifer as a Drupal core co-maintainer for version 7 and 8. Her responsibility will be solely around documentation and code style patches, plus occasional help on "emergency" commits such as a required rollback of an accidental patch commit in order to get our automated test suite passing again.

The hope is that delegating responsibility for documentation and code style patches to Jennifer will help increase the velocity of Drupal 8 development. Not only will documentation changes go in faster, it also allows catch, webchick and myself to focus our time on bigger patches.

Welcome to the core committer team, Jennifer! :-)


Sam Kottler (not verified):

Wow! This is great news.

I'm really glad that these kind of optimizations are being made to accelerate the work of Catch, Angie, and yourself.

jhodgdon (not verified):

Thanks! It's an honor to be admitted into the Drupal 7/8 team of Dries, Angie, and Nat... Not to mention more than a little scary to have commit privileges on Drupal Core, but I'll certainly try to be as careful as I can!


Dave Reid (not verified):

Congrats to Jennifer and the docs team! This should help ensure all those annoying docs patches get in smoothly and quickly.

Is this pattern of allowing commit access and delegating responsibility to core going to continue to other trusted system maintainers or is this just a one-time-deal kind of thing? It would be nice if we could actually trust people in MAINTAINERS.txt to make small improvements and leave medium and larger patches and issues to more review.

mthl (not verified):

As a first act, I recommend clarifying the distinct parts of module documentation between formal/material/efficient and final causes.

Final cause - why the module exists, currently the module project page.
Material cause - what the module is made of, currently code documentation from code comments, also the "view repository" link on the project page

and the most confused subjects for module developers asked to write documentation:
Formal cause - how the module works
Efficient cause - how to use the module (use cases)

Right now the last two are spread out over the "read documentation" pages, the module's Readme file, and all sorts of blogs and Drupal Q&A sites. This is terrible because clear use cases and models of the code are what allow newcomers to climb the learning curve. You don't learn a new system by reading the code top to bottom.

sun (not verified):

This makes sense to some extent, but really could have used some more public discussions upfront.

In particular, I'm slightly concerned about:

  1. Larger docs patches that change more than a typo, but instead revise, update, or rewrite documentation.

    I totally don't want to discredit @jhodgdon or anyone else working on docs patches (you're awesome!), but there's a not so small chance for changing documentation to state something that is wrong/inappropriate. This happened in the past already (don't have time to dig out concrete examples right now, sorry).

    My concern is that some documentation patches might be fast-tracked into core, and people working on those patches may lack a deeper understanding of the code that the docs are actually for.

  2. As with any other dedicated and special component/topic area, in terms of Quality Assurance, I think it is highly problematic to allow anyone who participated in the engineering process to perform the final judgment on whether a particular piece of work was done correctly and meets all quality criteria.

    In fact, doing so pretty much contradicts the #1 rule of quality assurance: separation of concerns.

    Our core committers to date were in line with that, since they normally do not participate in any issue until it's RTBC, so they're able to make a unbiased judgment on the final result of work, as they're coming from an "outsider" and general perspective.


Not everything needs to be discussed in public upfront. We can adjust the rules based on lessons learned. Sometimes that is a more effective approach.

We'll always make mistakes and commit patches prematurely or mistakenly. That is fine as long as the benefits outweigh the drawbacks. I believe that will be the case, but let's see.

webchick (not verified):

I think coming in with an unbiased judgment of work makes sense when you're talking about parts of the system that are closely coupled together or changes that could have deeper ramifications (which, btw, is why "commit access for every subsystem maintainer" is a nightmare scenario to me), or anything else that involves actual engineering/coding.

However, documentation is an area that has literally no way of breaking anything else functionally in the system if something wrong is committed. It's also an area where fixing bugs (if they are introduced) is incredibly cheap—simply spin off a Novice issue and it'll usually get looked at within a few days, if not a few hours. Changes/tweaks to documentation are harmless, unlike changes/tweaks to APIs, so it makes sense to employ a looser standard of oversight.

Of course, for documentation/coding standards changes that do have wider implications, such as introducing new coding standards or changing rules around @return parameters or similar, which directly affect core/module developers, those would go through the standard community review cycle. But for everything else (which is 99.9% of docs/coding standards patches), this allows them to get out of the RTBC queue much faster, so that Dries, catch, and I can stay focused on the patches that actually do need more careful consideration and an unbiased perspective. (Though just because I'm not actively participating in an issue before RTBC doesn't mean I'm not watching. ;))

Senpai (not verified):

I approve this message! Hooray for Jennifer and all the current members of the Docs team! This is HUGE!!

Thomas Svenson (not verified):

Fantastic news and choice. Having a core committer that focuses on these important parts is going to really help making it easier to engage new contributors working on documentation.

Andy Berezovsky (not verified):

Congrats to Jennifer!

Folowing the suggestion by Dave Reid I would mention here that Linus Torvalds uses a "model of trust" to speed up the development of Linux core.
As we all know, git is what he "invented" to be the version control for Linux core - and he determined that he trusts several people on specific subsystems (like USB, File system, media handling, etc.). So he only directly works with these people he knows as experts (and accepts pull requests from them as he knows that they have reviewed it and trusts them). And these experts then form there own "circle of trust" with other developers wotking on Linux core.

May be not closely related to the way Drupal core development is oranized, but this is what other people are doing :)