diff --git a/docs/conf.py b/docs/conf.py
index 1e2b7ef46..9836b9748 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -266,6 +266,7 @@ def find_version(filename):
# This is here to prevent:
# "WARNING: more than one target found for cross-reference"
"ref.python",
+ "autosectionlabel.*",
]
sphinx_version = tuple(int(part) for part in sphinx.__version__.split("."))
diff --git a/docs/developers.rst b/docs/developers.rst
index 43e88385b..759e017ea 100644
--- a/docs/developers.rst
+++ b/docs/developers.rst
@@ -16,7 +16,7 @@ developing RDFLib code.
* You must supply tests for new code.
* RDFLib uses `Poetry `_ for dependency management and packaging.
-If you add a new cool feature, consider also adding an example in ``./examples``
+If you add a new cool feature, consider also adding an example in ``./examples``.
Pull Requests Guidelines
------------------------
@@ -71,6 +71,87 @@ the users of this project.
Please note that while we would like all PRs to follow the guidelines given
here, we will not reject a PR just because it does not.
+Maintenance Guidelines
+----------------------
+
+This section contains guidelines for maintaining RDFLib. RDFLib maintainers
+should try to follow these. These guidelines also serve as an indication to
+RDFLib users what they can expect.
+
+Breaking changes
+~~~~~~~~~~~~~~~~
+
+Breaking changes to RDFLib's public API should be made incrementally, with small
+pull requests to the main branch that change as few things as possible.
+
+Breaking changes should be discussed first in an issue before work is started,
+as it is possible that the change is not necessary or that there is a better way
+to achieve the same goal, in which case the work on the PR would have been
+wasted. This will however not be strictly enforced, and no PR will be rejected
+solely on the basis that it was not discussed upfront.
+
+RDFLib follows `semantic versioning `_ and `trunk-based development
+`_, so if any breaking changes were
+introduced into the main branch since the last release, then the next release
+will be a major release with an incremented major version.
+
+Releases of RDFLib will not as a rule be conditioned on specific features, so
+there may be new major releases that contain very few breaking changes, and
+there could be no minor or patch releases between two major releases.
+
+.. _breaking_changes_rationale:
+
+Rationale
+^^^^^^^^^
+
+RDFLib has been around for more than a decade, and in this time both Python and
+RDF have evolved, and RDFLib's API also has to evolve to keep up with these
+changes and to make it easier for users to use. This will inevitably require
+breaking changes.
+
+There are more or less two ways to introduce breaking changes to RDFLib's public
+API:
+
+- Revolutionary: Create a new API from scratch and reimplement it, and when
+ ready, release a new version of RDFLib with the new API.
+- Evolutionary: Incrementally improve the existing API with small changes and
+ release any breaking changes that were made at regular intervals.
+
+While the revolutionary approach seems appealing, it is also risky and
+time-consuming.
+
+The evolutionary approach puts a lot of strain on the users of RDFLib as they
+have to adapt to breaking changes more often, but the shortcomings of the RDFLib
+public API also put a lot of strain on the users of RDFLib. On the other hand, a
+major advantage of the evolutionary approach is that it is simple and achievable
+from a maintenance and contributor perspective.
+
+Deprecating functionality
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To whatever extent possible, classes, functions, variables, or parameters that
+will be removed should be marked for deprecation in documentation, and if
+possible, should be changed to raise deprecation warnings if used.
+
+There is however no hard requirement that something may only be removed after a
+deprecation notice has been added, or only after a release was made with a
+deprecation notice.
+
+Consequently, functionality may be removed without it ever being marked as
+deprecated.
+
+.. _deprecation_rationale:
+
+Rationale
+^^^^^^^^^
+
+Current resource limitations and the backlog of issues make it impractical to
+first release or incorporate deprecation notices before making quality of life
+changes.
+
+RDFLib uses semantic versioning and provides type hints, and these are the
+primary mechanisms for signalling breaking changes to our users.
+
.. _tests:
Tests
diff --git a/docs/index.rst b/docs/index.rst
index e36962ea0..e3e2ca003 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -90,6 +90,16 @@ API reference:
.. * :ref:`genindex`
.. * :ref:`modindex`
+Versioning
+----------
+RDFLib follows `Semantic Versioning 2.0.0 `_, which can be summarized as follows:
+
+ Given a version number ``MAJOR.MINOR.PATCH``, increment the:
+
+ #. ``MAJOR`` version when you make incompatible API changes
+ #. ``MINOR`` version when you add functionality in a backwards-compatible
+ manner
+ #. ``PATCH`` version when you make backwards-compatible bug fixes
For developers
--------------