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".
Clearly defining how we will balance evolution with stability is
important to both users and project developers.
People affected by changes in Docutils include:
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).
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, [1]
output templates and style sheets provided with the writers,
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. [2]
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.
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) [3].
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.
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.