2021-01-14 08:07:24 +01:00
|
|
|
|
===========================
|
|
|
|
|
NEP 0 — Purpose and Process
|
|
|
|
|
===========================
|
|
|
|
|
|
|
|
|
|
:Author: Jarrod Millman <millman@berkeley.edu>
|
|
|
|
|
:Status: Active
|
|
|
|
|
:Type: Process
|
|
|
|
|
:Created: 2017-12-11
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
What is a NEP?
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
NEP stands for NumPy Enhancement Proposal. A NEP is a design
|
|
|
|
|
document providing information to the NumPy community, or describing
|
|
|
|
|
a new feature for NumPy or its processes or environment. The NEP
|
|
|
|
|
should provide a concise technical specification of the feature and a
|
|
|
|
|
rationale for the feature.
|
|
|
|
|
|
|
|
|
|
We intend NEPs to be the primary mechanisms for proposing major new
|
|
|
|
|
features, for collecting community input on an issue, and for
|
|
|
|
|
documenting the design decisions that have gone into NumPy. The NEP
|
|
|
|
|
author is responsible for building consensus within the community and
|
|
|
|
|
documenting dissenting opinions.
|
|
|
|
|
|
|
|
|
|
Because the NEPs are maintained as text files in a versioned
|
|
|
|
|
repository, their revision history is the historical record of the
|
|
|
|
|
feature proposal [1]_.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Types
|
|
|
|
|
^^^^^
|
|
|
|
|
|
|
|
|
|
There are three kinds of NEPs:
|
|
|
|
|
|
|
|
|
|
1. A **Standards Track** NEP describes a new feature or implementation
|
|
|
|
|
for NumPy.
|
|
|
|
|
|
|
|
|
|
2. An **Informational** NEP describes a NumPy design issue, or provides
|
|
|
|
|
general guidelines or information to the Python community, but does not
|
|
|
|
|
propose a new feature. Informational NEPs do not necessarily represent a
|
|
|
|
|
NumPy community consensus or recommendation, so users and implementers are
|
|
|
|
|
free to ignore Informational NEPs or follow their advice.
|
|
|
|
|
|
|
|
|
|
3. A **Process** NEP describes a process surrounding NumPy, or
|
|
|
|
|
proposes a change to (or an event in) a process. Process NEPs are
|
|
|
|
|
like Standards Track NEPs but apply to areas other than the NumPy
|
|
|
|
|
language itself. They may propose an implementation, but not to
|
|
|
|
|
NumPy's codebase; they require community consensus. Examples include
|
|
|
|
|
procedures, guidelines, changes to the decision-making process, and
|
|
|
|
|
changes to the tools or environment used in NumPy development.
|
|
|
|
|
Any meta-NEP is also considered a Process NEP.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
NEP Workflow
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
The NEP process begins with a new idea for NumPy. It is highly
|
|
|
|
|
recommended that a single NEP contain a single key proposal or new
|
|
|
|
|
idea. Small enhancements or patches often don't need
|
|
|
|
|
a NEP and can be injected into the NumPy development workflow with a
|
|
|
|
|
pull request to the NumPy `repo`_. The more focused the
|
|
|
|
|
NEP, the more successful it tends to be.
|
|
|
|
|
If in doubt, split your NEP into several well-focused ones.
|
|
|
|
|
|
|
|
|
|
Each NEP must have a champion---someone who writes the NEP using the style
|
|
|
|
|
and format described below, shepherds the discussions in the appropriate
|
|
|
|
|
forums, and attempts to build community consensus around the idea. The NEP
|
|
|
|
|
champion (a.k.a. Author) should first attempt to ascertain whether the idea is
|
|
|
|
|
suitable for a NEP. Posting to the numpy-discussion `mailing list`_ is the best
|
|
|
|
|
way to go about doing this.
|
|
|
|
|
|
|
|
|
|
The proposal should be submitted as a draft NEP via a `GitHub pull
|
|
|
|
|
request`_ to the ``doc/neps`` directory with the name ``nep-<n>.rst``
|
|
|
|
|
where ``<n>`` is an appropriately assigned four-digit number (e.g.,
|
|
|
|
|
``nep-0000.rst``). The draft must use the :doc:`nep-template` file.
|
|
|
|
|
|
|
|
|
|
Once the PR for the NEP is in place, a post should be made to the
|
|
|
|
|
mailing list containing the sections up to "Backward compatibility",
|
|
|
|
|
with the purpose of limiting discussion there to usage and impact.
|
|
|
|
|
Discussion on the pull request will have a broader scope, also including
|
|
|
|
|
details of implementation.
|
|
|
|
|
|
|
|
|
|
At the earliest convenience, the PR should be merged (regardless of
|
|
|
|
|
whether it is accepted during discussion). Additional PRs may be made
|
|
|
|
|
by the Author to update or expand the NEP, or by maintainers to set
|
|
|
|
|
its status, discussion URL, etc.
|
|
|
|
|
|
|
|
|
|
Standards Track NEPs consist of two parts, a design document and a
|
|
|
|
|
reference implementation. It is generally recommended that at least a
|
|
|
|
|
prototype implementation be co-developed with the NEP, as ideas that sound
|
|
|
|
|
good in principle sometimes turn out to be impractical when subjected to the
|
|
|
|
|
test of implementation. Often it makes sense for the prototype implementation
|
|
|
|
|
to be made available as PR to the NumPy repo (making sure to appropriately
|
|
|
|
|
mark the PR as a WIP).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Review and Resolution
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
NEPs are discussed on the mailing list. The possible paths of the
|
|
|
|
|
status of NEPs are as follows:
|
|
|
|
|
|
|
|
|
|
.. image:: _static/nep-0000.png
|
|
|
|
|
|
|
|
|
|
All NEPs should be created with the ``Draft`` status.
|
|
|
|
|
|
|
|
|
|
Eventually, after discussion, there may be a consensus that the NEP
|
|
|
|
|
should be accepted – see the next section for details. At this point
|
|
|
|
|
the status becomes ``Accepted``.
|
|
|
|
|
|
|
|
|
|
Once a NEP has been ``Accepted``, the reference implementation must be
|
|
|
|
|
completed. When the reference implementation is complete and incorporated
|
|
|
|
|
into the main source code repository, the status will be changed to ``Final``.
|
|
|
|
|
|
|
|
|
|
To allow gathering of additional design and interface feedback before
|
|
|
|
|
committing to long term stability for a language feature or standard library
|
|
|
|
|
API, a NEP may also be marked as "Provisional". This is short for
|
|
|
|
|
"Provisionally Accepted", and indicates that the proposal has been accepted for
|
|
|
|
|
inclusion in the reference implementation, but additional user feedback is
|
|
|
|
|
needed before the full design can be considered "Final". Unlike regular
|
|
|
|
|
accepted NEPs, provisionally accepted NEPs may still be Rejected or Withdrawn
|
|
|
|
|
even after the related changes have been included in a Python release.
|
|
|
|
|
|
|
|
|
|
Wherever possible, it is considered preferable to reduce the scope of a
|
|
|
|
|
proposal to avoid the need to rely on the "Provisional" status (e.g. by
|
|
|
|
|
deferring some features to later NEPs), as this status can lead to version
|
|
|
|
|
compatibility challenges in the wider NumPy ecosystem.
|
|
|
|
|
|
|
|
|
|
A NEP can also be assigned status ``Deferred``. The NEP author or a
|
|
|
|
|
core developer can assign the NEP this status when no progress is being made
|
|
|
|
|
on the NEP.
|
|
|
|
|
|
|
|
|
|
A NEP can also be ``Rejected``. Perhaps after all is said and done it
|
|
|
|
|
was not a good idea. It is still important to have a record of this
|
|
|
|
|
fact. The ``Withdrawn`` status is similar---it means that the NEP author
|
|
|
|
|
themselves has decided that the NEP is actually a bad idea, or has
|
|
|
|
|
accepted that a competing proposal is a better alternative.
|
|
|
|
|
|
|
|
|
|
When a NEP is ``Accepted``, ``Rejected``, or ``Withdrawn``, the NEP should be
|
|
|
|
|
updated accordingly. In addition to updating the status field, at the very
|
|
|
|
|
least the ``Resolution`` header should be added with a link to the relevant
|
|
|
|
|
thread in the mailing list archives.
|
|
|
|
|
|
|
|
|
|
NEPs can also be ``Superseded`` by a different NEP, rendering the
|
|
|
|
|
original obsolete. The ``Replaced-By`` and ``Replaces`` headers
|
|
|
|
|
should be added to the original and new NEPs respectively.
|
|
|
|
|
|
|
|
|
|
Process NEPs may also have a status of ``Active`` if they are never
|
|
|
|
|
meant to be completed, e.g. NEP 0 (this NEP).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
How a NEP becomes Accepted
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
A NEP is ``Accepted`` by consensus of all interested contributors. We
|
|
|
|
|
need a concrete way to tell whether consensus has been reached. When
|
|
|
|
|
you think a NEP is ready to accept, send an email to the
|
|
|
|
|
numpy-discussion mailing list with a subject like:
|
|
|
|
|
|
|
|
|
|
Proposal to accept NEP #<number>: <title>
|
|
|
|
|
|
|
|
|
|
In the body of your email, you should:
|
|
|
|
|
|
|
|
|
|
* link to the latest version of the NEP,
|
|
|
|
|
|
|
|
|
|
* briefly describe any major points of contention and how they were
|
|
|
|
|
resolved,
|
|
|
|
|
|
|
|
|
|
* include a sentence like: "If there are no substantive objections
|
|
|
|
|
within 7 days from this email, then the NEP will be accepted; see
|
|
|
|
|
NEP 0 for more details."
|
|
|
|
|
|
|
|
|
|
For an example, see: https://mail.python.org/pipermail/numpy-discussion/2018-June/078345.html
|
|
|
|
|
|
|
|
|
|
After you send the email, you should make sure to link to the email
|
|
|
|
|
thread from the ``Discussion`` section of the NEP, so that people can
|
|
|
|
|
find it later.
|
|
|
|
|
|
|
|
|
|
Generally the NEP author will be the one to send this email, but
|
|
|
|
|
anyone can do it – the important thing is to make sure that everyone
|
|
|
|
|
knows when a NEP is on the verge of acceptance, and give them a final
|
|
|
|
|
chance to respond. If there's some special reason to extend this final
|
|
|
|
|
comment period beyond 7 days, then that's fine, just say so in the
|
|
|
|
|
email. You shouldn't do less than 7 days, because sometimes people are
|
|
|
|
|
travelling or similar and need some time to respond.
|
|
|
|
|
|
|
|
|
|
In general, the goal is to make sure that the community has consensus,
|
|
|
|
|
not provide a rigid policy for people to try to game. When in doubt,
|
|
|
|
|
err on the side of asking for more feedback and looking for
|
|
|
|
|
opportunities to compromise.
|
|
|
|
|
|
|
|
|
|
If the final comment period passes without any substantive objections,
|
|
|
|
|
then the NEP can officially be marked ``Accepted``. You should send a
|
|
|
|
|
followup email notifying the list (celebratory emoji optional but
|
|
|
|
|
encouraged 🎉✨), and then update the NEP by setting its ``:Status:``
|
|
|
|
|
to ``Accepted``, and its ``:Resolution:`` header to a link to your
|
|
|
|
|
followup email.
|
|
|
|
|
|
|
|
|
|
If there *are* substantive objections, then the NEP remains in
|
|
|
|
|
``Draft`` state, discussion continues as normal, and it can be
|
|
|
|
|
proposed for acceptance again later once the objections are resolved.
|
|
|
|
|
|
|
|
|
|
In unusual cases, the `NumPy Steering Council`_ may be asked to decide
|
|
|
|
|
whether a controversial NEP is ``Accepted``.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Maintenance
|
|
|
|
|
^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
In general, Standards track NEPs are no longer modified after they have
|
|
|
|
|
reached the Final state as the code and project documentation are considered
|
|
|
|
|
the ultimate reference for the implemented feature.
|
|
|
|
|
However, finalized Standards track NEPs may be updated as needed.
|
|
|
|
|
|
|
|
|
|
Process NEPs may be updated over time to reflect changes
|
|
|
|
|
to development practices and other details. The precise process followed in
|
|
|
|
|
these cases will depend on the nature and purpose of the NEP being updated.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Format and Template
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
NEPs are UTF-8 encoded text files using the reStructuredText_ format. Please
|
|
|
|
|
see the :doc:`nep-template` file and the reStructuredTextPrimer_ for more
|
|
|
|
|
information. We use Sphinx_ to convert NEPs to HTML for viewing on the web
|
|
|
|
|
[2]_.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Header Preamble
|
|
|
|
|
^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
Each NEP must begin with a header preamble. The headers
|
|
|
|
|
must appear in the following order. Headers marked with ``*`` are
|
|
|
|
|
optional. All other headers are required. ::
|
|
|
|
|
|
|
|
|
|
:Author: <list of authors' real names and optionally, email addresses>
|
|
|
|
|
:Status: <Draft | Active | Accepted | Deferred | Rejected |
|
|
|
|
|
Withdrawn | Final | Superseded>
|
|
|
|
|
:Type: <Standards Track | Process>
|
|
|
|
|
:Created: <date created on, in dd-mmm-yyyy format>
|
|
|
|
|
* :Requires: <nep numbers>
|
|
|
|
|
* :NumPy-Version: <version number>
|
|
|
|
|
* :Replaces: <nep number>
|
|
|
|
|
* :Replaced-By: <nep number>
|
|
|
|
|
* :Resolution: <url>
|
|
|
|
|
|
|
|
|
|
The Author header lists the names, and optionally the email addresses
|
|
|
|
|
of all the authors of the NEP. The format of the Author header
|
|
|
|
|
value must be
|
|
|
|
|
|
|
|
|
|
Random J. User <address@dom.ain>
|
|
|
|
|
|
|
|
|
|
if the email address is included, and just
|
|
|
|
|
|
|
|
|
|
Random J. User
|
|
|
|
|
|
|
|
|
|
if the address is not given. If there are multiple authors, each should be on
|
|
|
|
|
a separate line.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Discussion
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
- https://mail.python.org/pipermail/numpy-discussion/2017-December/077481.html
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
References and Footnotes
|
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
|
|
.. [1] This historical record is available by the normal git commands
|
|
|
|
|
for retrieving older revisions, and can also be browsed on
|
|
|
|
|
`GitHub <https://github.com/numpy/numpy/tree/master/doc/neps>`_.
|
|
|
|
|
|
|
|
|
|
.. [2] The URL for viewing NEPs on the web is
|
|
|
|
|
https://www.numpy.org/neps/.
|
|
|
|
|
|
|
|
|
|
.. _repo: https://github.com/numpy/numpy
|
|
|
|
|
|
|
|
|
|
.. _mailing list: https://mail.python.org/mailman/listinfo/numpy-discussion
|
|
|
|
|
|
|
|
|
|
.. _issue tracker: https://github.com/numpy/numpy/issues
|
|
|
|
|
|
|
|
|
|
.. _NumPy Steering Council:
|
|
|
|
|
https://docs.scipy.org/doc/numpy/dev/governance/governance.html
|
|
|
|
|
|
|
|
|
|
.. _`GitHub pull request`: https://github.com/numpy/numpy/pulls
|
|
|
|
|
|
|
|
|
|
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
|
|
|
|
|
|
|
|
|
.. _reStructuredTextPrimer: http://www.sphinx-doc.org/en/stable/rest.html
|
|
|
|
|
|
|
|
|
|
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Copyright
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
This document has been placed in the public domain.
|