diff options
| -rw-r--r-- | doc/neps/_static/nep-0000.png | bin | 0 -> 20813 bytes | |||
| -rw-r--r-- | doc/neps/nep-0000.rst | 686 | ||||
| -rw-r--r-- | doc/neps/nep-template.rst | 73 |
3 files changed, 205 insertions, 554 deletions
diff --git a/doc/neps/_static/nep-0000.png b/doc/neps/_static/nep-0000.png Binary files differnew file mode 100644 index 000000000..51eb2b258 --- /dev/null +++ b/doc/neps/_static/nep-0000.png diff --git a/doc/neps/nep-0000.rst b/doc/neps/nep-0000.rst index 8232af4c2..9e3b863bc 100644 --- a/doc/neps/nep-0000.rst +++ b/doc/neps/nep-0000.rst @@ -1,391 +1,167 @@ -PEP: 1 -Title: PEP Purpose and Guidelines -Author: Barry Warsaw, Jeremy Hylton, David Goodger, Nick Coghlan -Status: Active -Type: Process -Content-Type: text/x-rst -Created: 13-Jun-2000 -Post-History: 21-Mar-2001, 29-Jul-2002, 03-May-2003, 05-May-2012, - 07-Apr-2013 - - -What is a PEP? -============== - -PEP stands for Python Enhancement Proposal. A PEP is a design -document providing information to the Python community, or describing -a new feature for Python or its processes or environment. The PEP +======================= +NEP Purpose and Process +======================= + +:Author: Jarrod Millman <millman@berkeley.edu> +:Status: Draft +: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 PEPs to be the primary mechanisms for proposing major new +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 Python. The PEP +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 PEPs are maintained as text files in a versioned +Because the NEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal [1]_. -PEP Types -========= - -There are three kinds of PEP: +Types +^^^^^ -1. A **Standards Track** PEP describes a new feature or implementation - for Python. It may also describe an interoperability standard that will - be supported outside the standard library for current Python versions - before a subsequent PEP adds standard library support in a future - version. +There are two kinds of NEP: -2. An **Informational** PEP describes a Python design issue, or - provides general guidelines or information to the Python community, - but does not propose a new feature. Informational PEPs do not - necessarily represent a Python community consensus or - recommendation, so users and implementers are free to ignore - Informational PEPs or follow their advice. +1. A **Standards Track** NEP describes a new feature or implementation + for NumPy. -3. A **Process** PEP describes a process surrounding Python, or - proposes a change to (or an event in) a process. Process PEPs are - like Standards Track PEPs but apply to areas other than the Python +2. 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 - Python's codebase; they often require community consensus; unlike - Informational PEPs, they are more than recommendations, and users - are typically not free to ignore them. Examples include + 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 Python development. - Any meta-PEP is also considered a Process PEP. + changes to the tools or environment used in NumPy development. + Any meta-NEP is also considered a Process NEP. -PEP Workflow -============ +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. -Python's BDFL -------------- - -There are several references in this PEP to the "BDFL". This acronym stands -for "Benevolent Dictator for Life" and refers to Guido van Rossum, the -original creator of, and the final design authority for, the Python -programming language. +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. +Following a discussion on the mailing list, 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 a formal proposal has been submitted as a PR, it should be announced +on the mailing list. -PEP Editors ------------ +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). -The PEP editors are individuals responsible for managing the administrative -and editorial aspects of the PEP workflow (e.g. assigning PEP numbers and -changing their status). See `PEP Editor Responsibilities & Workflow`_ for -details. The current editors are: -* Chris Angelico -* Anthony Baxter -* Georg Brandl -* Brett Cannon -* David Goodger -* R. David Murray -* Jesse Noller -* Berker Peksag -* Guido van Rossum -* Barry Warsaw +Review and Resolution +^^^^^^^^^^^^^^^^^^^^^ -PEP editorship is by invitation of the current editors, and they can be -contacted via the address <peps@python.org>, but you may only need to use this -to contact the editors semi-privately. All of the PEP workflow can be -conducted via the GitHub `PEP repository`_ issues and pull requests. +NEPs are discussed on the mailing list and perhaps in other forums. +Sometimes NEPs will grow out of an existing pull request. +The possible paths of the status of NEPs are as follows: +.. image:: _static/nep-0000.png -Start with an idea for Python ------------------------------ +All NEPs should be created with the ``Draft`` status. -The PEP process begins with a new idea for Python. It is highly -recommended that a single PEP contain a single key proposal or new -idea. Small enhancements or patches often don't need -a PEP and can be injected into the Python development workflow with a -patch submission to the Python `issue tracker`_. The more focused the -PEP, the more successful it tends to be. The PEP editors reserve the -right to reject PEP proposals if they appear too unfocused or too -broad. If in doubt, split your PEP into several well-focused ones. +Normally, a NEP is ``Accepted`` by consensus of all +interested Contributors. +In unusual cases, the `NumPy Steering Council`_ may be asked to decide whether +a controversial NEP is ``Accepted``. -Each PEP must have a champion -- someone who writes the PEP using the style -and format described below, shepherds the discussions in the appropriate -forums, and attempts to build community consensus around the idea. The PEP -champion (a.k.a. Author) should first attempt to ascertain whether the idea is -PEP-able. Posting to the comp.lang.python newsgroup -(a.k.a. python-list@python.org mailing list) or the python-ideas@python.org -mailing list is the best way to go about this. - -Vetting an idea publicly before going as far as writing a PEP is meant -to save the potential author time. Many ideas have been brought -forward for changing Python that have been rejected for various -reasons. Asking the Python community first if an idea is original -helps prevent too much time being spent on something that is -guaranteed to be rejected based on prior discussions (searching -the internet does not always do the trick). It also helps to make sure -the idea is applicable to the entire community and not just the author. -Just because an idea sounds good to the author does not -mean it will work for most people in most areas where Python is used. - -Once the champion has asked the Python community as to whether an -idea has any chance of acceptance, a draft PEP should be presented to -python-ideas. This gives the author a chance to flesh out the draft -PEP to make properly formatted, of high quality, and to address -initial concerns about the proposal. - - -Submitting a PEP ----------------- - -Following a discussion on python-ideas, the proposal should be submitted as a -draft PEP via a `GitHub pull request`_. The draft must be written in PEP -style as described below, else it will fail review immediately (although minor -errors may be corrected by the editors). - -The standard PEP workflow is: - -* You, the PEP author, fork the `PEP repository`_, and create a file named - ``pep-9999.rst`` that contains your new PEP. Use "9999" as your draft PEP - number. -* Push this to your GitHub fork and submit a pull request. -* The PEP editors review your PR for structure, formatting, and other errors. -* Once approved, they will assign your PEP a number, and label it as Standards - Track, Informational, or Process, and give it the status "Draft" - -Once the review process is complete, and the PEP editors approve it (note that -this is *not* the same as accepting your PEP!), they will squash commit your -pull request onto master. - -The PEP editors will not unreasonably deny a PEP. Reasons for denying PEP -status include duplication of effort, being technically unsound, not providing -proper motivation or addressing backwards compatibility, or not in keeping -with the Python philosophy. The BDFL can be consulted during the approval -phase, and is the final arbiter of the draft's PEP-ability. - -Developers with git push privileges for the `PEP repository`_ may claim PEP -numbers directly by creating and committing a new PEP. When doing so, the -developer must handle the tasks that would normally be taken care of by the -PEP editors (see `PEP Editor Responsibilities & Workflow`_). This includes -ensuring the initial version meets the expected standards for submitting a -PEP. Alternately, even developers may choose to submit PEPs via pull request. -When doing so, let the PEP editors know you have git push privileges and they -can guide you through the process of updating the PEP repository directly. - -As updates are necessary, the PEP author can check in new versions if they -(or a collaborating developer) have git push privileges. - -After a PEP number has been assigned, a draft PEP may be discussed further on -python-ideas (getting a PEP number assigned early can be useful for ease of -reference, especially when multiple draft PEPs are being considered at the -same time). Eventually, all Standards Track PEPs must be sent to the -`python-dev list <mailto:python-dev@python.org>`__ for review as described -in the next section. - -Standards Track PEPs 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 PEP, as ideas that sound -good in principle sometimes turn out to be impractical when subjected to the -test of implementation. - -PEP authors are responsible for collecting community feedback on a PEP -before submitting it for review. However, wherever possible, long -open-ended discussions on public mailing lists should be avoided. -Strategies to keep the discussions efficient include: setting up a -separate SIG mailing list for the topic, having the PEP author accept -private comments in the early design phases, setting up a wiki page, etc. -PEP authors should use their discretion here. - - -PEP Review & Resolution ------------------------ - -Once the authors have completed a PEP, they may request a review for -style and consistency from the PEP editors. However, the content and -final acceptance of the PEP must be requested of the BDFL, usually via -an email to the python-dev mailing list. PEPs are reviewed by the -BDFL and his chosen consultants, who may accept or reject a PEP or -send it back to the author(s) for revision. For a PEP that is -predetermined to be acceptable (e.g., it is an obvious win as-is -and/or its implementation has already been checked in) the BDFL may -also initiate a PEP review, first notifying the PEP author(s) and -giving them a chance to make revisions. - -The final authority for PEP approval is the BDFL. However, whenever a new -PEP is put forward, any core developer that believes they are suitably -experienced to make the final decision on that PEP may offer to serve as -the BDFL's delegate (or "PEP czar") for that PEP. If their self-nomination -is accepted by the other core developers and the BDFL, then they will have -the authority to approve (or reject) that PEP. This process happens most -frequently with PEPs where the BDFL has granted in principle approval for -*something* to be done, but there are details that need to be worked out -before the PEP can be accepted. - -If the final decision on a PEP is to be made by a delegate rather than -directly by the BDFL, this will be recorded by including the -"BDFL-Delegate" header in the PEP. - -PEP review and resolution may also occur on a list other than python-dev -(for example, distutils-sig for packaging related PEPs that don't -immediately affect the standard library). In this case, the "Discussions-To" -heading in the PEP will identify the appropriate alternative list where -discussion, review and pronouncement on the PEP will occur. - -For a PEP to be accepted it must meet certain minimum criteria. It -must be a clear and complete description of the proposed enhancement. -The enhancement must represent a net improvement. The proposed -implementation, if applicable, must be solid and must not complicate -the interpreter unduly. Finally, a proposed enhancement must be -"pythonic" in order to be accepted by the BDFL. (However, "pythonic" -is an imprecise term; it may be defined as whatever is acceptable to -the BDFL. This logic is intentionally circular.) See PEP 2 [2]_ for -standard library module acceptance criteria. - -Once a PEP has been accepted, the reference implementation must be +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". +into the main source code repository, the status will be changed to ``Final``. -A PEP can also be assigned status "Deferred". The PEP author or an -editor can assign the PEP this status when no progress is being made -on the PEP. Once a PEP is deferred, a PEP editor can re-assign it -to draft status. +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 PEP can also be "Rejected". Perhaps after all is said and done it +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 PEP author -themselves has decided that the PEP is actually a bad idea, or has +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 PEP is Accepted, Rejected or Withdrawn, the PEP 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 post -in the python-dev mailing list archives. - -PEPs can also be superseded by a different PEP, rendering the original -obsolete. This is intended for Informational PEPs, where version 2 of -an API can replace version 1. +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 +post in the mailing list archives. -The possible paths of the status of PEPs are as follows: +NEPs can also be ``Replaced`` by a different NEP, rendering the original +obsolete. Process NEPs may also have a status of +``Active`` if they are never meant to be completed. E.g. NEP 0 (this NEP). -.. image:: pep-0001-1.png -Some Informational and Process PEPs may also have a status of "Active" -if they are never meant to be completed. E.g. PEP 1 (this PEP). +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. -PEP Maintenance ---------------- - -In general, Standards track PEPs are no longer modified after they have -reached the Final state. Once a PEP has been completed, the Language and -Standard Library References become the formal documentation of the expected -behavior. - -Informational and Process PEPs may be updated over time to reflect changes +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 PEP being updated. - - - -What belongs in a successful PEP? -================================= - -Each PEP should have the following parts: - -1. Preamble -- RFC 822 style headers containing meta-data about the - PEP, including the PEP number, a short descriptive title (limited - to a maximum of 44 characters), the names, and optionally the - contact info for each author, etc. - -2. Abstract -- a short (~200 word) description of the technical issue - being addressed. - -3. Copyright/public domain -- Each PEP must either be explicitly - labeled as placed in the public domain (see this PEP as an - example) or licensed under the `Open Publication License`_. - -4. Specification -- The technical specification should describe the - syntax and semantics of any new language feature. The - specification should be detailed enough to allow competing, - interoperable implementations for at least the current major Python - platforms (CPython, Jython, IronPython, PyPy). - -5. Motivation -- The motivation is critical for PEPs that want to - change the Python language. It should clearly explain why the - existing language specification is inadequate to address the - problem that the PEP solves. PEP submissions without sufficient - motivation may be rejected outright. - -6. Rationale -- The rationale fleshes out the specification by - describing what motivated the design and why particular design - decisions were made. It should describe alternate designs that - were considered and related work, e.g. how the feature is supported - in other languages. - - The rationale should provide evidence of consensus within the - community and discuss important objections or concerns raised - during discussion. - -7. Backwards Compatibility -- All PEPs that introduce backwards - incompatibilities must include a section describing these - incompatibilities and their severity. The PEP must explain how the - author proposes to deal with these incompatibilities. PEP - submissions without a sufficient backwards compatibility treatise - may be rejected outright. - -8. Reference Implementation -- The reference implementation must be - completed before any PEP is given status "Final", but it need not - be completed before the PEP is accepted. While there is merit - to the approach of reaching consensus on the specification and - rationale before writing code, the principle of "rough consensus - and running code" is still useful when it comes to resolving many - discussions of API details. - - The final implementation must include test code and documentation - appropriate for either the Python language reference or the - standard library reference. - +these cases will depend on the nature and purpose of the NEP being updated. -PEP Formats and Templates -========================= -PEPs are UTF-8 encoded text files using the reStructuredText_ format. -ReStructuredText_ allows for rich markup that is still quite easy to -read, but also results in good-looking and functional HTML. PEP 12 -contains instructions and a template [4]_ for reStructuredText PEPs. +Format and Template +------------------- -A Python script automatically converts PEPs to HTML for viewing on -the web [5]_. The conversion of reStructuredText PEPs is handled by -the Docutils_ module; the same script also renders a legacy plain-text -format of PEP internally, to support pre-reST documents. +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]_. -PEP Header Preamble -=================== +Header Preamble +^^^^^^^^^^^^^^^ -Each PEP must begin with an RFC 822 style header preamble. The headers -must appear in the following order. Headers marked with "*" are -optional and are described below. All other headers are required. :: +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. :: - PEP: <pep number> - Title: <pep title> - Author: <list of authors' real names and optionally, email addrs> - * BDFL-Delegate: <PEP czar's real name> - * Discussions-To: <email address> - Status: <Draft | Active | Accepted | Deferred | Rejected | + :Author: <list of authors' real names and optionally, email addresses> + :Status: <Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded> - Type: <Standards Track | Informational | Process> - * Content-Type: <text/x-rst | text/plain> - * Requires: <pep numbers> - Created: <date created on, in dd-mmm-yyyy format> - * Python-Version: <version number> - Post-History: <dates of postings to python-ideas and/or python-dev> - * Replaces: <pep number> - * Superseded-By: <pep number> - * Resolution: <url> + :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/owners of the PEP. The format of the Author header +of all the authors of the NEP. The format of the Author header value must be Random J. User <address@dom.ain> @@ -394,243 +170,45 @@ if the email address is included, and just Random J. User -if the address is not given. For historical reasons the format -"address@dom.ain (Random J. User)" may appear in a PEP, however new -PEPs must use the mandated format above, and it is acceptable to -change to this format when PEPs are updated. - -If there are multiple authors, each should be on a separate line -following RFC 2822 continuation line conventions. Note that personal -email addresses in PEPs will be obscured as a defense against spam -harvesters. - -The BDFL-Delegate field is used to record cases where the final decision to -approve or reject a PEP rests with someone other than the BDFL. (The -delegate's email address is currently omitted due to a limitation in the -email address masking for reStructuredText PEPs) - -*Note: The Resolution header is required for Standards Track PEPs -only. It contains a URL that should point to an email message or -other web resource where the pronouncement about the PEP is made.* - -For a PEP where final pronouncement will be made on a list other than -python-dev, a Discussions-To header will indicate the mailing list -or URL where the pronouncement will occur. A temporary Discussions-To header -may also be used when a draft PEP is being discussed prior to submission for -pronouncement. No Discussions-To header is necessary if the PEP is being -discussed privately with the author, or on the python-list, python-ideas -or python-dev mailing lists. Note that email addresses in the -Discussions-To header will not be obscured. - -The Type header specifies the type of PEP: Standards Track, -Informational, or Process. - -The format of a PEP is specified with a Content-Type header. The -acceptable values are "text/plain" for plaintext PEPs (see PEP 9 [3]_) -and "text/x-rst" for reStructuredText PEPs (see PEP 12 [4]_). -reStructuredText is strongly preferred, but for backwards -compatibility plain text is currently still the default if no -Content-Type header is present. - -The Created header records the date that the PEP was assigned a -number, while Post-History is used to record the dates of when new -versions of the PEP are posted to python-ideas and/or python-dev. Both -headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001. - -Standards Track PEPs will typically have a Python-Version header which -indicates the version of Python that the feature will be released with. -Standards Track PEPs without a Python-Version header indicate -interoperability standards that will initially be supported through -external libraries and tools, and then supplemented by a later PEP to -add support to the standard library. Informational and Process PEPs do -not need a Python-Version header. - -PEPs may have a Requires header, indicating the PEP numbers that this -PEP depends on. - -PEPs may also have a Superseded-By header indicating that a PEP has -been rendered obsolete by a later document; the value is the number of -the PEP that replaces the current document. The newer PEP must have a -Replaces header containing the number of the PEP that it rendered -obsolete. - - -Auxiliary Files -=============== - -PEPs may include auxiliary files such as diagrams. Such files must be -named ``pep-XXXX-Y.ext``, where "XXXX" is the PEP number, "Y" is a -serial number (starting at 1), and "ext" is replaced by the actual -file extension (e.g. "png"). +if the address is not given. If there are multiple authors, each should be on +a separate line. -Reporting PEP Bugs, or Submitting PEP Updates -============================================= - -How you report a bug, or submit a PEP update depends on several -factors, such as the maturity of the PEP, the preferences of the PEP -author, and the nature of your comments. For the early draft stages -of the PEP, it's probably best to send your comments and changes -directly to the PEP author. For more mature, or finished PEPs you may -want to submit corrections to the Python `issue tracker`_ so that your -changes don't get lost. If the PEP author is a Python developer, assign the -bug/patch to them, otherwise assign it to a PEP editor. +Discussion +---------- -When in doubt about where to send your changes, please check first -with the PEP author and/or a PEP editor. - -PEP authors with git push privileges for the PEP repository can update the -PEPs themselves by using "git push" to submit their changes. - - -Transferring PEP Ownership -========================== - -It occasionally becomes necessary to transfer ownership of PEPs to a -new champion. In general, it is preferable to retain the original author as -a co-author of the transferred PEP, but that's really up to the -original author. A good reason to transfer ownership is because the -original author no longer has the time or interest in updating it or -following through with the PEP process, or has fallen off the face of -the 'net (i.e. is unreachable or not responding to email). A bad -reason to transfer ownership is because the author doesn't agree with the -direction of the PEP. One aim of the PEP process is to try to build -consensus around a PEP, but if that's not possible, an author can always -submit a competing PEP. - -If you are interested in assuming ownership of a PEP, you can also do this via -pull request. Fork the `PEP repository`_, make your ownership modification, -and submit a pull request. You should also send a message asking to take -over, addressed to both the original author and the PEP editors -<peps@python.org>. If the original author doesn't respond to email in a -timely manner, the PEP editors will make a unilateral decision (it's not like -such decisions can't be reversed :). - - -PEP Editor Responsibilities & Workflow -====================================== - -A PEP editor must subscribe to the <peps@python.org> list and must watch the -`PEP repository`_. Most correspondence regarding PEP administration can be -handled through GitHub issues and pull requests, but you may also use -<peps@python.org> for semi-private discussions. Please do not cross-post! - -For each new PEP that comes in an editor does the following: - -* Read the PEP to check if it is ready: sound and complete. The ideas - must make technical sense, even if they don't seem likely to be - accepted. - -* The title should accurately describe the content. - -* Edit the PEP for language (spelling, grammar, sentence structure, - etc.), markup (for reST PEPs), code style (examples should match PEP - 8 & 7). - -If the PEP isn't ready, an editor will send it back to the author for -revision, with specific instructions. - -Once the PEP is ready for the repository, a PEP editor will: - -* Assign a PEP number (almost always just the next available number, - but sometimes it's a special/joke number, like 666 or 3141). - (Clarification: For Python 3, numbers in the 3000s were used for - Py3k-specific proposals. But now that all new features go into - Python 3 only, the process is back to using numbers in the 100s again. - Remember that numbers below 100 are meta-PEPs.) - -* Add the PEP to a local fork of the PEP repository. For workflow - instructions, follow `The Python Developers Guide <http://docs.python.org/devguide>`_ - - The git repo for the peps is:: - - https://github.com/python/peps - -* Run ``./genpepindex.py`` and ``./pep2html.py <PEP Number>`` to ensure they - are generated without errors. If either triggers errors, then the web site - will not be updated to reflect the PEP changes. - -* Commit and push the new (or updated) PEP - -* Monitor python.org to make sure the PEP gets added to the site - properly. If it fails to appear, running ``make`` will build all of the - current PEPs. If any of these are triggering errors, they must be - corrected before any PEP will update on the site. - -* Send email back to the PEP author with next steps (post to - python-list & -dev). - -Updates to existing PEPs should be submitted as a `GitHub pull request`_. -Questions may of course still be sent to <peps@python.org>. - -Many PEPs are written and maintained by developers with write access -to the Python codebase. The PEP editors monitor the python-checkins -list for PEP changes, and correct any structure, grammar, spelling, or -markup mistakes they see. - -PEP editors don't pass judgment on PEPs. They merely do the -administrative & editorial part (which is generally a low volume task). - -Resources: - -* `Index of Python Enhancement Proposals <http://www.python.org/dev/peps/>`_ - -* `Following Python's Development - <http://docs.python.org/devguide/communication.html>`_ - -* `Python Developer's Guide <http://docs.python.org/devguide/>`_ - -* `Frequently Asked Questions for Developers - <http://docs.python.org/devguide/faq.html>`_ +- 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 via HTTP here: - https://github.com/python/peps + for retrieving older revisions, and can also be browsed on + `GitHub <https://github.com/numpy/numpy/tree/master/doc/neps>`_. -.. [2] PEP 2, Procedure for Adding New Modules, Faassen - (http://www.python.org/dev/peps/pep-0002) +.. [2] The URL for viewing NEPs on the web is + https://docs.scipy.org/doc/numpy-1.13.0/neps/index.html. -.. [3] PEP 9, Sample Plaintext PEP Template, Warsaw - (http://www.python.org/dev/peps/pep-0009) +.. _repo: https://github.com/numpy/numpy -.. [4] PEP 12, Sample reStructuredText PEP Template, Goodger, Warsaw - (http://www.python.org/dev/peps/pep-0012) +.. _mailing list: https://mail.python.org/mailman/listinfo/numpy-discussion -.. [5] The script referred to here is pep2pyramid.py, the successor to - pep2html.py, both of which live in the same directory in the hg - repo as the PEPs themselves. Try ``pep2html.py --help`` for - details. The URL for viewing PEPs on the web is - http://www.python.org/dev/peps/. +.. _issue tracker: https://github.com/numpy/numpy/issues -.. _issue tracker: - http://bugs.python.org/ +.. _NumPy Steering Council: + https://docs.scipy.org/doc/numpy-dev/dev/governance/governance.html -.. _Open Publication License: http://www.opencontent.org/openpub/ +.. _`GitHub pull request`: https://github.com/numpy/numpy/pulls .. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Docutils: http://docutils.sourceforge.net/ - -.. _PEP repository: https://github.com/python/peps +.. _reStructuredTextPrimer: http://www.sphinx-doc.org/en/stable/rest.html -.. _`GitHub pull request`: https://github.com/python/peps/pulls +.. _Sphinx: www.sphinx-doc.org/en/stable Copyright -========= +--------- This document has been placed in the public domain. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/doc/neps/nep-template.rst b/doc/neps/nep-template.rst new file mode 100644 index 000000000..d51ad3688 --- /dev/null +++ b/doc/neps/nep-template.rst @@ -0,0 +1,73 @@ +============================= +NEP Template and Instructions +============================= + +:Author: <list of authors' real names and optionally, email addresses> +:Status: <Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded> +:Type: <Standards Track | Informational | Process> +:Created: <date created on, in yyyy-mm-dd format> + + +Abstract +-------- + +The abstract should be a short description of what the NEP will achieve. + + +Detailed description +-------------------- + +This section describes the need for the NEP. It should describe the existing +problem that it is trying to solve and why this NEP makes the situation better. +It should include examples of how the new functionality would be used and +perhaps some use cases. + + +Implementation +-------------- + +This section lists the major steps required to implement the NEP. Where +possible, it should be noted where one step is dependent on another, and which +steps may be optionally omitted. Where it makes sense, each step should +include a link related pull requests as the implementation progresses. + +Any pull requests or development branches containing work on this NEP should +be linked to from here. (A NEP does not need to be implemented in a single +pull request if it makes sense to implement it in discrete phases). + + +Backward compatibility +---------------------- + +This section describes the ways in which the NEP breaks backward compatibility. + + +Alternatives +------------ + +If there were any alternative solutions to solving the same problem, they should +be discussed here, along with a justification for the chosen approach. + + +Discussion +---------- + +This section may just be a bullet list including links to any discussions +regarding the NEP: + +- This includes links to mailing list threads or relevant GitHub issues. + + +References and Footnotes +------------------------ + +.. [1] Each NEP must either be explicitly labeled as placed in the public domain (see + this NEP as an example) or licensed under the `Open Publication License`_. + +.. _Open Publication License: http://www.opencontent.org/openpub/ + + +Copyright +--------- + +This document has been placed in the public domain. [1]_ |
