formalize proposal/decision making process

[orbeckst]

tl;dr: Put in words how the MDAnalysis community comes to decisions, based on a year of informal process development.

Background

A year ago, MDAnalysis moved to GitHub. Everyone rejoiced. During this year, we learnt how to use the tools on GitHub to improve communication between developers and developers and users. The GitHub issue tracker has become the central communication hub over the year, we have been using issues as the primary means to arrive at decisions regarding policy and requirements.

The public developer mailing list and the closed business mailing list have also been important for various aspects but typically, focused discussions were quickly moved to the issue tracker. The typical pattern was that one developer raised an issue regarding a certain policy and interested @MDAnalysis/coredevs commented. Once the discussion had petered out and all voices were heard, a summary was posted and/or the top post updated. In cases of overwhelming support, the issue was just considered accepted and the proposed action carried out. We also used voting (thumbs up/down) although so far all discussions seemed to have reached a consensus.

Proposal: Formalized decision making process

Rationale

I propose to document one process by which the MDAnalysis community can make decisions. This is not to say that this is the only process. It is primarily meant as guidance for new members and as a reference for our future selves.

How to propose global changes to MDAnalysis

If you want to change the API or the policy or library structure you should follow the following process:

1. (Optional) informally discuss on the developer mailinglist
2. Raise an issue in the issue tracker.
   • describe your proposal; include reasons for the changes and what the actions are that need to be taken if the proposal is accepted
   • add the proposal tag
   • add any other tags that are relevant (e.g. policy, API...)
   • assign the issue to yourself (you will have to look after it, see below)
3. Participate in the discussion; be especially courteous when opposing viewpoints are voiced; try to address all questions and explain as much as necessary. Keep the tone of the discussion professional.
4. Once the discussion comes to a lull, summarize the state of the discussion.
5. Evaluate the discussion and take action:
   • If you are not sure if there's consensus,
     • ask people to vote (thumbs up or down); cast your own vote, too!
     • Wait a few days.
     • Count votes:
       • If you now have a fair number of +1 vs -1 then go to broad consensus to accept the proposal.
       • Otherwise go to no support.
   • If there's a broad consensus to accept the proposal,
     • say so in a comment and then
     • wait for a day or two.
     • If no-one challenges your assessment,
       • update the top post (and issue title) to properly reflect the proposal after the discussion (note edits with name and date at the bottom of the top post under a History heading)
       • post a comment that you consider the proposal accepted,
       • remove the proposal tag
       • carry out the proposed actions (e.g. updating docs, raising new issues)
       • close the issue once the actions have been performed
   • If you get mostly dissenting opinions (or no comments at all, even after asking for comments/voting) then you have no support.
     • post a comment that the proposal has not sufficient support
     • Close the issue without taking actions.

Actions

If accepted:

• document on wiki
• communicate to developer list
• blog post?

Examples

• #786 (on the fly coordinate transformations, open for discussions)
• #743 (mandate tests for MDAnalysis.analysis, accepted)
• #719 (MDAnalysis.analysis user interface, basically accepted but details need to be determined)
• #315 (flexible configuration system, not supported)

---

History (of the issue)

• 2016-03-25 initial proposal (@orbeckst)

[mnmelo]

We also have a BDFL figure that moderates discussions and helps keep focus on the important things. This should definitely be taken into account in the written-down decision model.

[orbeckst]

@mnmelo , I am not really sure how to put your suggestion into the above proposal, especially as BDFL really only works as long as the BDFL retains the respect of the other developers. As such there's little point in putting the role in writing. Either people listen to a "BDFL" figure because they think it's overall beneficial for the project, or they don't. But if they don't, then putting the role into writing wouldn't change a thing.

Furthermore, I think the truth about the current governance model is that anyone of the currently active core devs is perfectly capable to moderate discussions and keep focus.

All that said, I maintain a strong interest in the well-being of MDAnalysis and will continue to support it as best as I can, including trying to get funding to actually pay people to work on it and expand the developer and user community.

[orbeckst]

Hi @MDAnalysis/coredevs ,

if there are no more 'ayes' for this proposal in the next two days then I will close this as "not accepted" (in line with the proposed procedure, which would be kind of ironic ;-) ).

(Right now only I and @richardjgowers gave it a "thumbs up".)

Of course, if you have suggestions for changes, please bring them on.

[jbarnoud]

I agree with most of the proposal, but it seems a bit too formal; the history part especially. What is in the proposal looks sane to me, but are we big enough so we need to write it down?

[orbeckst]

Re: History: That's part of the issue, I tend to put in so any edits to the issue main post are logged (because there's not version control on the top post). I did not intend the "History" section to be part of the written down wiki page.

Re writing down processes: I find it useful because with more and more people coming in and contributing (good!) it can take a bit of time to learn the processes "by osmosis" so it's convenient to point newcomers to a wiki page.

But if most of the core devs are perfectly happy to leave it informal then that's fine, too.

[kain88-de]

Your suggestions read as a nice guide how one should approach any community with changes. But I wouldn't like to formalize this process for MDAnalysis I think we are working good with the current informal style.

[tylerjereddy]

I'm probably ok with mostly informal processes as well. Usually when I go to another medium-large sized library I'll look at their contribution guidelines / rules, but because of time constraints on volunteer / open-source contributions I'll usually just roughly follow the rules / use common sense, and hope the core devs aren't too aggressive in the PR comments. Basically, I'd want to make a prototype and get some constructive feedback fairly soon if I'm going to keep pouring volunteered time into the PR.

The activation energy for making an open source contribution is pretty high if you already have a day job even if you are pretty passionate about the stuff, as many of the core devs here probably are. If I don't see a net positive response to a proposed fix / change / PR of any kind the task drops pretty quickly to the bottom of my priority list (i.e., default = not going to happen).

I suppose the flip side is that an informal process might make the 'curation' activities of very-active core devs more tedious because changes / proposals are presented in inconsistent formats. I can barely keep up with skimming all the things that are going on in issues / PRs, but I know some people are actually reading that code and providing feedback more regularly than I, so their opinions should probably have a bit more weight.

[orbeckst]

Thanks for all the feedback. It seems that people are quite happy with the informal approach that we have going so I am closing it with a wont fix (and it can be revisited in the future if deemed necessary).

[hainm]

I am late for this party but +1 for keeping informal and fun workflow.