With the work going on in issues like #1255674: [meta] Make core maintainable and elsewhere, one of the things that's going to help us move forward is defining additional people to sit in MAINTAINERS.txt. It'd be good, for a number of reasons, to define better what that actually means.

The current text reads:

"The people listed here have agreed to do more quality assurance work for
particular areas of Drupal. All of them are subject to change."

Proposed text would read something more like:

"The people listed below set architectural direction for their respective subsystems, and ensure their parts of the Drupal core issue queue are being looked after. Maintainers are both the main point of contact for new contributors who are working on issues touching a certain subsystem, as well as for core maintainers who wish to get a sanity check of proposed patches.

If you'd like to be listed here, a good place to start is performing some basic issue queue triage and clean-up in the respective subsystem, followed by reviews and patches for outstanding issues. Once you've established a contribution record for a few weeks, post an issue at http://drupal.org/node/add/project-issue/drupal to recommend yourself for MAINTAINERS.txt under the relevant subsystem."

I'm sure that needs tons of more work, but that's along the lines of what the general unwritten definition of subsystem maintainer is, I think. It'd be helpful in a recruiting effort to know what people are signing up for, and what's expected of them.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

larowlan’s picture

Should there also be a clause about advocacy and recruiting / coordinating / mentoring.
This is an important role / value of established core maintainers and crucial to the long term sustainability of drupal.

catch’s picture

I'm not sure about the very first bit:

"The people listed below set architectural direction for their respective subsystems, and ensure their parts of the Drupal core issue queue are being looked after."

A fair amount of architectural work is and can be done by people are aren't listed as subsystem maintainers, I think this is giving a listing more prominence than it should have (i.e. we don't want people to not work on things because they're not listed). However it'd be good to get architecture or high level overview in there somehow.

What being in MAINTAINERS.txt currently means (in practice) for me:

- person did significant work on the subsystem prior to getting listed (put it in in the first place, major refactoring, lots of bug fixes or reviews). Defining significant is hard, depends on the subsystem, the person, what amount of work it actually needs.

- person has committed to at least reviewing patches for that subsystem for a while (the end of the release cycle they were added or beyond).

It'd also be good to point out that subsystems can have >= 2 maintainers.

Everything else looks great to me. I am not sure about advocacy/recruiting etc. - some people listed in MAINTAINERS.txt do bits of that because they spend unhealthy amounts of time on irc etc., but I think it's fine to be in there even if the only thing you ever do in core is fix bugs in sqlite or poll module as long as there's some consistency.

David_Rothstein’s picture

Back in #621618: Revamp MAINTAINERS.txt (and the followup issue, #746920: [meta] Complete + clean up MAINTAINERS.txt and drupal.org components) there were several drafts of different text that could go in here, but in the end we wound up going with something short (with the idea that something could be added to the handbook later explaining it in more detail - however, I guess that never happened).

Might be worth looking back through those old issues for inspiration.

I agree with @catch that "set architectural direction" is too strong. Really doing something like that (or at least doing it well) is a huge time commitment (see: D8 initiatives, which have been doing that for months now), and it's not healthy for either the maintainer or the community to have that be something "owned" primarily by those one or two people. Obviously they will likely participate in architectural discussions, but I think the main responsibility is more like "try to keep the issue queue sane, write/review patches when possible, and be the point of contact if someone is looking to get involved."

jhodgdon’s picture

As I recall, the issue queue farming was also controversial in the last go-around -- people didn't want to commit to watching their component's issue queue. So it would be good to run that by the people currently listed there probably. It's a lot of work (at least I can speak for docs in that regard, and search, which I used to issue-queue-farm until recently, and I don't think anyone is any more).

Anyway, +1 on the proposal by webchick.

Bojhan’s picture

I do wonder though, if the goal of this issue is to create a better picture of what people are signing up for when becoming a maintainer. Why are we doing this? Because people are currently not signing up to be a maintainer because they don't understand what they are signing up for. Or increase the quality of new/existing maintainers? I feel we should have a clear understanding of what our goal is here, if its to attract new maintainers - we should probably line out, why they currently are not signing up (lack of a description in maintainers.txt seems to be an unlikely fix).

webchick’s picture

The goals are the following:

- Crell and others already in MAINTAINERS.txt have stated that they have no idea what being in MAINTAINERS.txt actually means, and so they want a definition.
- A bunch of people got scared witless last week when we started chucking stuff out of Drupal core indiscriminately. Several of those people want to help take burden off the core dev team by offering to maintain some of these long-neglected modules. But without a definition of what maintenance actually means, we have no means of setting proper expectations when onboarding new contributors.
- To make it clear to people contributing patches to these subsystems, but not interested in taking on a maintainership role, who the main point of contact is for their area so they can get feedback on patches and work on more important issues.
- To make it clear to everyone that MAINTAINERS.txt is *always* looking for extra hands.

Stuff like that.

catch’s picture

- To make it clear to everyone that MAINTAINERS.txt is *always* looking for extra hands.

This bit I think is seriously missing from the current version and people's expectations. I think that comes from MAINTAINERS.txt being half documentation of who is maintaining, and half a list of credits. Both functions are fine but if it's looked at as a list of credits then it can be daunting to suggest adding yourself to it.

jhodgdon’s picture

Here's the current text at the top of maintainers.txt:

Drupal core is maintained by the community.  To participate, go to

  http://drupal.org/contribute

The people listed here have agreed to do more quality assurance work for
particular areas of Drupal.  All of them are subject to change.

Here is my suggestion for how it could read:

------------------

Drupal core is built and maintained by the Drupal project community. Everyone is encouraged to submit issues and changes (patches) to improve Drupal, and to contribute in other ways. To find out more, visit http://drupal.org/contribute

The branch maintainers listed below oversee the development of Drupal as a whole, by making the ultimate decisions on which patches are applied to the software, and by working with the community to set goals, priorities, and guidelines. They make a long-term commitment to the future of Drupal.

The component maintainers listed below oversee the development of Drupal subsystems, with a shorter-term, more fluid commitment. Responsibilities of component maintainers (which can be divided amongst the maintainers of the subsystem) include:
- Monitoring their subsytem's issue queue for new issue reports, and triaging those reports.
- Mentoring new contributors who are working on issues related to that subsystem.
- Being the point of contact for that subsystem's contributors.
- Reviewing proposed patches to that subsystem.
- Acting as an expert on the workings of that subsystem (answering questions that come up, and being involved in discussions of major overhauls and re-architecting).

Most component maintainers start out contributing to their component by triaging issues, supplying patches, and reviewing others' patches. Then once a pattern of contribution and knowledge of that component is established, they can apply to become a component maintainer by posting an issue at http://drupal.org/node/add/project-issue/drupal to recommend themselves for MAINTAINERS.txt under the relevant subsystem.

The current maintainers are listed below.

--------------

Thoughts on this? Easier to write/review in a comment than in a patch for now I think?

webchick’s picture

Wow, I LOVE it! The one nit I'd pick is that the word "triaging" seems to be a bit problematic, especially for non-native speakers. A lot of people tend to think it means something related to a hospital. So maybe spelling that out a bit more (or linking to documentation if we have it).

webchick’s picture

Status: Active » Needs review

Also marking needs review.

Bojhan’s picture

Status: Needs review » Active

I wonder, why don't we just put this in a handbook - on being a maintainer? I think the text is a great start, but I am left wondering why we burden any reader with that in Maintainers.txt? For this to be effective we should the initial text on making the points about:

- Definition of a maintainer
- That you can contact, those listed below if you have a issue in that queue
- That we need more maintainers

I believe being brief is part of being effective, thereby my rewrite - a lot of the points you made above are great, but my suggestion is to move that to a book, where we can go more in-depth?

"Drupal core is built and maintained by the Drupal project community. The maintainers below are responsible for overseeing development of their part, and actively contribute bringing patches into Drupal core. Everyone is encouraged to submit issues and changes (patches) to improve Drupal, and to contribute in other ways ( http://drupal.org/contribute ).

For more information about maintainers and possibly how to become one see http://drupal.org/contribute/maintainers"

Anyways just an idea, I welcome it being shot down.

webchick’s picture

Status: Active » Needs review

Sure, I'm ambivalent on where it ultimately lives. As long as someone reading MAINTAINERS.txt can find it.

catch’s picture

That looks great. I would actually list branch maintainers immediately after the branch maintainer description (there are not very many), so it's completely clear who's in which group.

jhodgdon’s picture

+1 on moving it to a page on d.o instead of being in maintainers.txt. I'm not fond of the wording in #11 though, since it says maintainers contribute patches. I don't think that's part of the defined responsibility -- we want them to *manage* their section, not *write* their section (a distinction I'm being increasingly aware of, as being co-leader of docs means I have no time to write docs any more, for instance, and when was the last time Dries or Angie had time to actively write many patches for core?).

So how about this:

-----
Drupal core is built and maintained by the Drupal project community. Everyone is encouraged to submit issues and changes (patches) to improve Drupal, and to contribute in other ways -- see http://drupal.org/contribute to find out how.

The Drupal Core branch maintainers oversee the development of Drupal as a whole:
(list of branch maintainers)

The Drupal Core component maintainers oversee the development of Drupal subsystems. See http://drupal.org/contribute/core-maintainers for more information on their responsibilities, and to find out how to become a component maintainer. Current component maintainers for this branch of Drupal core:
(list of component maintainers)

-----
And then we can put the wording from #8, expanded, and using the word "issue queue farming" (with an explanation) instead of triage, into http://drupal.org/contribute/core-maintainers -- and that page should say to look at MAINTAINERS.txt for the current list. Thoughts?

jhodgdon’s picture

First draft of the handbook page is up:
http://drupal.org/contribute/core-maintainers

jhodgdon’s picture

