[Numpy-discussion] NEP process update

Nathaniel Smith njs at pobox.com
Tue Dec 5 22:44:23 EST 2017

On Tue, Dec 5, 2017 at 5:32 PM, Ralf Gommers <ralf.gommers at gmail.com> wrote:
> On Wed, Dec 6, 2017 at 1:49 PM, Nathaniel Smith <njs at pobox.com> wrote:
>> - NEPs are really part of the development process, not an output for
>> end-users -- they're certainly useful to have available as a
>> reference, but if we're asking end-users to look at them on a regular
>> basis then I think we've messed up and should improve our actual
>> documentation :-)
>> - NEPs have a different natural life-cycle than numpy itself. Right
>> now, if I google "numpy neps", the first hit is the 1.13 version of
>> the NEPs, and the third hit is someone else's copy of the 1.9 version
>> of the NEPs. What you actually want in every case is the latest
>> development version of the NEPs, and the idea of "numpy 1.13 NEPs"
>> doesn't even make sense, because NEPs are not describing a specific
>> numpy release.
> The last two points are good arguments, I agree that they shouldn't serve as
> documentation. A separate repo has downsides though (discoverability etc.),
> we also keep our dev docs within the numpy repo and you can make exactly the
> same argument about those as about NEPs. So I'd still suggest keeping them
> where they are. Or otherwise move all development related docs.

Are these the dev docs you're thinking of?

Regarding discoverability, right now it looks like the only way to
find the latest NEPs on google is by searching for something like
"numpy-dev neps", which is pretty obscure. (It took me 4 tries to find
something that worked. "numpy neps" seemed to work, but actually sent
me to an out-of-date snapshot.) In Python, the PEP web pages are
rebuilt on something like a 6 hour timer, and it's actually super
annoying, because it means that when someone posts to the list like
"hey, I just pushed a new version, tell me what you think", everyone
goes and finds the old stale version, sometimes people start
critiquing it, ... it's just confusing all around. So I do think we
want to make sure there's some simple way to find them, and that it
leads to the latest version, not a stale build or an old snapshot.

Moving NEPs + development docs to their own dedicated repo would
resolve this and seems like a plausible option to me. We could
probably do better than we are now with the regular docs too. Though
the experience with PEPs does make me a bit nervous about having
versioned snapshots of the NEPs in all our old versioned manuals
(which have tons of google-juice).


Nathaniel J. Smith -- https://vorpus.org

More information about the NumPy-Discussion mailing list