SF.net SVN: docutils:[10101] trunk
milde--- via Docutils-checkins <[email protected]> Tue, 22 Apr 2025 14:04:44 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10101
http://sourceforge.net/p/docutils/code/10101
Author: milde
Date: 2025-04-22 14:04:43 +0000 (Tue, 22 Apr 2025)
Log Message:
-----------
Set up enhancement proposals in developer documentation.
Cf. [feature-requests:#111].
Modified Paths:
--------------
trunk/docutils/docs/index.rst
Added Paths:
-----------
trunk/docutils/docs/eps/
trunk/docutils/docs/eps/ep-001.rst
trunk/docutils/docs/eps/ep-010.rst
trunk/docutils/docs/eps/ep-template.rst
trunk/docutils/docs/eps/header.rst
trunk/docutils/docs/eps/index.rst
Removed Paths:
-------------
trunk/sandbox/enhancement-proposals/dep-999-backwards-compatibility.txt
trunk/sandbox/enhancement-proposals/dep-NNN.txt
Added: trunk/docutils/docs/eps/ep-001.rst
===================================================================
--- trunk/docutils/docs/eps/ep-001.rst (rev 0)
+++ trunk/docutils/docs/eps/ep-001.rst 2025-04-22 14:04:43 UTC (rev 10101)
@@ -0,0 +1,455 @@
+.. include:: header.rst
+
+=========================================
+EP 1 — Docutils EP Purpose and Guidelines
+=========================================
+
+:Author: 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
+==========
+
+.. Explain why the existing specification is inadequate
+
+`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
+=========
+
+.. Describe why particular design decisions were made.
+
+*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
+=============
+
+.. Describe the syntax and semantics of any new feature.
+
+.. note::
+ The key words "*must*", "*must not*", "*required*", "*shall*",
+ "*shall not*", *should*", "*should not*", "*recommended*", "*may*",
+ and "*optional*" are to be interpreted as described in :RFC:`2119`.
+
+A `Docutils Enhancement Proposal` (EP) [#dep]_ is a reStructuredText_
+document with a preamble_ and a standard set of sections_.
+
+.. [#dep] Deciding on an abbreviation for `Docutils Enhancement Proposals`
+ is one of the `open issues`_.
+
+
+Preamble
+--------
+
+The preamble *should* contain the following `Bibliographic Fields`_:
+
+
+.. class:: field-indent-8em
+
+:Author [#]_: 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 [#iso8601]_ that the proposal was assigned a number.
+:Abstract: A short description of the technical issue being addressed.
+
+As appropriate, it *may* contain
+
+.. class:: field-indent-8em
+
+: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 [#iso8601]_ with link to the acceptance/rejection post.
+
+.. [#] Use "Authors_" if there is more than one author.
+.. [#iso8601] in ISO 8601 format (yyyy-mm-dd)
+
+
+Sections
+--------
+
+Each standard EP *should* have the following sections:
+
+.. class:: description
+
+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.
+
+ .. _`sec: rationale`:
+
+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 <sec: 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.
+
+ .. _`sec: rejected ideas`:
+
+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 <sec: 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.
+
+
+Backwards Compatibility
+=======================
+
+.. Describe potential impact and severity on pre-existing code.
+
+`Enhancement Proposals` will supplement rather than replace existing
+communication channels.
+
+`Issue tickets`_ with a long list of comments will gain from a
+consolidation into a related EP.
+Some sections of the `Docutils To Do List`_ may be moved to an EP.
+
+
+Security Implications
+=====================
+
+.. How could a malicious user take advantage of this new feature?
+
+A structured discussion of proposed changes including their security
+implications will help `deploying Docutils securely`_.
+
+
+How to Teach This
+=================
+
+.. How to teach users, new and experienced, how to apply the proposal to
+ their work.
+
+Enhancement proposals will be included in the `Docutils documentation`__.
+
+In the FAQ entry "`How can I get a new feature into Docutils?`_",
+we should add a paragraph like
+
+ If discussion of a bug, patch, or feature request ticket_ spans more
+ than one page, it may be time to consider turning it into an
+ `enhancement proposal`.
+ (The existing ticket should be referenced in the "Discussions-To" or
+ "Post-History" preamble_ field.)
+
+__ ../index.html#enhancement-proposals
+
+
+Reference Implementation
+========================
+
+.. Link to any existing implementation and details about its state, e.g.
+ proof-of-concept.
+
+The sandbox_ contains a directory for
+`enhancement proposals in "pre-draft" stage`_.
+
+
+Rejected Ideas
+==============
+
+.. Why certain ideas that were brought while discussing this proposal
+ were not ultimately pursued.
+
+
+Open Issues
+===========
+
+.. Any points that are still being decided/discussed.
+
+* 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,
+
+
+References
+==========
+
+.. A collection of URLs used as references through the proposal.
+
+.. [PEP1] `PEP Purpose and Guidelines`,
+ Barry Warsaw, Jeremy Hylton, David Goodger, Alyssa Coghlan,
+ 13-Jun-2000, https://peps.python.org/pep-0001/
+
+Enhancement Proposals in _`other projects`
+------------------------------------------
+
+.. class:: field-indent-3em
+
+:EPs: used by
+
+:AEP__: AiiDA__ workflow manager for computational science
+
+ __ https://github.com/aiidateam/AEP
+ __ https://www.aiida.net/
+
+:CEP__: Cassandra__ distributed database
+
+ __ https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=95652201
+ __ https://cwiki.apache.org/confluence/display/CASSANDRA/
+
+:DEP__: Debian__ Linux distribution
+
+ __ https://dep-team.pages.debian.net/
+ __ https://www.debian.org
+
+:DEP__: Django__ Web framework
+
+ __ https://github.com/django/deps
+ __ http://www.djangoproject.com/
+
+:DEP__: Dylan__ programming language
+
+ __ https://opendylan.org/proposals/index.html
+ __ https://opendylan.org/
+
+:IEP__: `International Standard Content Code`__ content-based identifier
+
+ __ https://ieps.iscc.codes/
+ __ https://iscc.codes/
+
+
+:JEP__: OpenJDK__ Java Platform
+
+ __ https://openjdk.org/jeps/0
+ __ https://openjdk.org/
+
+:JEP__: Jenkins__ automation server
+
+ __ https://github.com/jenkinsci/jep
+ __ https://www.jenkins.io/
+
+:JEP__: Project Jupyter__ interactive computing
+
+ __ https://github.com/jupyter/enhancement-proposals
+ __ https://jupyter.org/
+
+:Julep__: Julia__ programming language
+
+ __ https://github.com/JuliaLang/Juleps
+ __ https://julialang.org/
+
+:KEEP__: Kotline__ programming language
+
+ __ https://github.com/Kotlin/KEEP
+ __ https://kotlinlang.org/
+
+:KEP__: Kubernetes__ container orchestration system
+
+ __ https://www.kubernetes.dev/resources/keps/
+ __ https://kubernetes.io/
+
+:MEP__: Matplotlib__ data visualisation library
+
+ __ https://matplotlib.org/3.10.0/devel/MEP/index.html
+ __ https://matplotlib.org
+
+:MEP__: MyST__ markup language and abstract syntax tree
+
+ __ https://mep.myst-tools.org/en/latest/
+ __ https://mystmd.org/
+
+:NEP__: NEAR__ proof-of-stake blockchain
+
+ __ https://github.com/near/NEPs
+ __ https://docs.near.org/
+
+:NEP__: NumPy__ package for scientific computing with Python
+
+ __ https://numpy.org/neps/
+ __ https://numpy.org/
+
+:PEP_: Python__ programming language
+
+ __ https://www.python.org/
+
+:PLEP__: PlasmaPy__ package for plasma research and education
+
+ __ https://github.com/PlasmaPy/PlasmaPy-PLEPs
+ __ https://docs.plasmapy.org
+
+:REP__: ROS__ Robot Operating System
+
+ __ https://www.ros.org/reps/rep-0000.html
+ __ https://www.ros.org/
+
+:REP__: Ray__ unified Python framework for machine learning
+
+ __ https://github.com/ray-project/enhancements
+ __ https://docs.ray.io/
+
+:SEP__: Salt__ event-driven automation engine (EPs deprecated__!)
+
+ __ https://github.com/saltstack/salt-enhancement-proposals
+ __ https://docs.saltproject.io
+ __ https://github.com/saltstack/salt-enhancement-proposals
+ #deprecation-of-sep-process
+
+:SLEP__: scikit-learn__ Machine Learning in Python
+
+ __ https://github.com/scikit-learn/enhancement_proposals
+ __ https://scikit-learn.org
+
+:STEP__: sktime__ time series analysis in Python
+
+ __ https://github.com/sktime/enhancement-proposals
+ __ https://www.sktime.net
+
+:ZEP__: Zarr__ specifications and software for storage of large tensors
+
+ __ https://zarr.dev/zeps/active/ZEP0000.html
+ __ https://zarr.dev/
+
+
+.. URI references
+ --------------
+
+.. _Python Enhancement Proposals:
+.. _PEP:
+.. _PEPs: https://peps.python.org/
+.. _PEP review & resolution:
+ https://peps.python.org/pep-0001/#pep-review-resolution
+
+.. _feature-requests 111:
+ https://sourceforge.net/p/docutils/feature-requests/111/
+.. _sandbox: https://docutils.sourceforge.io/sandbox/README.html
+.. _enhancement proposals in "pre-draft" stage:
+ https://docutils.sourceforge.io/sandbox/enhancement-proposals/
+.. _ticket:
+.. _issue tickets: https://sourceforge.net/p/docutils/_list/tickets
+
+.. _Docutils To Do List: ../dev/todo.html
+.. _security documentation:
+.. _Deploying Docutils Securely:
+ ../howto/security.html
+.. _document model:
+ ../ref/doctree.html
+.. _reStructuredText:
+ ../ref/rst/restructuredtext.html
+.. _bibliographic fields:
+ ../ref/rst/restructuredtext.html#bibliographic-fields
+.. _Authors:
+ ../ref/rst/restructuredtext.html#authors
+.. _How can I get a new feature into Docutils?:
+ ../../FAQ.html#how-can-i-get-a-new-feature-into-docutils
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.
Copied: trunk/docutils/docs/eps/ep-010.rst (from rev 10094, trunk/sandbox/enhancement-proposals/dep-999-backwards-compatibility.txt)
===================================================================
--- trunk/docutils/docs/eps/ep-010.rst (rev 0)
+++ trunk/docutils/docs/eps/ep-010.rst 2025-04-22 14:04:43 UTC (rev 10101)
@@ -0,0 +1,309 @@
+.. include:: header.rst
+
+=====================================================
+EP 10 — Public API and Backwards Compatibility Policy
+=====================================================
+
+:Authors: Günter Milde, Adam Turner
+:Discussions-To: https://sourceforge.net/p/docutils/feature-requests/89/
+:Status: Draft
+:Type: Process
+:Created: 2025-04-22
+:Docutils-Version: 1.0
+:Abstract:
+ This document suggests a definition of the public APIs provided by the
+ Docutils project and the backwards compatibility policy.
+
+.. contents::
+
+
+Motivation
+==========
+
+.. Clearly explain why the existing specification is inadequate to
+ address the problem that the proposal solves.
+
+Docutils has a large user base and is used in production at several
+places (Python documentation, Linux kernel documentation, CMake
+documentation, readthedocs, ...). OTOH, Docutils has a version number
+below 1.0 (widely seen as an indicator of "beta" status of a project).
+
+The current `Docutils Project Policies`_ section on `version
+identifcation`_ concentrates on the formal definition of the version
+specifier but leaves open what consists a "major change in the design
+or API".
+
+The current `backwards compatibility policy`_ is a stub referencing
+:PEP:`387`.
+
+
+Rationale
+=========
+
+.. Describe why particular design decisions were made.
+
+Clearly defining how we will balance evolution with stability is
+important to both users and project developers.
+
+People affected by changes in Docutils include:
+
+.. class:: description
+
+Authors
+ writing or maintaining reStructuredText documents.
+
+End-Users
+ of Docutils native `front-end tools`_ (optionally with 3rd-party
+ drop-in extensions) or alternative tools using Docutils either as a
+ library (Sphinx_, …) or via the command line interface
+ (build systems, Makefiles, scripts in other languages).
+
+Developers
+ i.e. authors and maintainers of
+
+ - projects that use Docutils as a library (Sphinx_, rsted_, Leo_,
+ Pelican_, ebookmaker_, MyST_, readthedocs_, rinohtype_, …),
+ - drop-in components (pycmark_, rst2pdf_, rst2beamer_, …),
+ - alternative front-end tools,
+ - custom stylesheets (CSS style sheets, LaTeX styles, ODT styles),
+ or
+ - re-implementations of the `reStructuredText specification`_,
+ e.g. Pandoc_ or Text-Restructured_ (prest).
+
+A person may belong to more than one of these catgories.
+
+.. _Sphinx: https://www.sphinx-doc.org/
+.. _rsted: https://github.com/anru/rsted
+.. _Leo: https://leo-editor.github.io/leo-editor/
+.. _Pelican: https://docs.getpelican.com/en/latest/
+.. _MyST: https://myst-parser.readthedocs.io/
+.. _readthedocs: https://readthedocs.org/
+.. _pycmark: https://github.com/pycmark/pycmark
+.. _rst2pdf: https://rst2pdf.org/
+.. _rst2beamer: https://docutils.sourceforge.io/sandbox/rst2beamer/
+.. _rinohtype: https://pypi.org/project/rinohtype/
+.. _ebookmaker: https://pypi.org/project/ebookmaker/
+.. _PanDoc: https://pandoc.org/
+.. _Text-Restructured: https://metacpan.org/dist/Text-Restructured
+
+
+Specification
+=============
+
+.. Describe the syntax and semantics of any new feature.
+
+Docutils public APIs are:
+
+* the `reStructuredText specification`_,
+
+* the `Docutils document structure`_ (`Docutils Document Tree`),
+
+* names, command-line arguments and behaviour of
+ the `"console_scripts" entry points`_ (`Front-end Tools`),
+
+* the core ``docutils`` Python package API:
+
+ - the `Docutils Publisher`_ interface for programmatic use,
+
+ - component interfaces as defined by the abstract base classes
+ `docutils.reader.Reader`, `docutils.writer.Writer`, and
+ `docutils.transform.Transform`,
+
+* behaviour and names of all *documented Python objects*, [#]_
+
+* *output templates* and *style sheets* provided with the writers,
+
+ .. template.txt, default.tex, titlepage.tex, xelatex.tex
+ .. html4css1.css, minimal.css, docutils.sty (LaTeX), styles.odt
+
+* the interface to custom stylesheets -- elements, macros and classes
+ used by writers to represent doctree_ nodes in the output format.
+
+Exemptions:
+ Python objects, stylesheets and templates can explicitly "opt-out" of
+ the public API with a docstring noting that the object is provisional_
+ or internal.
+
+ All undocumented objects should be assumed to be internal. [#]_
+
+See also the `API Reference Material for Client-Developers`_.
+
+.. [#] Cf. `PEP 387: Backwards Compatibility Rules`_
+.. [#] Cf. `PEP 008: Public and Internal Interfaces`_
+
+
+Backwards Compatibility
+=======================
+
+.. Describe potential impact and severity on pre-existing code.
+
+Beginning with version 1.0, Docutils will follow the rules of
+`Semantic Versioning`_. All incompatible changes to the public APIs
+require increasing the `major` part of the `version specifier`_.
+Backwards compatible changes can be done in `minor` releases.
+
+
+Security Implications
+=====================
+
+If required, critical bug fixes may change the public API without advance
+warning.
+
+
+How to Teach This
+=================
+
+.. How to teach users, new and experienced,
+ how to apply the proposal to their work.
+
+* Move the API specification_ and the backwards compatibility declaration
+ to the `Docutils Project Policies`_.
+
+* Complete the API documentation and keep it up to date.
+
+* Generate "docutils" package API documentation from the docstrings:
+
+ - Fix/enhance/add docstrings to improve the output of `pydoc`_.
+
+ - Generate API documentation with Sphinx:
+
+ - nicely format rST docstrings
+ - include attribute docstrings (ignored by pydoc_).
+
+* Put the following text at a suitable place in the documentation:
+
+ To find out if an object from the "docutils" package is safe to use,
+ look up its docstring and the docstring of its parent(s) [#]_.
+
+ If there is no documentation or the documentation says "provisional" or
+ "internal", the name, behaviour, and existence of the object is not
+ guaranteed to be stable.
+
+ Code relying on non-public objects should be made robust using
+ public alternatives. If there is a no such alternative or the
+ required change would be a problem, `contact the Docutils
+ developers`__ or file a `feature request`_.
+
+ .. [#] `Attribute docstrings`_ are not shown by pydoc_. To find out
+ whether attributes have a docstring, check the source.
+
+ .. _attribute docstrings:
+ https://peps.python.org/pep-0258/#attribute-docstrings
+ .. _pydoc: https://docs.python.org/3/library/pydoc.html
+ __ https://docutils.sourceforge.io/docs/user/mailing-lists.html
+ .. _feature request: https://sourceforge.net/p/docutils/feature-requests/
+
+
+Rejected Ideas
+==============
+
+.. Why certain ideas that were brought while discussing this proposal were not
+ ultimately pursued.
+
+* Use type annotations as an indication of status in the public API.
+
+ - There is no known precedence for this approach.
+ - Type annotations may be helpful also for non-public code.
+
+* Use Calendar Versioning (CalVer).
+
+ - Would be a break from current versioning without clear advantages.
+
+* Allow breaking API changes in *minor* versions after prior announcement
+ and a deprecation period.
+
+ - Breaks the principle of least surprise.
+
+* Enumerate all modules, classes, and functions that form the public API.
+
+* Mark all private objects with a prefix underscore.
+
+ - May needlessly break applications that use "internal" objects by the
+ current name.
+ - Too much work.
+
+
+Open Issues
+===========
+
+.. Any points that are still being decided/discussed.
+
+* Differentiate between "core API" and "extended API"?
+
+ Cf. the `Docutils Project Policies`_
+
+ When Docutils reaches version 1.0, the major APIs will be considered
+ frozen.
+
+ The major number [...] may be incremented later if there is a major
+ change in the design or API.
+
+
+* Formalise the wording for docstrings for public/private/provisional
+ (ideally this would be a single regex pattern)?
+
+ * The keyword provisional_ is well defined. ✓
+ * Use "private" or "internal"?
+
+* Declare only objects included in the ``__all__`` attribute of their
+ parent objects as public rsp. explicitely list all public objects in
+ ``__all__`` attribute of their parents?
+
+ This would hide private objects from `pydoc` help on the parent objects.
+
+* Define a minimum deprecation time similar to Docbook__? E.g.
+
+ * A "major" release may contain backward-incompatible changes if:
+
+ * the change was announced in the release notes for the previous
+ version (major or minor) and
+ * the change was announced in a release that occurred at least six
+ months previously.
+
+ By these rules, Docutils developers can announce, in release 5.1, for
+ example, its plans to make a backward-incompatible change in release 6.0.
+ Then, in 6.0, if it’s been at least six months since 5.1 was
+ released, they can make that change.
+
+ __ https://tdg.docbook.org/tdg/5.1/ch01.html#bwcompat
+
+
+References
+==========
+
+.. A collection of URLs used as references through the proposal.
+
+.. _API Reference Material for Client-Developers:
+ ../index.html#api-reference-material-for-client-developers
+.. _doctree:
+.. _Docutils document structure: ../ref/doctree.html
+.. _docutils.dtd: ../ref/docutils.dtd
+.. _Docutils Design Specification: ../peps/pep-0258.html
+.. _Docutils Project Policies: ../dev/policies.html
+.. _version specifier:
+.. _version identifcation:
+ ../dev/policies.html#version-identification
+.. _backwards compatibility policy:
+ ../dev/policies.html#backwards-compatibility-policy
+.. _"console_scripts" entry points:
+.. _front-end tools: ../user/tools.html
+.. _Docutils Publisher: ../api/publisher.html
+.. _Docutils Transforms: ../ref/transforms.html
+.. _HISTORY: ../docutils/HISTORY.html
+.. _RELEASE-NOTES: ../docutils/RELEASE-NOTES.html
+.. _reStructuredText specification:
+ ../ref/rst/restructuredtext.html
+
+.. _`PEP 387: backwards compatibility rules`:
+ https://peps.python.org/pep-0387/#backwards-compatibility-rules
+.. _`PEP 008: Public and Internal Interfaces`:
+ https://peps.python.org/pep-0008/#public-and-internal-interfaces
+.. _provisional: https://docs.python.org/3/glossary.html#term-provisional-API
+.. _Semantic Versioning: https://semver.org/
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.
Copied: trunk/docutils/docs/eps/ep-template.rst (from rev 10094, trunk/sandbox/enhancement-proposals/dep-NNN.txt)
===================================================================
--- trunk/docutils/docs/eps/ep-template.rst (rev 0)
+++ trunk/docutils/docs/eps/ep-template.rst 2025-04-22 14:04:43 UTC (rev 10101)
@@ -0,0 +1,97 @@
+.. include:: header.rst
+
+==========================
+<EP number> — <title>
+==========================
+
+:Author: <name and optional e-mail; use ``:Authors:`` for a list>
+:Discussions-To: <current discussion thread and/or enhancement ticket URL>
+:Status: <Draft | Active | Accepted | Provisional | Deferred |
+ Rejected | Withdrawn | Final | Superseded>
+:Created: <yyyy-mm-dd>
+
+ .. optional
+:Docutils-Version: <first release including the new feature>
+:Post-History: <past discussion threads and/or issue tickets>
+:Type: <Standard (default) | Informational | Process>
+:Topic: <API | reStructuredText | DocTree | HTML output | ...>
+:Requires: <EP number(s)>
+:Replaces: <current EP, policy or API document>
+:Superseded-By: <EP number>
+:Resolution: <`yyyy-mm-dd <link to decision>`__>
+
+:Abstract:
+ .. A short (<~200 word) description of the technical issue being addressed.
+
+.. contents::
+
+
+Motivation
+==========
+
+.. Clearly explain why the existing specification is inadequate to
+ address the problem that the proposal solves.
+
+
+Rationale
+=========
+
+.. Describe why particular design decisions were made.
+
+
+Specification
+=============
+
+.. Describe the syntax and semantics of any new feature.
+
+
+Backwards Compatibility
+=======================
+
+.. Describe potential impact and severity on pre-existing code.
+
+
+Security Implications
+=====================
+
+.. How could a malicious user take advantage of this new feature?
+
+
+How to Teach This
+=================
+
+.. How to teach users, new and experienced, how to apply the proposal to
+ their work.
+
+
+Reference Implementation
+========================
+
+.. Link to any existing implementation and details about its state, e.g.
+ proof-of-concept.
+
+
+Rejected Ideas
+==============
+
+.. Why certain ideas that were brought while discussing this proposal
+ were not ultimately pursued.
+
+
+Open Issues
+===========
+
+.. Any points that are still being decided/discussed.
+
+
+References
+==========
+
+.. A collection of footnotes and references.
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.
Added: trunk/docutils/docs/eps/header.rst
===================================================================
--- trunk/docutils/docs/eps/header.rst (rev 0)
+++ trunk/docutils/docs/eps/header.rst 2025-04-22 14:04:43 UTC (rev 10101)
@@ -0,0 +1,12 @@
+.. Minimal menu bar for inclusion in enhancement proposal sources
+ in ``docutils/docs/eps/``.
+
+ Attention: this is not a standalone document.
+
+.. header::
+ Docutils__ | Overview__ | `Enhancement Proposals`__
+
+ __ https://docutils.sourceforge.io
+
+ __ ../index.html
+ __ index.html
Added: trunk/docutils/docs/eps/index.rst
===================================================================
--- trunk/docutils/docs/eps/index.rst (rev 0)
+++ trunk/docutils/docs/eps/index.rst 2025-04-22 14:04:43 UTC (rev 10101)
@@ -0,0 +1,25 @@
+.. include:: ../header.rst
+
+================================
+ Docutils Enhancement Proposals
+================================
+
+A framework for proposing major new features, collecting community input
+on an issue, and documenting the design decisions that have gone into
+Docutils and the reStructuredText format.
+
+For details see `Docutils EP Purpose and Guidelines`_.
+The `template file <ep-template.rst>`_ can be used as
+starting point for new enhancement proposals.
+
+Index
+-----
+
+=== ========================================================= ===========
+# Title Status
+=== ========================================================= ===========
+001 `Docutils EP Purpose and Guidelines <ep-001.html>`_ Draft
+
+010 `Public API and Backwards Compatibility Policy Draft
+ <ep-010.html>`_
+=== ========================================================= ===========
Modified: trunk/docutils/docs/index.rst
===================================================================
--- trunk/docutils/docs/index.rst 2025-04-22 12:34:00 UTC (rev 10100)
+++ trunk/docutils/docs/index.rst 2025-04-22 14:04:43 UTC (rev 10101)
@@ -191,6 +191,12 @@
Docutils developer.
+Docutils Enhancement Proposals
+==============================
+
+* `Enhancement Proposal Index <eps/index.html>`__
+
+
.. _howto:
Instructions for Developers
Deleted: trunk/sandbox/enhancement-proposals/dep-999-backwards-compatibility.txt
===================================================================
--- trunk/sandbox/enhancement-proposals/dep-999-backwards-compatibility.txt 2025-04-22 12:34:00 UTC (rev 10100)
+++ trunk/sandbox/enhancement-proposals/dep-999-backwards-compatibility.txt 2025-04-22 14:04:43 UTC (rev 10101)
@@ -1,323 +0,0 @@
-=============================================
-Public API and Backwards Compatibility Policy
-=============================================
-
-:Author: Günter Milde, Adam Turner, open to all Docutils developers
-:Discussions-To: [email protected], https://sourceforge.net/p/docutils/feature-requests/89/
-:Status: Draft
-:Type: Process
-:Created: 2022-01-21
-:Docutils-Version: 0.19
-
-
-Abstract
-========
-
-.. A short (<~200 word) description of the technical issue being addressed.
-
-This document suggests a definition of the public APIs provided by the
-Docutils project and the backwards compatibility policy.
-
-
-Motivation
-==========
-
-.. Clearly explain why the existing specification is inadequate to
- address the problem that the proposal solves.
-
-Docutils has a large user base and is used in production at several
-places (Python documentation, Linux kernel documentation, CMake
-documentation, readthedocs, ...). OTOH, Docutils has a version number
-below 1.0 (widely seen as an indicator of "beta" status of a project).
-
-The current `Docutils Project Policies`_ section on `version
-identifcation`_ concentrates on the formal definition of the version
-specifier but leaves open what consists a "major change in the design
-or API".
-
-The current `backwards compatibility policy`__ is only a stub referencing
-:PEP:`387`.
-
-Clearly defining how we will balance evolution with stability is
-important to both users and project developers.
-
-.. _version specifier:
-.. _version identifcation:
- ../../docutils/docs/dev/policies.html#version-identification
-__ ../../docutils/docs/dev/policies.html#backwards-compatibility-policy
-
-
-Rationale
-=========
-
-.. Describe why particular design decisions were made.
-
-People affected by changes in Docutils include:
-
-.. class:: description
-
-Authors
- writing or maintaining reStructuredText documents.
-
-End-Users
- of Docutils native `front-end tools`_ (optionally with 3rd-party
- drop-in extensions) or alternative tools using Docutils either as a
- library (Sphinx_, …) or via the command line interface
- (build systems, Makefiles, scripts in other languages).
-
-Developers
- authors and maintainers of
-
- - projects that use Docutils as a library (Sphinx_, rsted_, Leo_,
- Pelican_, ebookmaker_, MyST_, readthedocs_, rinohtype_, …),
- - drop-in components (pycmark_, rst2pdf_, rst2beamer_, …),
- - alternative front-end tools,
- - custom stylesheets (CSS style sheets, LaTeX styles, ODT styles),
- or
- - re-implementations of the `reStructuredText specification`_,
- e.g. PanDoc_ or Text-Restructured_ (prest).
-
-A person may belong to more than one of these catgories.
-
-.. _Sphinx: https://www.sphinx-doc.org/
-.. _rsted: https://github.com/anru/rsted
-.. _Leo: https://leoeditor.com
-.. _Pelican: https://docs.getpelican.com/en/latest/
-.. _MyST: https://myst-parser.readthedocs.io/
-.. _readthedocs: https://readthedocs.org/
-.. _pycmark: https://github.com/pycmark/pycmark
-.. _rst2pdf: https://rst2pdf.org/
-.. _rst2beamer: https://docutils.sourceforge.io/sandbox/rst2beamer/
-.. _rinohtype: https://pypi.org/project/rinohtype/
-.. _ebookmaker: https://pypi.org/project/ebookmaker/
-.. _PanDoc: https://pandoc.org/
-.. _Text-Restructured: https://metacpan.org/dist/Text-Restructured
-
-
-Specification
-=============
-
-.. Describe the syntax and semantics of any new feature.
-
-Docutils public APIs are:
-
-* the `reStructuredText specification`_,
-
-* the `Docutils document structure`_ (`Docutils Document Tree`),
-
-* names, command-line arguments and behaviour of
- the `"console_scripts" entry points`_ (`Front-end Tools`),
-
-* the core ``docutils`` Python package API:
-
- - the `Docutils Publisher`_ interface for programmatic use,
-
- - component interfaces as defined by the base
- `docutils.reader.Reader`, `docutils.writer.Writer`, and
- `docutils.transform.Transform` classes,
-
-* behaviour and names of all *documented Python objects*, [#]_
-
-* *output templates* and *style sheets* provided with the writers,
-
- .. template.txt, default.tex, titlepage.tex, xelatex.tex
- .. html4css1.css, minimal.css, docutils.sty (LaTeX), styles.odt
-
-* the interface to custom stylesheets -- elements, macros and classes
- used by writers to represent doctree_ nodes in the output format.
-
-Exemptions:
- Python objects, stylesheets and templates can explicitly "opt-out" of
- the public API with a docstring noting that the object is provisional_
- or internal.
-
- All undocumented objects should be assumed to be internal. [#]_
-
-See also the `API Reference Material for Client-Developers`_.
-
-.. [#] Cf. `PEP 387: Backwards Compatibility Rules`_
-.. [#] Cf. `PEP 008: Public and Internal Interfaces`_
-
-
-Backwards Compatibility
-=======================
-
-.. Describe potential impact and severity on pre-existing code.
-
-Beginning with version 1.0, Docutils will follow the rules of
-`Semantic Versioning`_. All incompatible changes to the public APIs
-require increasing the `major` part of the `version specifier`_.
-Backwards compatible changes can be done in `minor` releases.
-
-
-Security Implications
-=====================
-
-If required, critical bug fixes may change the public API without advance
-warning.
-
-
-How to Teach This
-=================
-
-.. How to teach users, new and experienced,
- how to apply the proposal to their work.
-
-* Move the API specification_ and the backwards compatibility declaration
- to the `Docutils Project Policies`_.
-
-* Complete the `api/`_ documentation and keep it up to date.
-
-* Generate "docutils" package API documentation from the docstrings:
-
- - Fix/enhance/add docstrings to improve the output of `pydoc`_.
-
- - Generate API documentation with Sphinx:
-
- - nicely format rST docstrings
- - include attribute docstrings (ignored by pydoc_).
-
-* Put the following text at a suitable place in the documentation:
-
- To find out if an object from the "docutils" package is safe to use,
- look up its docstring and the docstring of its parent [#]_.
-
- If there is no documentation or the documentation says "provisional" or
- "internal", the name, behaviour, and existence of the object is not
- guaranteed to be stable.
-
- Code relying on non-public objects should be made robust using
- public alternatives. If there is a no such alternative or the
- required change would be a problem, `contact the Docutils
- developers`__ or file a `feature request`_.
-
- .. [#] `Attribute docstrings`_ are not shown by pydoc_. To find out
- whether attributes have a docstring, check the source.
-
- .. _attribute docstrings:
- https://peps.python.org/pep-0258/#attribute-docstrings
- .. _pydoc: https://docs.python.org/3/library/pydoc.html
- __ https://docutils.sourceforge.io/docs/user/mailing-lists.html
- .. _feature request: https://sourceforge.net/p/docutils/feature-requests/
-
-
-Rejected Ideas
-==============
-
-.. Why certain ideas that were brought while discussing this proposal were not
- ultimately pursued.
-
-* Use type annotations as an indication of status in the public API.
-
- - There is no known precedence for this approach.
- - Type annotations may be helpful also for non-public code.
-
-* Use Calendar Versioning (CalVer).
-
- - Would be a break from current versioning without clear advantages.
-
-* Allow breaking API changes in *minor* versions after prior announcement
- and a deprecation period.
-
- - Breaks the principle of least surprise.
-
-* Enumerate all modules, classes, and functions that form the public API.
-
-* Mark all private objects with a prefix underscore.
-
- - May needlessly break applications that use "internal" objects by the
- current name.
- - Too much work.
-
-
-Open Issues
-===========
-
-.. Any points that are still being decided/discussed.
-
-* Differentiate between "core API" and "extended API"?
-
- Cf. the `Docutils Project Policies`_
-
- When Docutils reaches version 1.0, the major APIs will be considered
- frozen.
-
- The major number [...] may be incremented later if there is a major
- change in the design or API.
-
-
-* Formalise the wording for docstrings for public/private/provisional
- (ideally this would be a single regex pattern)?
-
- * The keyword provisional_ is well defined. ✓
- * Use "private" or "internal"?
-
-* Declare only objects included in the ``__all__`` attribute of their
- parent objects as public rsp. explicitely list all public objects in
- ``__all__`` attribute of their parents?
-
- This would hide private objects from `pydoc` help on the parent objects.
-
-* Define a minimum deprecation time similar to Docbook__? E.g.
-
- * A "major" release may contain backward-incompatible changes if:
-
- * the change was announced in the release notes for the previous
- version (major or minor) and
- * the change was announced in a release that occurred at least six
- months previously.
-
- By these rules, Docutils developers can announce, in release 5.1, for
- example, its plans to make a backward-incompatible change in release 6.0.
- Then, in 6.0, if it’s been at least six months since 5.1 was
- released, they can make that change.
-
- __ https://tdg.docbook.org/tdg/5.1/ch01.html#bwcompat
-
-
-References
-==========
-
-.. A collection of URLs used as references through the proposal.
-
-.. _api/:
-.. _API Reference Material for Client-Developers:
- ../../docutils/docs/index.html
- #api-reference-material-for-client-developers
-.. _doctree:
-.. _Docutils document structure: ../../docutils/docs/ref/doctree.html
-.. _docutils.dtd: ../../docutils/docs/ref/docutils.dtd
-.. _Docutils Design Specification: ../../docutils/docs/peps/pep-0258.html
-.. _Docutils Project Policies: ../../docutils/docs/dev/policies.html
-.. _"console_scripts" entry points:
-.. _front-end tools: ../../docutils/docs/user/tools.html
-.. _Docutils Publisher: ../../docutils/docs/api/publisher.html
-.. _Docutils Transforms: ../../docutils/docs/ref/transforms.html
-.. _HISTORY: ../../docutils/HISTORY.html
-.. _RELEASE-NOTES: ../../docutils/RELEASE-NOTES.html
-.. _reStructuredText specification:
- ../../docutils/docs/ref/rst/restructuredtext.html
-
-.. _`PEP 387: backwards compatibility rules`:
- https://peps.python.org/pep-0387/#backwards-compatibility-rules
-.. _`PEP 008: Public and Internal Interfaces`:
- https://peps.python.org/pep-0008/#public-and-internal-interfaces
-.. _provisional: https://docs.python.org/3/glossary.html#term-provisional-API
-.. _Semantic Versioning: https://semver.org/
-
-Copyright
-=========
-
-This document is placed in the public domain or under the
-CC0-1.0-Universal license, whichever is more permissive.
-
-
-
-..
- Local Variables:
- mode: indented-text
- indent-tabs-mode: nil
- sentence-end-double-space: t
- fill-column: 70
- coding: utf-8
- End:
Deleted: trunk/sandbox/enhancement-proposals/dep-NNN.txt
===================================================================
--- trunk/sandbox/enhancement-proposals/dep-NNN.txt 2025-04-22 12:34:00 UTC (rev 10100)
+++ trunk/sandbox/enhancement-proposals/dep-NNN.txt 2025-04-22 14:04:43 UTC (rev 10101)
@@ -1,100 +0,0 @@
-==================================
-:Title: <REQUIRED: proposal title>
-==================================
-
-:Author: <REQUIRED: list of authors' real names and optionally, email addrs>
-:Discussions-To: [email protected], <enhancement ticket URL>
-:Status: <REQUIRED: Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
-:Type: <REQUIRED: API | Informational | Process>
-:Created: <date created on, in dd-mmm-yyyy format>
-:Docutils-Version: <version number>
-:Replaces: current policy/API document
-:Resolution: <url>
-
-
-Abstract
-========
-
-.. A short (<~200 word) description of the technical issue being addressed.
-
-
-Motivation
-==========
-
-.. Clearly explain why the existing specification is inadequate to
- address the problem that the proposal solves.
-
-
-Rationale
-=========
-
-.. Describe why particular design decisions were made.
-
-
-Specification
-=============
-
-.. Describe the syntax and semantics of any new feature.
-
-
-Backwards Compatibility
-=======================
-
-.. Describe potential impact and severity on pre-existing code.
-
-
-Security Implications
-=====================
-
-.. How could a malicious user take advantage of this new feature?
-
-
-How to Teach This
-=================
-
-.. How to teach users, new and experienced, how to apply the proposal to
- their work.
-
-
-Reference Implementation
-========================
-
-.. Link to any existing implementation and details about its state, e.g.
- proof-of-concept.
-
-
-Rejected Ideas
-==============
-
-.. Why certain ideas that were brought while discussing this proposal
- were not ultimately pursued.
-
-
-Open Issues
-===========
-
-.. Any points that are still being decided/discussed.
-
-
-References
-==========
-
-.. A collection of URLs used as references through the proposal.
-
-
-Copyright
-=========
-
-This document is placed in the public domain or under the
-CC0-1.0-Universal license, whichever is more permissive.
-
-
-
-..
- Local Variables:
- mode: indented-text
- indent-tabs-mode: nil
- sentence-end-double-space: t
- fill-column: 70
- coding: utf-8
- End:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins