Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from Mar 5, 2019
Merged
Changes from all commits
Commits
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

@@ -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`_.

This conversation was marked as resolved by brettcannon

This comment has been minimized.

Copy link
@gvanrossum

gvanrossum Mar 4, 2019

Member

Should we perhaps make a security section mandatory too? Or at least mention that if there are any security concerns they should be collected in a separate section? (Because if most PEPs don't have security issues, requiring everyone to have a section "Security concerns" that says "There are none" is a bit silly.)

This comment has been minimized.

Copy link
@willingc

willingc Mar 4, 2019

Contributor

Similar to Section 7: How to Teach, there could be a Section x: Deployment, Configuration, and Security that highlights any specific deployment, configuration, or security processes or best practices when used.


PEP Formats and Templates
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.