RFC Governance Document #12878

amueller · 2018-12-27T22:36:00Z

This is a draft of the proposed governance structure for the scikit-learn project. It has been discussed somewhat between core developers, but I want to get input from the wider community.
We tried to keep is as simple as possible though some complexities crept in as always.

I did some editing to have a consistent document, so this is "my version", not a consensus (yet).

The goal is to discuss this document further in this PR and have a final vote of core developers on the public mailing list.

I kicked out the (really old and bad) flow chart from the documentation page (it's still in the tutorial). Alternatively we could remove the "other resources" which are pretty out of date and google probably provides better ones.

initial rendering:
https://41695-843222-gh.circle-artifacts.com/0/doc/governance.html

qinhanmin2014 · 2018-12-28T03:34:03Z

doc/documentation.rst

@@ -87,13 +87,6 @@ Documentation of scikit-learn |version|
            </div>

            <div class="row-fluid">
-                <div class="span4 box">
-                    <h2><a href="tutorial/machine_learning_map/index.html">Flow Chart</a></h2>


Maybe remove Additional Resources instead? The flow chart seems useful from my side and most additional resources are outdated.

I think it would be fine to see governance linked from About and Developers and not have this prominent a position

@jnothman so you don't want to see the additional resources go?

I just don't see the value in having this as a core section of the Documentation page. Most users don't care. Most developers don't care. It is not, in a sense, about the software, but about about the software (so it belongs on About and Developers).

doc/governance.rst

qinhanmin2014

LGTM, personally I'd like to keep the flow chart.

reshamas · 2018-12-30T17:55:24Z

Question for you:
For example, if a contributor does not respond to a review comment in PR, when can someone else take it over? What's the etiquette for that? Do they wait 1 week, 1 month? Or follow-up 1-3 times before taking it over?
(refer to wimlds scikit-sprint for examples)

doc/governance.rst

GaelVaroquaux · 2018-12-30T16:37:47Z

doc/governance.rst

+comments) in the past 12 months will be asked if they want to become emeritus
+core developers and recant their commit and voting rights until they become
+active again. The list of core developers, active and emeritus (with dates at
+which they became active) is public on the scikit-learn website.


Ideally we should add a link here to this list. However, I would suggest that this is done in a second time, after the merge of this document.

I added a link to the group which is the active members, but yes, once we have a list we can link it here.

as someone who falls in this category, i think this is a really good idea.

I'm not, tbh, sure what benefit we have of putting dates on the dev list is...

I'm not super sold on it but we can try? ;)

I think the main motivation is that we show how long people were active to give proper credit?

If we're trying to "show how long", then "dates at which they became active" is not really sufficient!

If we have dates of when they became active and when inactive that shows how long, right?

doc/governance.rst

GaelVaroquaux · 2018-12-30T18:05:23Z

@reshamas :

For example, if a contributor does not respond to a review comment in PR, when can someone else take it over? What's the etiquette for that? Do they wait 1 week, 1 month? Or follow-up 1-3 times before taking it over?

This is a good question, and I feel that we should address it. My personal preference would be:

new contributor comments on PR saying that she/he wants to take over
failing to respond to respond to respond to comments for 1 week means PR can be taken over
a comment simply saying that the initial contributor wants to continue is valid, however such comment should give a timeframe

However, first this is only a personal view, second I feel that this should go in the contributor guide, rather than in the governance document.

(refer to wimlds scikit-sprint for examples)

Would you mind giving a link: I feel that there is good material that can be reused.

reshamas · 2018-12-30T18:17:11Z

@GaelVaroquaux

Here is the sprint list of PRs
Here are a couple of examples:

Side note: I also reached out to these contributors multiple times via email and Meetup email, and those communications are not documented on GitHub.

GaelVaroquaux · 2018-12-30T20:08:27Z

@reshamas : I am starting to understand (sorry, I have not been involved with the sprint, although it would have been a good use of my time): you, and others, lost time and were not able to contribute productively because of these stalled PRs.

As far as I am concerned, we should indeed move forward on such stalled PR. The only caveat is that sometimes a contributor has in his agenda to finish, but is not checking email at a specific time. I really think that your concern is a legitimate one, and we should address it by making things more explicit. When the project was small, the community made decisions on a case-by-case basis. With a much bigger community, it doesn't work well. I propose write guidelines in a separate pull request, and leave this one for the main governance questions.

amueller · 2018-12-30T21:31:41Z

