300 lines
12 KiB
ReStructuredText
300 lines
12 KiB
ReStructuredText
===========================
|
||
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.
|