EP 1 — Docutils EP Purpose and Guidelines

Preamble

The preamble should contain the following Bibliographic Fields:

Author [2]:

Author name and, optionally, email address (in angle brackets).

Discussions-To:

URL of the current discussion thread and/or issue ticket.

Status:

One of "Draft", "Active", "Accepted", "Provisional", "Deferred", "Rejected", "Withdrawn", "Final", or "Superseded" (cf. PEP Review & Resolution).

Created:

Date [3] that the proposal was assigned a number.

Abstract:

A short description of the technical issue being addressed.

As appropriate, it may contain

Docutils-Version:

Number of the first release including the new feature.

Post-History:

List of past discussion threads and/or issue tickets.

Type:

One of "Standard" (default), "Informational", "Process".

Topic:

Special topic (affected component or part), e.g. "reStructuredText", "Document Model", "HTML output", …

Requires:

Number(s) of EP(s) this proposal depends on.

Replaces:

Current policy, API document, or EP.

Superseded-By:

Number of EP obsoleting this proposal.

Resolution:

Date [3] with link to the acceptance/rejection post.

Sections

Each standard EP should have the following sections:

Motivation:

Clearly explain why the existing specification is inadequate to address the problem that the proposal solves.

The motivation is critical for proposals that want to change the reStructuredText language or the Docutils document model, library, or ecosystem. Proposals without sufficient motivation may be rejected.

Rationale:

Describe why particular design decisions were made.

The rationale 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 (see also rejected Ideas below).

Specification:

Describe the syntax and semantics of any new feature.

The specification should be detailed enough to allow competing, interoperable implementations.

Backwards Compatibility:

Describe potential impact and severity on pre-existing code.

The proposal must explain how the author attempts to deal with these incompatibilities. Proposal submissions without a sufficient backwards compatibility treatise may be rejected outright.

Security Implications:

How could a malicious user take advantage of this new feature?

If there are security concerns in relation to the PEP, those concerns should be explicitly written out to make sure reviewers of the PEP are aware of them. If applicable, include a suggestion how to update the security documentation.

How to Teach This:

How to teach users, new and experienced, how to apply the proposal 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 make use of the new feature.

Reference Implementation:

Link to any existing implementation and details about its state, e.g. proof-of-concept.

The reference implementation must be completed before any PEP is given status “Final”, but it need not be completed before the PEP is accepted. The final implementation must include test code and documentation.

Rejected Ideas:

Why certain ideas that were brought while discussing this proposal were not ultimately pursued.

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.

A brief discussion of rejected ideas should be included in the Rationale.

Open Issues:

Any points that are still being decided/discussed.

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 and reduces people duplicating prior discussion.

References:

A collection of footnotes and references.

Copyright:

The copyright notice.

See the copyright of this document for a suggestion.

Enhancement Proposals in other projects

EPs:

used by

AEP:

AiiDA workflow manager for computational science

CEP:

Cassandra distributed database

DEP:

Debian Linux distribution

DEP:

Django Web framework

DEP:

Dylan programming language

IEP:

International Standard Content Code content-based identifier

JEP:

OpenJDK Java Platform

JEP:

Jenkins automation server

JEP:

Project Jupyter interactive computing

Julep:

Julia programming language

KEEP:

Kotline programming language

KEP:

Kubernetes container orchestration system

MEP:

Matplotlib data visualisation library

MEP:

MyST markup language and abstract syntax tree

NEP:

NEAR proof-of-stake blockchain

NEP:

NumPy package for scientific computing with Python

PEP:

Python programming language

PLEP:

PlasmaPy package for plasma research and education

REP:

ROS Robot Operating System

REP:

Ray unified Python framework for machine learning

SEP:

Salt event-driven automation engine (EPs deprecated!)

SLEP:

scikit-learn Machine Learning in Python

STEP:

sktime time series analysis in Python

ZEP:

Zarr specifications and software for storage of large tensors