@reshamas I agree this is an important issue, but I would also argue this should probably not part of the governance doc.
@GaelVaroquaux I was helping @reshamas with the sprint and I think overall it went pretty well :)

amueller · 2018-12-30T21:33:19Z

Thank you for all your input @GaelVaroquaux! I'll try to respond before my vacation starts on Tuesday but I have a long list of things to do.

fix broken link Co-Authored-By: amueller <t3kcit@gmail.com>

qinhanmin2014 · 2018-12-31T02:02:29Z

So we've decided to drop the great flow chart? I still think it's better to remove Additional Resources instead.

amueller · 2019-01-09T22:26:20Z

@qinhanmin2014 I wouldn't say that we have decided that. I think no-one else has voiced their opinion (looks like @TomDLT agrees with you). I'm happy to make the change but this is not the part I'm most concerned about ;)

There's been no movement on this for 10 days. I think I had actually commented on the issue brought up by @GaelVaroquaux and I like @adrinjalali's suggestion.

I'm a bit disappointed by the lack of engagement I have to say but I guess that's what we get for a lengthy process. Given the lack of input, I think we should go with @adrinjalali's suggestion, give everything another reading, and then probably put it to a vote on the general mailing list, with all "core devs" having the ability to vote?

jnothman · 2019-01-02T03:16:51Z

doc/documentation.rst

@@ -87,13 +87,6 @@ Documentation of scikit-learn |version|
            </div>

            <div class="row-fluid">
-                <div class="span4 box">
-                    <h2><a href="tutorial/machine_learning_map/index.html">Flow Chart</a></h2>


I think it would be fine to see governance linked from About and Developers and not have this prominent a position

doc/governance.rst

jnothman · 2019-01-10T07:30:00Z

doc/governance.rst

+
+Scikit-learn uses a "consensus seeking" process for making decisions. The group
+tries to find a resolution that has no open objections among core developers
+within a month. If no consensus can be reached in this time frame, a


within a month of what? How/when does one declare that a decision needs to be made? Does one create a SLEP to force a decision, such that then there is a month from its posting to find consensus? Can this be made more explicit?

When I tried to fix this issue on the doc version, I failed to keep it simple, but it was along the lines of: "A deadline is set once two core developers call for a deadline on a particular issue."

This is indeed a tricky point and I'm not sure how to best address it.
Go has (shepherds)[https://github.com/golang/proposal] that can call for votes if I understand correctly. I'm not sure how well that works.
Having a call for vote and a seconding would also work. Can the proposer call for a vote and/or second?

I'm not sure what you're asking in

Can the proposer call for a vote and/or second?

I'm fine with two people proposing a vote, but it seems absent here.

... The group tries to find a resolution that has no open objections among core developers within a month. ...

->

... The group tries to find a resolution that has no open objections among core developers. At any given time, if a core developer suggests a deadline for the discussion and another core developer seconds the suggestion, that deadline is the time the team has to reach a consensus. ...

but then you need to stipulate a minimum time to deadline

My first draft had "a deadline which is not closer that two weeks from the point of setting the deadline", but it becomes a bit convoluted in the text. I just thought if we require two people to sign on the deadline, they'd agree on a "reasonable" deadline. I'm personally happy with having a min and/or max on the deadline call.

@jnothman The question was whether to do a vote, we need two people that are not the proposer to call for a vote, or if the proposer can be one of the two people.

I'll try to reformulate this in a bit.

within a month of what? How/when does one declare that a decision needs to be made? Does one create a SLEP to force a decision, such that then there is a month from its posting to find consensus?

According to this document the SLEPs are explicitly used to call for a vote. So that seems like a natural solution to me. But it doesn't have to be a strict requirement, just a possibility.

How about:

call for a vote = vote will take place in 1 month.

any call for a vote must be backed by a SLEP

any core dev can call for a vote, regardless of who created the SLEP

SLEP creation != call for a vote, though the proposer can do both at the same time

Co-Authored-By: amueller <t3kcit@gmail.com>

…vernance

amueller · 2019-01-29T15:54:01Z

Ok I tried to simplify taking the process by adding a call to vote. So now any core dev can call a vote on any SLEP and the vote takes a month. If no 2/3 majority is reached, it goes to the TC which has another month.
I think this is ample time to make a decision. I'd really like to move forward with this and ideally approve and merge before the sprint.

Sorry for my delay on finalizing this.
If there's no major comments in the next week I'll call for a vote on the general mailing list.

adrinjalali · 2019-01-31T08:49:15Z

doc/governance.rst

+
+Scikit-learn uses a "consensus seeking" process for making decisions. The group
+tries to find a resolution that has no open objections among core developers.
+At any point during the discussion, any core-developer can call for a vote, which will


I still think it makes sense to include the requirement of another core developer to second the call for the vote though. But no hard feelings.

I feel like that would complicate things and we can always change this if it doesn't work out. What do others think?
I'm not really opposed to it but I feel like we should try and keep things as simple as possible.

I think in practice a single call for vote should be okay.

Ok. I'll wait a couple more days for people to comment.

amueller · 2019-02-06T04:48:13Z

I'll call for a vote on the ML on Friday, then we can have two weeks of voting (possibly longer if we don't get a good turnout?) and can merge before we (that is non paris people) head out to the sprint.

