diff options
author | Ralf Gommers <ralf.gommers@gmail.com> | 2021-01-23 20:21:17 +0100 |
---|---|---|
committer | Ralf Gommers <ralf.gommers@gmail.com> | 2021-01-23 20:21:17 +0100 |
commit | 7670cb43442c068617f0b36d4aa1c1d4bbf11e21 (patch) | |
tree | 4ae66d4c14e672e8b601f0f6de3cf64d4adb912c | |
parent | a6edae724424e424f8390c75715ea2273645dfe3 (diff) | |
download | numpy-7670cb43442c068617f0b36d4aa1c1d4bbf11e21.tar.gz |
Address more review comments on the backwards compat NEP
[ci skip]
-rw-r--r-- | doc/neps/nep-0023-backwards-compatibility.rst | 21 |
1 files changed, 15 insertions, 6 deletions
diff --git a/doc/neps/nep-0023-backwards-compatibility.rst b/doc/neps/nep-0023-backwards-compatibility.rst index b37499af9..0445c4b04 100644 --- a/doc/neps/nep-0023-backwards-compatibility.rst +++ b/doc/neps/nep-0023-backwards-compatibility.rst @@ -82,7 +82,10 @@ to be delayed for one or more releases. Strategies related to deprecations ----------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Impact assessment +````````````````` Getting hard data on the impact of a deprecation of often difficult. Strategies that can be used to assess such impact include: @@ -96,6 +99,9 @@ that can be used to assess such impact include: that's too burdensome, then at least to test pre-releases), so this often turns up issues quickly. +Alternatives to deprecations +```````````````````````````` + If the impact is unclear or significant, it is often good to consider alternatives to deprecations. For example, discouraging use in documentation only, or moving the documentation for the functionality to a less prominent @@ -109,8 +115,10 @@ Implementing deprecations and removals Deprecation warnings are necessary in all cases where functionality will eventually be removed. If there is no intent to remove functionality, -then it should not be deprecated either. A "please don't use this" in the -documentation or other type of warning should be used instead. +then it should not be deprecated either. A "please don't use this for new code" +in the documentation or other type of warning should be used instead, and the +documentation can be organized such that the preferred alternative is more +prominently shown. Deprecations: @@ -200,7 +208,7 @@ made to indicate when the behavior changed: Decision making -~~~~~~~~~~~~~~~ +--------------- In concrete cases where this policy needs to be applied, decisions are made according to the `NumPy governance model @@ -217,8 +225,9 @@ Functionality with more strict deprecation policies - ``numpy.random`` has its own backwards compatibility policy with additional requirements on top of the ones in this NEP, see `NEP 19 <http://www.numpy.org/neps/nep-0019-rng-policy.html>`_. -- The file format for ``.npy`` and ``.npz`` files must not be changed in a backwards - incompatible way. +- The file format for ``.npy`` and ``.npz`` files is strictly versioned + independent of the NumPy version; existing format versions must remain + backwards compatible even if a newer format version is introduced. Example cases |