[Numpy-discussion] NEP Procedure Discussion

[Ralf Gommers]

On Fri, Aug 14, 2020 at 1:36 PM Ilhan Polat <ilhanpolat at gmail.com> 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 <peter at entschev.com>
> 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



>> [1] https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst
>>
>> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20200816/9c900486/attachment.html>