I want the sprint to be spend bikeshedding the sleps, not the governance ;)

NelleV

👍

NelleV · 2019-02-09T02:24:42Z

doc/governance.rst

+
+This is a meritocratic, consensus-based community project. Anyone with an
+interest in the project can join the community, contribute to the project
+design and participate in the decision making process. This document describes


minor nitpick: there should probably be a comma after the word "design"

the Oxford comma...

NelleV · 2019-02-09T02:30:44Z

doc/governance.rst

+consensus in the required time frame, the TC is the entity to resolve the
+issue.
+Membership of the TC is by nomination by a core developer. A nomination will
+result in discussion which cannot take more than a month and then a vote by


similarly, a comma is missing after "month"

NelleV · 2019-02-09T02:35:21Z

doc/governance.rst

+decision is escalated to the TC, which in turn will use consensus seeking with
+the fallback option of a simple majority vote if no consensus can be found
+within a month. This is what we hereafter may refer to as “the decision making
+process”.


nitpick: process''. -> process.''

I always understood this as being UK-US variation.

NelleV · 2019-02-09T02:40:11Z

doc/governance.rst

+tries to find a resolution that has no open objections among core developers.
+At any point during the discussion, any core-developer can call for a vote, which will
+conclude one month from the call for the vote. Any vote must be backed by a
+`SLEP <slep>`. If no option can gather two thirds of the votes cast, the


This phrasing is a bit ambiguous: are options referring to "yes" or "no?" Or is it referring to several technical options, and core developers don't agree with the same technical option?

Maybe I'm being to nitpicky here: I don't know how often this situation happens. We can always revisit if the TC is swamped with voting requests.

Yes, it's ambiguous, I agree. I think right now it allows both (yes/no or different options). For things like freezing or pipeline slicing it might be less a question of whether we want it but how. We could have one SLEP and vote per technical option, I'm not sure how this would play out in practice. I think we can figure this out as we go along.

NelleV · 2019-02-09T02:43:20Z

doc/governance.rst

