sandbox/enhancement-proposals/dep-999-backwards-compatibility.txt

   1 =============================================
   2 Public API and Backwards Compatibility Policy
   3 =============================================
   4
   5 :Author: Günter Milde, Adam Turner, open to all Docutils developers
   6 :Discussions-To: docutils-develop@lists.sf.net, https://sourceforge.net/p/docutils/feature-requests/89/
   7 :Status: Draft
   8 :Type: Process
   9 :Created: 2022-01-21
  10 :Docutils-Version: 0.19
  11
  12
  13 Abstract
  14 ========
  15
  16 .. A short (<~200 word) description of the technical issue being addressed.
  17
  18 This document suggests a definition of the public APIs provided by the
  19 Docutils project and the backwards compatibility policy.
  20
  21
  22 Motivation
  23 ==========
  24
  25 .. Clearly explain why the existing specification is inadequate to
  26    address the problem that the proposal solves.
  27
  28 Docutils has a large user base and is used in production at several
  29 places (Python documentation, Linux kernel documentation, CMake
  30 documentation, readthedocs, ...). OTOH, Docutils has a version number
  31 below 1.0 (widely seen as an indicator of "beta" status of a project).
  32
  33 The current `Docutils Project Policies`_ section on `version
  34 identifcation`_ concentrates on the formal definition of the version
  35 specifier but leaves open what consists a "major change in the design
  36 or API".
  37
  38 The current `backwards compatibility policy`__ is only a stub referencing
  39 :PEP:`387`.
  40
  41 Clearly defining how we will balance evolution with stability is
  42 important to both users and project developers.
  43
  44 .. _version specifier:
  45 .. _version identifcation:
  46    ../../docutils/docs/dev/policies.html#version-identification
  47 __ ../../docutils/docs/dev/policies.html#backwards-compatibility-policy
  48
  49
  50 Rationale
  51 =========
  52
  53 .. Describe why particular design decisions were made.
  54
  55 People affected by changes in Docutils include:
  56
  57 .. class:: description
  58
  59 Authors
  60   writing or maintaining reStructuredText documents.
  61
  62 End-Users
  63   of Docutils native `front-end tools`_ (optionally with 3rd-party
  64   drop-in extensions) or alternative tools using Docutils either as a
  65   library (Sphinx_, …) or via the command line interface
  66   (build systems, Makefiles, scripts in other languages).
  67
  68 Developers
  69   authors and maintainers of
  70
  71   - projects that use Docutils as a library (Sphinx_, rsted_, Leo_,
  72     Pelican_, ebookmaker_, MyST_, readthedocs_, rinohtype_, …),
  73   - drop-in components (pycmark_, rst2pdf_, rst2beamer_, …),
  74   - alternative front-end tools,
  75   - custom stylesheets (CSS style sheets, LaTeX styles, ODT styles),
  76     or
  77   - re-implementations of the `reStructuredText specification`_,
  78     e.g. PanDoc_ or Text-Restructured_ (prest).
  79
  80 A person may belong to more than one of these catgories.
  81
  82 .. _Sphinx: https://www.sphinx-doc.org/
  83 .. _rsted: https://github.com/anru/rsted
  84 .. _Leo: https://leoeditor.com
  85 .. _Pelican: https://docs.getpelican.com/en/latest/
  86 .. _MyST: https://myst-parser.readthedocs.io/
  87 .. _readthedocs: https://readthedocs.org/
  88 .. _pycmark: https://github.com/pycmark/pycmark
  89 .. _rst2pdf: https://rst2pdf.org/
  90 .. _rst2beamer: https://docutils.sourceforge.io/sandbox/rst2beamer/
  91 .. _rinohtype: https://pypi.org/project/rinohtype/
  92 .. _ebookmaker: https://pypi.org/project/ebookmaker/
  93 .. _PanDoc: https://pandoc.org/
  94 .. _Text-Restructured: https://metacpan.org/dist/Text-Restructured
  95
  96
  97 Specification
  98 =============
  99
 100 .. Describe the syntax and semantics of any new feature.
 101
 102 Docutils public APIs are:
 103
 104 * the `reStructuredText specification`_,
 105
 106 * the `Docutils document structure`_ (`Docutils Document Tree`),
 107
 108 * names, command-line arguments and behaviour of
 109   the `"console_scripts" entry points`_ (`Front-end Tools`),
 110
 111 * the core ``docutils`` Python package API:
 112
 113   - the `Docutils Publisher`_ interface for programmatic use,
 114
 115   - component interfaces as defined by the base
 116     `docutils.reader.Reader`, `docutils.writer.Writer`, and
 117     `docutils.transform.Transform` classes,
 118
 119 * behaviour and names of all *documented Python objects*, [#]_
 120
 121 * *output templates* and *style sheets* provided with the writers,
 122
 123   .. template.txt, default.tex, titlepage.tex, xelatex.tex
 124   .. html4css1.css, minimal.css, docutils.sty (LaTeX), styles.odt
 125
 126 * the interface to custom stylesheets -- elements, macros and classes
 127   used by writers to represent doctree_ nodes in the output format.
 128
 129 Exemptions:
 130   Python objects, stylesheets and templates can explicitly "opt-out" of
 131   the public API with a docstring noting that the object is provisional_
 132   or internal.
 133
 134   All undocumented objects should be assumed to be internal. [#]_
 135
 136 See also the `API Reference Material for Client-Developers`_.
 137
 138 .. [#] Cf. `PEP 387: Backwards Compatibility Rules`_
 139 .. [#] Cf. `PEP 008: Public and Internal Interfaces`_
 140
 141
 142 Backwards Compatibility
 143 =======================
 144
 145 .. Describe potential impact and severity on pre-existing code.
 146
 147 Beginning with version 1.0, Docutils will follow the rules of
 148 `Semantic Versioning`_. All incompatible changes to the public APIs
 149 require increasing the `major` part of the `version specifier`_.
 150 Backwards compatible changes can be done in `minor` releases.
 151
 152
 153 Security Implications
 154 =====================
 155
 156 If required, critical bug fixes may change the public API without advance
 157 warning.
 158
 159
 160 How to Teach This
 161 =================
 162
 163 .. How to teach users, new and experienced,
 164    how to apply the proposal to their work.
 165
 166 * Move the API specification_ and the backwards compatibility declaration
 167   to the `Docutils Project Policies`_.
 168
 169 * Complete the `api/`_ documentation and keep it up to date.
 170
 171 * Generate "docutils" package API documentation from the docstrings:
 172
 173   - Fix/enhance/add docstrings to improve the output of `pydoc`_.
 174
 175   - Generate API documentation with Sphinx:
 176
 177     - nicely format rST docstrings
 178     - include attribute docstrings (ignored by pydoc_).
 179
 180 * Put the following text at a suitable place in the documentation:
 181
 182      To find out if an object from the "docutils" package is safe to use,
 183      look up its docstring and the docstring of its parent [#]_.
 184
 185      If there is no documentation or the documentation says "provisional" or
 186      "internal", the name, behaviour, and existence of the object is not
 187      guaranteed to be stable.
 188
 189      Code relying on non-public objects should be made robust using
 190      public alternatives. If there is a no such alternative or the
 191      required change would be a problem, `contact the Docutils
 192      developers`__ or file a `feature request`_.
 193
 194      .. [#] `Attribute docstrings`_ are not shown by pydoc_. To find out
 195         whether attributes have a docstring, check the source.
 196
 197      .. _attribute docstrings:
 198          https://peps.python.org/pep-0258/#attribute-docstrings
 199      .. _pydoc: https://docs.python.org/3/library/pydoc.html
 200      __ https://docutils.sourceforge.io/docs/user/mailing-lists.html
 201      .. _feature request: https://sourceforge.net/p/docutils/feature-requests/
 202
 203
 204 Rejected Ideas
 205 ==============
 206
 207 .. Why certain ideas that were brought while discussing this proposal were not
 208    ultimately pursued.
 209
 210 * Use type annotations as an indication of status in the public API.
 211
 212   - There is no known precedence for this approach.
 213   - Type annotations may be helpful also for non-public code.
 214
 215 * Use Calendar Versioning (CalVer).
 216
 217   - Would be a break from current versioning without clear advantages.
 218
 219 * Allow breaking API changes in *minor* versions after prior announcement
 220   and a deprecation period.
 221
 222   - Breaks the principle of least surprise.
 223
 224 * Enumerate all modules, classes, and functions that form the public API.
 225
 226 * Mark all private objects with a prefix underscore.
 227
 228   - May needlessly break applications that use "internal" objects by the
 229     current name.
 230   - Too much work.
 231
 232
 233 Open Issues
 234 ===========
 235
 236 .. Any points that are still being decided/discussed.
 237
 238 * Differentiate between "core API" and "extended API"?
 239
 240   Cf. the `Docutils Project Policies`_
 241
 242     When Docutils reaches version 1.0, the major APIs will be considered
 243     frozen.
 244
 245     The major number [...] may be incremented later if there is a major
 246     change in the design or API.
 247
 248
 249 * Formalise the wording for docstrings for public/private/provisional
 250   (ideally this would be a single regex pattern)?
 251
 252   * The keyword provisional_ is well defined. ✓
 253   * Use "private" or "internal"?
 254
 255 * Declare only objects included in the ``__all__`` attribute of their
 256   parent objects as public rsp. explicitely list all public objects in
 257   ``__all__`` attribute of their parents?
 258
 259   This would hide private objects from `pydoc` help on the parent objects.
 260
 261 * Define a minimum deprecation time similar to Docbook__? E.g.
 262
 263     * A "major" release may contain backward-incompatible changes if:
 264
 265       * the change was announced in the release notes for the previous
 266         version (major or minor) and
 267       * the change was announced in a release that occurred at least six
 268         months previously.
 269
 270     By these rules, Docutils developers can announce, in release 5.1, for
 271     example, its plans to make a backward-incompatible change in release 6.0.
 272     Then, in 6.0, if it’s been at least six months since 5.1 was
 273     released, they can make that change.
 274
 275   __ https://tdg.docbook.org/tdg/5.1/ch01.html#bwcompat
 276
 277
 278 References
 279 ==========
 280
 281 .. A collection of URLs used as references through the proposal.
 282
 283 .. _api/:
 284 .. _API Reference Material for Client-Developers:
 285     ../../docutils/docs/index.html
 286     #api-reference-material-for-client-developers
 287 .. _doctree:
 288 .. _Docutils document structure: ../../docutils/docs/ref/doctree.html
 289 .. _docutils.dtd: ../../docutils/docs/ref/docutils.dtd
 290 .. _Docutils Design Specification: ../../docutils/docs/peps/pep-0258.html
 291 .. _Docutils Project Policies: ../../docutils/docs/dev/policies.html
 292 .. _"console_scripts" entry points:
 293 .. _front-end tools: ../../docutils/docs/user/tools.html
 294 .. _Docutils Publisher: ../../docutils/docs/api/publisher.html
 295 .. _Docutils Transforms: ../../docutils/docs/ref/transforms.html
 296 .. _HISTORY: ../../docutils/HISTORY.html
 297 .. _RELEASE-NOTES: ../../docutils/RELEASE-NOTES.html
 298 .. _reStructuredText specification:
 299     ../../docutils/docs/ref/rst/restructuredtext.html
 300
 301 .. _`PEP 387: backwards compatibility rules`:
 302     https://peps.python.org/pep-0387/#backwards-compatibility-rules
 303 .. _`PEP 008: Public and Internal Interfaces`:
 304     https://peps.python.org/pep-0008/#public-and-internal-interfaces
 305 .. _provisional: https://docs.python.org/3/glossary.html#term-provisional-API
 306 .. _Semantic Versioning: https://semver.org/
 307
 308 Copyright
 309 =========
 310
 311 This document is placed in the public domain or under the
 312 CC0-1.0-Universal license, whichever is more permissive.
 313
 314
 315 \f
 316 ..
 317     Local Variables:
 318     mode: indented-text
 319     indent-tabs-mode: nil
 320     sentence-end-double-space: t
 321     fill-column: 70
 322     coding: utf-8
 323     End: