EP 1 — Docutils EP Purpose and Guidelines (original) (raw)

Günter Milde

Discussions-To:

feature-requests 111

Status:

Draft

Type:

Process

Created:

2025-04-22

Docutils-Version:

0.22

Abstract

Docutils Enhancement Proposals are a mechanism for proposing major new features, collecting community input, and documenting important design decisions. This document describes their purpose and structure. It borrows heavily from Python Enhancement Proposals. [PEP1]

The document is still a draft -- suggestions and contributions are welcome.

Contents

Motivation
Rationale
Specification
- Preamble
- Sections
Backwards Compatibility
Security Implications
How to Teach This
Reference Implementation
Rejected Ideas
Open Issues
References
- Enhancement Proposals in other projects
Copyright

Motivation

Issue tickets on the project page and the Docutils To Do List are established channels for suggesting changes to Docutils and reStructuredText. They work fine for small changes or issues with one obvious solution. However, we are missing a framework for complex cases with competing alternative approaches and for documenting the internal processes at the Docutils project.

Rationale

Enhancement Proposals are used by a wide range of projects of different size (see References). David Goodger suggested using enhancement proposals in a lightweight formal process for the Docutils project.

Specification

A Docutils Enhancement Proposal (EP) [1] is a reStructuredTextdocument with a preamble and a standard set of sections.

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 thereStructuredText 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 thesecurity 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 theRationale.

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.

The copyright notice.

See the copyright of this document for a suggestion.

If discussion of a bug, patch, or feature request ticket spans more than one page, it may be time to consider turning it into anenhancement proposal. (The existing ticket should be referenced in the "Discussions-To" or "Post-History" preamble field.)

How to abbreviate Docutils Enhancement Proposal?
David Goodger proposed "DocutilsEP" or "DEP" or just "EP". Alternatively we may use an unambiguous abbreviation like "DuEP" or "DUEP" for Documentation Utilities Enhancement Proposal.
See also the abbreviations used by other projects.
Put the EP number in
- the title, preceding the topic,
- a sub-title,
- the title with the topic as sub-title,
- an "EP" preamble field,