NEP Procedure Discussion

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

NEP Procedure Discussion

Peter Andreas Entschev
Hi all,

During the discussion about NEP-35, there have been lots of
discussions around the NEP process itself. In the interest of allowing
people who are mostly interested in this discussion and to avoid
drifting so much off-topic in that thread, I'm starting this new
thread to discuss the NEP procedure.

A few questions that have been raised so far:

- Is the NEP Template [1] a guideline to be strictly followed or a
suggestion for authors?
- Who should decide when a NEP is sufficiently clear?
- Should a NEP PR be merged at all until it's sufficiently clear or
should it only be merged even in Draft state only after it's
sufficiently clear?
- What parts of the NEP are necessary to be clear for everyone? Just
Abstract? Motivation and Scope? Everything, including the real
technical details of implementation?
- Would it be possible to have proof-readers -- preferably people who
are not at all involved in the NEP's topic?

Please feel free to comment on that and add any major points I might
have missed.

Best,
Peter

[1] https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: NEP Procedure Discussion

Ilhan Polat
Also, not to be a complete slacker, I'd like to add to this list;

- How can I help as an external lib maintainer?
- Do you even want us to get involved before the final draft? Or wait until internal discussion finishes?




On Fri, Aug 14, 2020 at 1:23 PM Peter Andreas Entschev <[hidden email]> wrote:
Hi all,

During the discussion about NEP-35, there have been lots of
discussions around the NEP process itself. In the interest of allowing
people who are mostly interested in this discussion and to avoid
drifting so much off-topic in that thread, I'm starting this new
thread to discuss the NEP procedure.

A few questions that have been raised so far:

- Is the NEP Template [1] a guideline to be strictly followed or a
suggestion for authors?
- Who should decide when a NEP is sufficiently clear?
- Should a NEP PR be merged at all until it's sufficiently clear or
should it only be merged even in Draft state only after it's
sufficiently clear?
- What parts of the NEP are necessary to be clear for everyone? Just
Abstract? Motivation and Scope? Everything, including the real
technical details of implementation?
- Would it be possible to have proof-readers -- preferably people who
are not at all involved in the NEP's topic?

Please feel free to comment on that and add any major points I might
have missed.

Best,
Peter

[1] https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: NEP Procedure Discussion

Adrin
Somewhat relevant, this is the discussion around the same topic we've been having in scikit-learn:

On Fri, Aug 14, 2020 at 2:36 PM Ilhan Polat <[hidden email]> wrote:
Also, not to be a complete slacker, I'd like to add to this list;

- How can I help as an external lib maintainer?
- Do you even want us to get involved before the final draft? Or wait until internal discussion finishes?




On Fri, Aug 14, 2020 at 1:23 PM Peter Andreas Entschev <[hidden email]> wrote:
Hi all,

During the discussion about NEP-35, there have been lots of
discussions around the NEP process itself. In the interest of allowing
people who are mostly interested in this discussion and to avoid
drifting so much off-topic in that thread, I'm starting this new
thread to discuss the NEP procedure.

A few questions that have been raised so far:

- Is the NEP Template [1] a guideline to be strictly followed or a
suggestion for authors?
- Who should decide when a NEP is sufficiently clear?
- Should a NEP PR be merged at all until it's sufficiently clear or
should it only be merged even in Draft state only after it's
sufficiently clear?
- What parts of the NEP are necessary to be clear for everyone? Just
Abstract? Motivation and Scope? Everything, including the real
technical details of implementation?
- Would it be possible to have proof-readers -- preferably people who
are not at all involved in the NEP's topic?

Please feel free to comment on that and add any major points I might
have missed.

Best,
Peter

[1] https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: NEP Procedure Discussion

ralfgommers
In reply to this post by Ilhan Polat


On Fri, Aug 14, 2020 at 1:36 PM Ilhan Polat <[hidden email]> wrote:
Also, not to be a complete slacker, I'd like to add to this list;

- How can I help as an external lib maintainer?
- Do you even want us to get involved before the final draft? Or wait until internal discussion finishes?

Yes, before. The internal discussion (at least of the type that's now dominant) should come after, and in a way is less important. A NEP talks to different audiences, depending on the topic. It should start by talking to the people who are impacted by the end result of the particular proposal. Most of the time, these are end users and downstream library authors. Sometimes, for example the umath-multiarray merger, that's NumPy developers. But that's a small minority of cases.

Part of the issue here is that we don't have explicit roles, like a company that develops software products would have. We do have them, they're hidden though. Typically one would have:

- Customers
- A product manager (technical background, marketing/sales role)
- Engineering manager
- Software architects (sometimes multiple layers, e.g. system architect and component architects)
- Domain specialists

People in these roles have conversations at different levels, and the feedback travelling up and down that chain improves the product so it's both fit for purpose and of high technical quality. The current NEP conversations are equivalent to domain specialists and software architects talking about implementation while assuming to fully understand customer needs. And then when a customer asks a question, telling them "we understand your problem, and see our code does multiple dispatch and is fast C code, so it will solve the problem - please wait 6 months and then you can buy the new version of our product".

That's maybe exaggerated, but not by much. Especially for already established products (like NumPy) that are being improved, getting the customer's problem statement and constraints clear has to come first. There will be some iteration, e.g. once there's a prototype new constraints or additional benefits will be discovered, and that refines the outcomes.


On Fri, Aug 14, 2020 at 1:23 PM Peter Andreas Entschev <[hidden email]> wrote:
Hi all,

During the discussion about NEP-35, there have been lots of
discussions around the NEP process itself. In the interest of allowing
people who are mostly interested in this discussion and to avoid
drifting so much off-topic in that thread, I'm starting this new
thread to discuss the NEP procedure.

A few questions that have been raised so far:

- Is the NEP Template [1] a guideline to be strictly followed or a
suggestion for authors?

I agree with Juan, who said "strict NEP template. NEPs with missing sections will not be accepted".

- Who should decide when a NEP is sufficiently clear?

Juan said: "So, my proposal is that there needs to be an *editor* of NEPs who takes responsibility, once they are themselves satisfied with the NEP, for seeking out external reviewers and pinging them individually and asking them if they would be ok to review."

I quite like that too. It would be great to have a pool of NEP editors, because relying on a single editor for everything would be too much for that person. This may be a place where interested downstream library authors like Ilhan and Juan can be really helpful.
 
- Should a NEP PR be merged at all until it's sufficiently clear or
should it only be merged even in Draft state only after it's
sufficiently clear?

I propose: merging as Draft once the sections up to Backwards Compatibility are clear enough, while implementation can still be rough but at least outlines the direction.
 
- What parts of the NEP are necessary to be clear for everyone? Just
Abstract? Motivation and Scope? Everything, including the real
technical details of implementation?
- Would it be possible to have proof-readers -- preferably people who
are not at all involved in the NEP's topic?

Juan said "enforce the above with at least two independent rounds of coordinated peer review".

I'm not sure two rounds are necessary for every single NEP (e.g. the website redesign one was pretty straightforward), but for complex technical NEPs it does seem like a good idea. In many cases, doing one round of review with 1-2 people *before* submitting as a PR could be very beneficial.

Cheers,
Ralf


_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion