[Numpy-discussion] NEP process update

[Nathaniel Smith]

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?
https://docs.scipy.org/doc/numpy-dev/dev/index.html

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).

-n

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