Merge pull request #14447 from stefanv/nep-releases-minor-language-fixups

MAINT: Clarify policy language in NEP-29.

1 files changed, 59 insertions, 72 deletions

diff --git a/doc/neps/nep-0029-deprecation_policy.rst b/doc/neps/nep-0029-deprecation_policy.rst
index 5451327b3..d8cbeb982 100644
--- a/doc/neps/nep-0029-deprecation_policy.rst
+++ b/doc/neps/nep-0029-deprecation_policy.rst
@@ -3,7 +3,7 @@ NEP 29 — Recommend Python and Numpy version support as a community policy stan
 ==================================================================================
 
 
-:Author: Thomas A Caswell <tcaswell@gmail.com>, Andreas Mueller, Brian Granger, Madicken Munk, Ralf Gommers, Matt Haberland <mhaberla@calpoly.edu>, Matthias Bussonnier <bussonniermatthias@gmail.com>, Stefan van der Walt
+:Author: Thomas A Caswell <tcaswell@gmail.com>, Andreas Mueller, Brian Granger, Madicken Munk, Ralf Gommers, Matt Haberland <mhaberla@calpoly.edu>, Matthias Bussonnier <bussonniermatthias@gmail.com>, Stefan van der Walt <stefanv@berkeley.edu>
 :Status: Draft
 :Type: Informational Track
 :Created: 2019-07-13
@@ -12,8 +12,8 @@ NEP 29 — Recommend Python and Numpy version support as a community policy stan
 Abstract
 --------
 
-This NEP recommends and encourages all projects across the Scientific
-Python ecosystem to adopt a common "time window-based" policy for
+This NEP recommends that all projects across the Scientific
+Python ecosystem adopt a common "time window-based" policy for
 support of Python and NumPy versions. Standardizing a recommendation
 for project support of minimum Python and NumPy versions will improve
 downstream project planning.
@@ -36,25 +36,25 @@ Detailed description
 For the purposes of this NEP we assume semantic versioning and define:
 
 *major version*
-   A release that change the first number (e.g. X.0.0)
+   A release that changes the first number (e.g. X.0.0)
 
 *minor version*
-   A release that changes the second number (e.g x.Y.0)
+   A release that changes the second number (e.g 1.Y.0)
 
 *patch version*
-   A release that changes the third number (e.g. x.y.Z)
+   A release that changes the third number (e.g. 1.1.Z)
 
 
-When a project creates a new major or minor version, we recommend that
-the project should support at least all minor versions of Python
-introduced and released in the prior 42 months ~~from their
-anticipated release date~~ with a minimum of 2 minor versions of
+When a project releases a new major or minor version, we recommend that
+they support at least all minor versions of Python
+introduced and released in the prior 42 months *from the
+anticipated release date* with a minimum of 2 minor versions of
 Python, and all minor versions of NumPy released in the prior 24
-months ~~from their anticipated release date~~ with a minimum of 3
+months *from the anticipated release date* with a minimum of 3
 minor versions of NumPy.
 
 
-The diagram::
+Consider the following timeline::
 
        Jan 16      Jan 17      Jan 18      Jan 19      Jan 20
        |           |           |           |           |
@@ -65,33 +65,33 @@ The diagram::
             |-----------------------------------------> Dec19
                       |-----------------------------------------> Nov20
 
-shows the 42 month support windows for Python.  A project with a
-major or minor version release in Feb19 should support py35 and newer,
-a project with a major or minor version release in Dec19 should
-support py36 and newer, and a project with a major or minor version
-release in Nov20 should support py37 and newer.
+It shows the 42 month support windows for Python.  A project with a
+major or minor version release in February 2019 should support Python 3.5 and newer,
+a project with a major or minor version released in December 2019 should
+support Python 3.6 and newer, and a project with a major or minor version
+release in November 2020 should support Python 3.7 and newer.
 
 The current Python release cadence is 18 months so a 42 month window
 ensures that there will always be at least two minor versions of Python
-in the window.  By padding the window by 6 months from the anticipated
-Python cadence we avoid the edge cases where a project releases
-the month after Python and would effectively only support one
-minor version of Python that has an installed base.
-This six month buffer provides resilience to minor fluctuations /
-delays in the Python release schedule.
-
-Because Python minor version support is based on historical release
-dates, a 36 month time window, and a project's plans, a project can
-decide to drop a given minor version of Python very early in the release
-process.
-
-While there will be some unavoidable mismatch in supported versions of
-Python between projects if releases occurs immediately after a
-minor version of Python ages out.  This should not last longer than one
-release cycle of each of the projects, and when a given project does a
-minor or major release, it is guaranteed that there will be a stable
-release of all other projects that support the set of Python the
-new release will support.
+in the window.  The window is extended 6 months beyond the anticipated two-release
+interval for Python to provides resilience against small fluctuations /
+delays in its release schedule.
+
+Because Python minor version support is based only on historical
+release dates, a 42 month time window, and a planned project release
+date, one can predict with high confidence when a project will be able
+to drop any given minor version of Python.  This, in turn, could save
+months of unnecessary maintenance burden.
+
+If a project releases immediately after a minor version of Python
+drops out of the support window, there will inevitably be some
+mismatch in supported versions—but this situation should only last
+until other projects in the ecosystem make releases.
+
+Otherwise, once a project does a minor or major release, it is
+guaranteed that there will be a stable release of all other projects
+that, at the source level, support the same set of Python versions
+supported by the new release.
 
 If there is a Python 4 or a NumPy 2 this policy will have to be
 reviewed in light of the community's and projects' best interests.
