Move backwards compatibility policy to dev.rst.

For lemon24#60.

CHANGES.rst

@@ -669,7 +669,7 @@ Released 2021-08-18
   `details <https://github.com/lemon24/reader/issues/163#issuecomment-895041943>`_).
 
   Note these globals are private, and thus *not* covered by the
-  :doc:`backwards compatibility policy <compat>`.
+  :ref:`backwards compatibility policy <compat>`.
 
 
 Version 2.0

CONTRIBUTING.rst

@@ -264,4 +264,4 @@ If you have `entr <http://eradman.com/entrproject/>`_ installed,
 will run the corresponding commands when the files in the repo change.
 
 Likewise, ``serve-dev`` will run the web app with the Flask
-`development server <https://flask.palletsprojects.com/en/2.3.x/server/>`_.
+`development server <https://flask.palletsprojects.com/en/latest/server/>`_.

docs/dev.rst

@@ -30,8 +30,63 @@ In no particular order:
 Also see open issues: https://github.com/lemon24/reader/issues
 
 
+.. _compat:
+
+Backwards compatibility
+-----------------------
+
+*reader* uses `semantic versioning`_.
+
+Breaking compatibility is done by incrementing the major version,
+announcing it in the :doc:`changelog`,
+and raising deprecation warnings for at least one minor version
+before the new major version is released (if possible).
+
+There may be minor exceptions to this,
+e.g. bug fixes and gross violation of specifications;
+they will be announced in the :doc:`changelog`
+with a **This is a minor compatibility break** warning.
+
+Schema migrations for the default storage must happen automatically.
+Migrations can be removed in new major versions,
+with at least 3 months provided since the last migration.
+
+.. _semantic versioning: https://semver.org/
+
+
+What is the public API
+~~~~~~~~~~~~~~~~~~~~~~
+
+*reader* follows the `PEP 8 definition`_ of public interface.
+
+The following are part of the public API:
+
+* Every interface documented in the :doc:`API reference <api>`.
+* Any (documented) module, function, object, method, and attribute,
+  defined in the *reader* package,
+  that is accessible without passing through a name
+  that starts with underscore.
+* The number and position of positional arguments.
+* The names of keyword arguments.
+* Argument types (argument types cannot become more strict).
+* Attribute types (attribute types cannot become less strict).
+
+Undocumented type aliases (even if not private)
+are **not** part of the public API.
+
+Other exceptions are possible; they will be marked aggresively as such.
+
+.. _PEP 8 definition: https://www.python.org/dev/peps/pep-0008/#public-and-internal-interfaces
+
+
+.. seealso::
+
+  The `Twisted Compatibility Policy <https://github.com/twisted/twisted/blob/twisted-16.2.0/docs/core/development/policy/compatibility-policy.rst>`_,
+  which served as inspiration for this.
+
+
 Supported Python versions
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The oldest Python version reader should support is:
 
@@ -40,16 +95,28 @@ The oldest Python version reader should support is:
 
 This usually ends up being the last 3 stable CPython versions.
 
+Dropping support for a Python version should be announced
+at least 1 release prior.
 
-Making a release
-----------------
 
-Making a release (from ``x`` to ``y`` == ``x + 1``):
+
+Releases
+--------
+
+For convenience, *reader* only releases major and minor versions
+(bugfixes go in minor versions).
+Changes go only to the next release (no backports).
+
+
+Making a release
+~~~~~~~~~~~~~~~~
 
 .. note::
 
     :gh:`scripts/release.py <scripts/release.py>` already does most of these.
 
+Making a release (from ``x`` to ``y`` == ``x + 1``):
+
 * (release.py) bump version in ``src/reader/__init__.py`` to ``y``
 * (release.py) update changelog with release version and date
 * (release.py) make sure tests pass / docs build

docs/index.rst

@@ -87,7 +87,6 @@ It is rigorously tested on Python |min_python|\+ and PyPy.
     :maxdepth: 2
 
     contributing
-    compat
     dev
     changelog