[Numpy-discussion] backwards compatibility and deprecation policy NEP

Nathaniel Smith njs at pobox.com
Tue Jul 24 23:07:58 EDT 2018

On Sun, Jul 22, 2018 at 12:28 PM, Ralf Gommers <ralf.gommers at gmail.com> wrote:
> On Sat, Jul 21, 2018 at 7:15 PM, Nathaniel Smith <njs at pobox.com> wrote:
>> Speaking of examples: I hate to say this because in general I think
>> using examples is a great idea. But... I think you should delete most
>> of these examples. The problem is scope creep: the goal for this NEP
>> (IMO) should be to lay out the principles we use to think about these
>> issues in general, but right now it comes across as trying to lay down
>> a final resolution on lots of specific issues (including several where
>> there are ongoing conversations). It ends up like trying to squish
>> multiple NEPs into one, which makes it hard to discuss, and also
>> distracts from the core purpose.
> I'm not sure this is the best thing to do. I can remove a couple, but aiming
> to be "totally uncontroversial" is almost impossible given the topic of the
> NEP.

Of course the NEP itself will have some things to discuss – but I
think the discussion will be more productive if we can stay focused on
the core part of the NEP, which is the general principles we use to
evaluate each specific situation as it comes up. Look at how much of
the discussion so far has gotten derailed onto topics like
subclassing, submodules, etc.

> The diag view example is important I think, it's the second most
> discussed backwards compatibility issue next to histogram. I'm happy to
> remove the statement on what should happen with it going forward though.

It's the most discussed issue because it was the test case where we
developed all these policies in the first place :-). I'm not sure it's
particularly interesting aside from that, and that specific history
("let's come up with a transition plan for this feature that no-one
actually cares about, b/c no-one cares about it so it's a good thing
to use as a test case") is unlikely to be repeated.

> Then, I think it's not unreasonable to draw a couple of hard lines. For
> example, removing complete submodules like linalg or random has ended up on
> some draft brainstorm roadmap list because someone (no idea who) put it
> there after a single meeting. Clearly the cost-benefit of that is such that
> there's no point even discussing that more, so I'd rather draw that line
> here than every time someone open an issue. Very recent example:
> https://github.com/numpy/numpy/issues/11457 (remove auto-import of
> numpy.testing).

I can see an argument for splitting random and linalg into their own
modules, which numpy depends on and imports so that existing code
doesn't break. E.g. this might let people install an old version of
random if they needed to reproduce some old results, or help us merge
numpy and scipy's linalg modules into a single package. I agree though
that making 'np.linalg' start raising AttributeError is a total

>> Regarding the major version number thing: ugh do we really want to
>> talk about this more. I'd probably leave it out of the NEP entirely.
>> If it stays in, I think it needs a clearer description of what counts
>> as a "major" change.
> I think it has value to keep it, and that it's not really possible to come
> up with a very clear description of "major". In particular, I'd like every
> deprecation message to say "this deprecated feature will be removed by
> release X.Y.0". At the moment we don't do that, so if users see a message
> they don't know if a removal will happen next year, in the far future (2.0),
> or never. The major version thing is quite useful to signal our intent.
> Doesn't mean we need to exhaustively discuss when to do a 2.0 though, I
> agree that that's not a very useful discussion right now.

The problem is that "2.0" means a lot of different things to different
people, not just "some future date to be determined", so using it that
way will confuse people. Also, it's hard to predict when a deprecation
will actually happen... it's very common that we adjust the schedule
as we go (e.g. when we try to remove it and then discover it breaks
everyone so we have to put it back for a while).

I feel like it would be better to do this based on time -- like say
"this will be removed <today + 1 year>" or something, and then it
might take longer but not shorter?

Re: version numbers, I actually think numpy should consider switching
to calver [1]. We'd be giving up on being able to do a "2.0", but
that's kind of a good thing -- if a change is too big to handle
through our normal deprecation cycle, then it's probably too big to
handle period. And "numpy 2018.3" gives you more information than our
current scheme -- for example you could see at a glance that numpy
2012.1 is super out-of-date, and we could tell people that numpy
2019.1 will drop python 2 support.

...But that's a whole other discussion, and we shouldn't get derailed
onto it here in this NEP's thread :-).

[1] https://calver.org/


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

More information about the NumPy-Discussion mailing list