+will be unanimous, a two-thirds majority of the cast votes is enough. The vote
+needs to be open for at least 1 week.
+
+Core developers that have not contributed to the project (commits or GitHub


As a side note, this is a bit in contradiction with "not only code contributions are valued." This doesn't include any organization of sprints, fundraising, etc.

I think we can change that to "having actively contributed (commits, comments or organizational and non-code contributions)". I'm slightly hesitant about changing things now, but I think it would be consistent with the spirit of the document to rephrase this.

Recall, though, that the emeritus status is only negotiated ("will be asked if they want to become emeritus"), triggered by this criterion. Explicitly using a criterion of commits or comments makes it much easier to measure activity by which this emeritus proposition is triggered. A vague criterion is not especially helpful here. There is nowhere that says the emeritus status will be forced, though presumably this would follow the same as any other personnel dispute (not explicitly covered in this document), such as removing core dev rights.

I think the suggestion was more in terms of what he document communicates. I'm not sure we'll use a very precise criterion anyway (unless you wanted to write a bot ;). I figured it would be more that either we'll do a (yearly?) spring cleaning or someone thinks "has been awhile since this person was around"?
I don't have strong feelings either way, though.

GaelVaroquaux · 2019-02-09T13:10:41Z

As a side note, this is a bit in contradiction with "not only code contributions are valued." This doesn't include any organization of sprints, fundraising, etc.

I think that this aspect is important: for the future of the project, it is important for us that we have not only coders on board. We need to make sure that they feel that they can be fully part of our group.

amueller · 2019-02-11T04:05:48Z

Thanks for the approves. I would prefer if everybody voted on the mailing list as this is the mechanism specified in the document, and also more public and seems easier to get a record of @TomDLT @NelleV @agramfort.

GaelVaroquaux · 2019-02-11T06:15:32Z

I think we can change that to "having actively contributed (commits, comments or organizational and non-code contributions)".

+1 on such a change.

qinhanmin2014 · 2019-02-12T01:18:58Z

I just don't see the value in having this as a core section of the Documentation page. Most users don't care. Most developers don't care. It is not, in a sense, about the software, but about about the software (so it belongs on About and Developers).

Fair enough, should we remove doc/tutorial/machine_learning_map/ then? @jnothman

jnothman · 2019-02-12T01:20:35Z

Fair enough, should we remove doc/tutorial/machine_learning_map/ then? @jnothman

I'm trying to say that this PR should not be touching doc/documentation.rst so that question seems irrelevant.

qinhanmin2014 · 2019-02-12T01:33:28Z

I'm trying to say that this PR should not be touching doc/documentation.rst so that question seems irrelevant.

Sorry I misunderstood your comment. I don't have a strong opinion about where to put the governance document, just feel that the road map is useful from my side.

rephrasing Co-Authored-By: amueller <t3kcit@gmail.com>

amueller · 2019-02-19T15:40:41Z

@jnothman I'm fine with moving it to the about page.

amueller · 2019-02-19T15:51:28Z

It would be great if y'all could vote or abstain on the mailing list
@adrinjalali @agramfort @lesteve @yarikoptic @arjoly @glouppe @fabianp @kastnerkyle @MechCoder @jmetzen @jakevdp @bthirion.

Thanks!

…vernance

bthirion · 2019-02-19T18:53:36Z

+1 for me. Go go team ! B

…

jnothman

We should link to this from the contributing docs too. But this lgtm

MechCoder

looks great, thanks!

agramfort · 2019-02-20T16:21:22Z

@amueller I already upvoted on Feb 10 on the list

satra · 2019-02-20T16:40:53Z

@amueller - did you want us to specifically respond on the list, or does an upvote on the original post sufficient (which i did).

amueller · 2019-02-20T21:21:18Z

@agramfort oh sorry, my bad :-/ somehow the thread got split and I didn't take the first part into account, also had Gilles and Adrin.

amueller · 2019-02-20T21:21:47Z

@satra given the phrasing of the document for decision making I think it would be good if you posted on the list if you don't mind.

amueller · 2019-02-22T17:56:40Z

I didn't reach out to the other devs as I originally planned for time reason, but we have 25 votes for, zero against or explicit abstain, and 24 non-responses. I think we're good to merge. I'm not sure how we should record the outcome, is the mailing list archive enough?

GaelVaroquaux · 2019-02-22T21:49:46Z

I think we're good to merge.

I think so too!

I'm not sure how we should record the outcome, is the mailing list archive enough?

I would say so. At least it's somewhat neutral.

jmetzen · 2019-02-23T18:46:40Z

looks good to me, thanks team!

GaelVaroquaux · 2019-02-25T15:44:01Z

🍻

* add governance doc * add links to docs * minor formatting, more links * Update doc/governance.rst fix broken link Co-Authored-By: amueller <t3kcit@gmail.com> * Apply suggestions from code review Co-Authored-By: amueller <t3kcit@gmail.com> * reframed with call for vote. I think this is good. * make it easier to call a vote. * Update doc/governance.rst rephrasing Co-Authored-By: amueller <t3kcit@gmail.com> * link governance from the about page instead on documentation.rst

This reverts commit ae9bae2.

* add governance doc * add links to docs * minor formatting, more links * Update doc/governance.rst fix broken link Co-Authored-By: amueller <t3kcit@gmail.com> * Apply suggestions from code review Co-Authored-By: amueller <t3kcit@gmail.com> * reframed with call for vote. I think this is good. * make it easier to call a vote. * Update doc/governance.rst rephrasing Co-Authored-By: amueller <t3kcit@gmail.com> * link governance from the about page instead on documentation.rst

amueller added 2 commits December 27, 2018 17:26

add governance doc

0c88262

add links to docs

fab720d

qinhanmin2014 reviewed Dec 28, 2018

View reviewed changes

doc/governance.rst Outdated Show resolved Hide resolved

qinhanmin2014 reviewed Dec 28, 2018

View reviewed changes

doc/governance.rst Outdated Show resolved Hide resolved

doc/governance.rst Outdated Show resolved Hide resolved

doc/governance.rst Outdated Show resolved Hide resolved

betatim mentioned this pull request Dec 28, 2018

Governance of Binder jupyterhub/team-compass#42

Closed

minor formatting, more links

db8567a

qinhanmin2014 approved these changes Dec 29, 2018

View reviewed changes

GaelVaroquaux reviewed Dec 30, 2018

View reviewed changes

Update doc/governance.rst

616390e

fix broken link Co-Authored-By: amueller <t3kcit@gmail.com>

GaelVaroquaux mentioned this pull request Dec 30, 2018

[MRG] DOC: How to deal with stalled PR #12894

Merged

jnothman reviewed Jan 10, 2019

View reviewed changes

adrinjalali and others added 4 commits January 15, 2019 14:17

Apply suggestions from code review

4b291b9

Co-Authored-By: amueller <t3kcit@gmail.com>

reframed with call for vote. I think this is good.

26ead43

Merge branch 'governance' of github.com:amueller/scikit-learn into go…

c98b362

…vernance

make it easier to call a vote.

bc602c9

adrinjalali reviewed Jan 31, 2019

View reviewed changes

NelleV approved these changes Feb 9, 2019

View reviewed changes

NelleV reviewed Feb 9, 2019

View reviewed changes

TomDLT approved these changes Feb 11, 2019

View reviewed changes

Update doc/governance.rst

d5af494

rephrasing Co-Authored-By: amueller <t3kcit@gmail.com>

amueller added 3 commits February 19, 2019 10:51

Merge branch 'master' into governance

52eb8a9

link governance from the about page instead on documentation.rst

cfe1d74

Merge branch 'governance' of github.com:amueller/scikit-learn into go…

91561e1

…vernance

jnothman approved these changes Feb 19, 2019

View reviewed changes

MechCoder approved these changes Feb 19, 2019

View reviewed changes

amueller merged commit 8a258c9 into scikit-learn:master Feb 25, 2019

amueller mentioned this pull request Feb 25, 2019

GOV sent out pings for emeritus core devs. #13257

Closed

xhluca pushed a commit to xhluca/scikit-learn that referenced this pull request Apr 28, 2019

Revert "RFC Governance Document (scikit-learn#12878)"

6b967ad

This reverts commit ae9bae2.

xhluca pushed a commit to xhluca/scikit-learn that referenced this pull request Apr 28, 2019

Revert "RFC Governance Document (scikit-learn#12878)"

7e0f698

This reverts commit ae9bae2.

RFC Governance Document #12878

RFC Governance Document #12878

Conversation

amueller commented Dec 27, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

qinhanmin2014 left a comment

Choose a reason for hiding this comment

reshamas commented Dec 30, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GaelVaroquaux commented Dec 30, 2018

reshamas commented Dec 30, 2018 • edited Loading

GaelVaroquaux commented Dec 30, 2018

amueller commented Dec 30, 2018

amueller commented Dec 30, 2018

qinhanmin2014 commented Dec 31, 2018

amueller commented Jan 9, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amueller commented Jan 29, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amueller commented Feb 6, 2019

NelleV left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GaelVaroquaux commented Feb 9, 2019 via email

amueller commented Feb 11, 2019 • edited Loading

GaelVaroquaux commented Feb 11, 2019 via email

qinhanmin2014 commented Feb 12, 2019

jnothman commented Feb 12, 2019

qinhanmin2014 commented Feb 12, 2019

amueller commented Feb 19, 2019

amueller commented Feb 19, 2019

bthirion commented Feb 19, 2019 via email

jnothman left a comment

Choose a reason for hiding this comment

MechCoder left a comment

Choose a reason for hiding this comment

agramfort commented Feb 20, 2019

satra commented Feb 20, 2019

amueller commented Feb 20, 2019

amueller commented Feb 20, 2019

amueller commented Feb 22, 2019

GaelVaroquaux commented Feb 22, 2019 via email

jmetzen commented Feb 23, 2019

GaelVaroquaux commented Feb 25, 2019 via email

amueller commented Dec 27, 2018 •

edited

Loading

reshamas commented Dec 30, 2018 •

edited

Loading

amueller commented Feb 11, 2019 •

edited

Loading