@@ -103,9 +103,6 @@ Support Table
 ============ ====== =====
 Date         Python NumPy
 ------------ ------ -----
-Jan 16, 2019 3.5+   1.13+
-Mar 14, 2019 3.6+   1.13+
-Jun 08, 2019 3.6+   1.14+
 Jan 07, 2020 3.6+   1.15+
 Jun 23, 2020 3.7+   1.15+
 Jul 23, 2020 3.7+   1.16+
@@ -120,9 +117,7 @@ Drop Schedule
 
 ::
 
-  On Jan 16, 2019 drop support for Numpy 1.12 (initially released on Jan 15, 2017)
-  On Mar 14, 2019 drop support for Python 3.5 (initially released on Sep 13, 2015)
-  On Jun 08, 2019 drop support for Numpy 1.13 (initially released on Jun 07, 2017)
+  On next release, drop support for Python 3.5 (initially released on Sep 13, 2015)
   On Jan 07, 2020 drop support for Numpy 1.14 (initially released on Jan 06, 2018)
   On Jun 23, 2020 drop support for Python 3.6 (initially released on Dec 23, 2016)
   On Jul 23, 2020 drop support for Numpy 1.15 (initially released on Jul 23, 2018)
@@ -137,27 +132,20 @@ Implementation
 We suggest that all projects adopt the following language into their
 development guidelines:
 
+   This project supports:
 
-   - This project supports at least the minor versions of Python
-     initially released 42 months prior to a planned project release
-     date.
-   - The project will always support at least the 2 latest minor
-     versions of Python.
-   - The project will support minor versions of ``numpy`` initially
-     released in the 24 months prior to a planned project release date
-     or the oldest version that supports the minimum Python version
-     (whichever is higher).
-   - The project will always support at least the 3 latest minor
-     versions of NumPy.
+   - All minor versions of Python released 42 months prior to the
+     project, and at minimum the two latest minor versions.
+   - All minor versions of ``numpy`` released in the 24 months prior
+     to the project, and at minimum the last thee minor versions.
 
-   The minimum supported version of Python will be set to
-   ``python_requires`` in ``setup``.  All supported minor versions of
-   Python will be in the test matrix and have binary artifacts built
-   for releases.
+   In ``setup.py``, the ``python_requires`` variable should be set to
+   the minimum supported version of Python.  All supported minor
+   versions of Python should be in the test matrix and have binary
+   artifacts built for the release.
 
-   The project should adjust upward the minimum Python and NumPy
-   version support on every minor and major release, but never on a
-   patch release.
+   Minimum Python and NumPy version support should be adjusted upward
+   on every major and minor release, but never on a patch release.
 
 
 Backward compatibility
@@ -171,7 +159,7 @@ Alternatives
 Ad-Hoc version support
 ~~~~~~~~~~~~~~~~~~~~~~
 
-A project could on every release evaluate whether to increase
+A project could, on every release, evaluate whether to increase
 the minimum version of Python supported.
 As a major downside, an ad-hoc approach makes it hard for downstream users to predict what
 the future minimum versions will be.  As there is no objective threshold
@@ -183,16 +171,16 @@ All CPython supported versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The CPython supported versions of Python are listed in the Python
-Developers Guide and the Python PEPs. Supporting these is a very
-clear and conservative approach.  However, it means that there is 4
-year lag between when new language features come into the language and
-when the projects are able to use them.  Additionally, for projects
-that have a significant component of compiled extensions this requires
-building many binary artifacts for each release.
+Developers Guide and the Python PEPs. Supporting these is a very clear
+and conservative approach.  However, it means that there exists a four
+year lag between when a new features is introduced into the language
+and when a project is able to use it.  Additionally, for projects with
+compiled extensions this requires building many binary artifacts for
+each release.
 
 For the case of NumPy, many projects carry workarounds to bugs that
 are fixed in subsequent versions of NumPy.  Being proactive about
-increasing the minimum version of NumPy will allow downstream
+increasing the minimum version of NumPy allows downstream
 packages to carry fewer version-specific patches.
 
 
@@ -203,13 +191,14 @@ Default version on Linux distribution
 The policy could be to support the version of Python that ships by
 default in the latest Ubuntu LTS or CentOS/RHEL release.  However, we
 would still have to standardize across the community which
-distribution we are following.
+distribution to follow.
 
 By following the versions supported by major Linux distributions, we
 are giving up technical control of our projects to external
 organizations that may have different motivations and concerns than we
 do.
 
+
 N minor versions of Python
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -223,12 +212,10 @@ A more fundamental problem with a policy based on number of Python
 releases is that it is hard to predict when support for a given minor
 version of Python will be dropped as that requires correctly
 predicting the release schedule of Python for the next 3-4 years.  A
-time-based rule is only depends on things that have already happened
+time-based rule, in contrast, only depends on past events
 and the length of the support window.
 
 
-
-
 Time window from the X.Y.1 Python release
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~