Improvements for the JEP Shepherd documentation

[choldgraf]

Description

There are a few places where our documentation doesn't make it clear what exactly the Shepherd should do, or how to do it. Here are a few sticking points that I've run into as part of #79.

Confusion points

• No dedicated shepherd documentation. For starters, there's no dedicated place to provide shepherds with guidance. As this is a somewhat complex job, I think we should provide a place for them.
• How to decide who is on the review team. The guidelines mention that we suggest an optional review team, but it's unclear who needs to review a JEP, and who has final decision authority on whether it is accepted. I think right now this then defaults to "everybody on the @jupyter/steeringcouncil" but there are likely many JEPs that do not require a full steerco vote (or for which the steerco is not the right body to review).
• What is the decision criteria? The guidelines mention that in the end of the JEP process, it is either approved or rejected, but they do not specify what criteria leads to one of those two outcomes. Is the decision made by consensus? By majority vote? And who are the people that get a vote? I think that because this isn't specified, we likely default to the criteria of the changing governance rules, but this should be explicit.
• How to get in touch with the steering council? (who whoever the review team is) In the case of Jupyter Notebook version 7 #79, I'm assuming the steerco needs to be the review team on the JEP. However, it is unclear to me how the shepherd is supposed to get in touch with the steering council. I believe there is a listserv but I couldn't find its address publicly, and I wasn't sure whether emailing this group was welcome or not. There's also @jupyter/steeringcouncil but I am not sure if that will reliably ping the right people in a way they will notice.

[afshin]

How to decide who is on the review team.

This one in particular has a specific — if partial — answer in that once the Software Steering Council is up and running, it becomes their responsibility to vote on JEPs. The actual mechanics of it are left to them to establish, though.

[choldgraf]

@afshin is that true for every single JEP? Thinking out loud: it feels like requiring a full SSC vote on every JEP might be excessive, given that JEPs might be useful for subsets of the community but that don't necessarily require input from the entire SSC. If we make the voting process complex enough, we'll be disincentivizing people to open up JEPs.

I don't have strong opinions here, just voicing my initial gut reaction!

[afshin]

This is one of the primary responsibilities of the SSC just as it was one of the primary responsibilities of the original SC. They may well decide an internal process that isn't a full vote once that body is up and running. Or they may meet frequently enough that they do put it to a full vote. The new governance isn't prescriptive about how they do it, but it is prescriptive about who is responsible for doing it:

(https://github.com/jupyter/governance/blob/master/software_steering_council.md)

[ellisonbg]

@choldgraf I think you are making good points. Some thoughts:

• I think part of the role of the SSC is to help the community decide which things should be JEPs. In situations where the SSC decides that it is the wrong body to make the decision, I think they can and should push the decision back to a Subproject or working group. Put another way: the JEP process is designed for major decisions where the SSC is the right decision making body. If the SSC isn't the right decision making body, that is fine, but it probably doesn't need to be a JEP then.
• The SSC will make decision using the consensus seeking model, so they are free to use informal consensus to make decisions when it works, and only call formal votes as needed. IOW, not all decisions need to be made through a complex, formal vote.
• Even when a formal vote is called, the voting process has been designed to be simple and fast moving. For example the voting period for all votes is 7 days. This will ensure (especially relative to the current model) that JEPs don't get stalled.