Here is a patch for maintainers.txt that does #14 essentially.

jhodgdon’s picture

Hm. Bojhan suggested putting this into the doc page:
- Definition of a maintainer
- That you can contact, those listed below if you have a issue in that queue
- That we need more maintainers

I think definition is there, but not the other two. Any thoughts/revisions/suggestions for http://drupal.org/contribute/core-maintainers ?

jhodgdon’s picture

bump. Should we move forward on this?

catch’s picture

Status: Needs review » Reviewed & tested by the community

I posted #1290652: Trial adding MAINTAINER.txt folks as core 'issue queue maintainers', that would be something to add, which is a good reason to add it to the documentation page rather than having this in patches.

Marking #16 RTBC.

Bojhan’s picture

Status: Reviewed & tested by the community » Needs review

Wondering if we can get more reviews on the text? This is all still first draft

catch’s picture

Do you mean the text in MAINTAINERS.txt or the text on Drupal.org?

edit: I mean - if the MAINTAINERS.txt patch is fine, let's commit that then continue to work on the handbook page.

jhodgdon’s picture

By the way, looking at #17 and the current text in http://drupal.org/contribute/core-maintainers, I think it does cover (a) what being a maintainer does and (c) how to become a maintainer. All it doesn't cover from Bojhan's suggested content is (b) who you should contact about issues... at least not directly. Although the responsibilities do sort of imply that you can contact people ("being the point of contact")...

Anyway, suggestions are of course still welcome on that text! I think that the patch itself is fine... although I wrote it so of course I would. :)

Bojhan’s picture

If everyone is oke with the text I am fine with it, wondering if we should add catch to maintainers while we are at it.

ultimateboy’s picture

Agree with Bojhan. I could have opened a new issue, but I figured it's fine to just re-roll with Catch added. So here's that patch.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Yeah catch! :)

So it looks like we have several people who think this patch is good to go. I don't think it's very controversial.

Already tagged for d7 backport and d6 for that matter...

catch’s picture

Version: 8.x-dev » 7.x-dev
Status: Reviewed & tested by the community » Patch (to be ported)

Committed to 8.x.

Moving back to 7.x for webchick. That will need a different patch.

Do we want a new issue for working on the handbook page text some more?

jhodgdon’s picture

I guess as long as this issue is still open, we can discuss the handbook page here too? They kind of go together.

I personally don't think there are major problems with the Handbook page -- I think it contains the essential information, and is fairly concise... otherwise I would go revise it. :) I haven't seen any specific ideas for changing it yet, and I think it covers the ideas people said it should cover in comments above.

Maybe everyone subscribed to this issue could take a minute and go to
http://drupal.org/contribute/core-maintainers
and review it? maintainers.txt advertises this page as:

The Drupal Core component maintainers oversee the development of Drupal subsystems. See http://drupal.org/contribute/core-maintainers for more information on their responsibilities, and to find out how to become a component maintainer.

(which I think it covers)... DEFINITELY open to suggestions though!

Bojhan’s picture

A couple quick notes (traveling), Branch maintainers part is still a bit unclear that they supervise one version.

Onto component maintainers, wish we could remove some lingo here because I dont know that all contributors (especially the non coders) know what subsystem is and issue queue farming. Also what about enforcing the idea of their social responsibilities, they are involved in learning new contributors how to help on their topic, lead up initiatives around their topic and communicate about this.

Additionally "with a shorter-term, smaller time, and more fluid commitment" I am not sure thats true, for people who maintain things like UX, base system, a11y or docs it is probably not very nice to say its a "smaller time commitment" and "short term thinking". It would be easier here to just focus on the strengths, translate strategic thinking into actionable items and are committed to maintaining their topic in one or several versions.

Sorry I couldn't incorporate it yet,

jhodgdon’s picture

Thanks for the feedback! I've just edited the page to incorporate your suggestions (sort of anyway). A few thoughts:
- We did actually (see discussion above) want to make it clear that a subsystem maintainer didn't have to commit to maintaining the subsystem forever. So I didn't want to say that people had to commit to a long term. Revised this language to say "They can make a shorter-term commitment to maintaining a subsystem, or a longer-term commitment that spans several major Drupal versions."
- I think we need the subystem lingo, but I tried to make it clearer that it was being defined. Ditto with "issue queue farming", although I could be convinced to remove it.

Bojhan’s picture

@jhodgdon The way you explained subsystem should work. I will ping a few contributors I know, that dont know core dev - to give their feedback.

Crell’s picture

How in the world did this NOT get on my radar???

+Epic from me. :-) I've been begging for this for a long time.

Tor Arne Thune’s picture

Here's a re-roll for D7 of patch in #24 as asked for in #26 :)

xjm’s picture

Status: Patch (to be ported) » Reviewed & tested by the community

Looks great.

webchick’s picture

Status: Reviewed & tested by the community » Fixed

Looks great!

Committed and pushed to 7.x.

Automatically closed -- issue fixed for 2 weeks with no activity.