Re-order and flesh out what belongs in a PEP (#909)

Author: brettcannon

pep-0001.txt

@@ -401,7 +401,7 @@ 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:
+Each PEP should have the following parts/sections:
 
 1. Preamble -- RFC 822 style headers containing meta-data about the
    PEP, including the PEP number, a short descriptive title (limited
@@ -411,40 +411,48 @@ Each PEP should have the following parts:
 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`_.
+3. Motivation -- The motivation is critical for PEPs that want to
+   change the Python language, library, or ecosystem.  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.
 
-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.
+4. Rationale -- The rationale fleshes out the specification by
+   describing 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.
+   
+5. 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).
 
-7. Backwards Compatibility -- All PEPs that introduce backwards
+6. 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.
+   
+7. Security Implications -- If there are security concerns in relation
+   to the PEP, those concerns should be expliciltly written out to make
+   sure reviewers of the PEP are aware of them.
+
+8. How to Teach This -- For a PEP that adds new functionality or changes
+   language behavior, it is helpful to include a section on how to
+   teach users, new and experienced, how to apply the PEP to their
+   work.
 
-8. Reference Implementation -- The reference implementation must be
+   This section may include key points and recommended documentation
+   changes that would help users adopt a new feature or migrate their
+   code to use a language change.
+
+9. 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
@@ -455,15 +463,30 @@ Each PEP should have the following parts:
    The final implementation must include test code and documentation
    appropriate for either the Python language reference or the
    standard library reference.
-
-9. How to Teach This -- For a PEP that adds new functionality or changes
-   language behavior, it is helpful to include a section on how to
-   teach users, new and experienced, how to apply the PEP to their
-   work.
-
-   This section may include key points and recommended documentation
-   changes that would help users adopt a new feature or migrate their
-   code to use a language change.
+   
+10. Rejected Ideas -- Throughout the discussion of a PEP, various ideas
+    will be proposed which are not accepted. Those rejected ideas should
+    be recorded along with the reasoning as to why they were rejected.
+    This both helps record the thought process behind the final version
+    of the PEP as well as preventing people from bringing up the same
+    rejected idea again in subsequent discussions.
+   
+    In a way this section can be thought of as a breakout section of the
+    Rationale section that is focused specifically on why certain ideas
+    were not ultimately pursued.
+
+11. Open Issues -- While a PEP is in draft, ideas can come up which
+    warrant further discussion. Those ideas should be recorded so people
+    know that they are being thought about but do not have a concrete
+    resolution. This helps make sure all issues required for the PEP to be
+    ready for consideration are complete complete and reduces people
+    duplicating prior discussion.
+    
+12. References -- A collection of URLs used as references through the PEP. 
+   
+13. 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`_.
 
 
 PEP Formats and Templates