docs: add guidelines for breaking changes

Add guidelines on how breaking changes should be approached.

The guidelines take a very pragmatic approach with known downsides, but this
seems like the best compromise given the current situation.

For prior discussion on this point see:
- RDFLib#2395
- RDFLib#2108
- RDFLib#1841

Author: aucampia

docs/developers.rst

@@ -16,7 +16,7 @@ developing RDFLib code.
 * You must supply tests for new code.
 * RDFLib uses `Poetry <https://python-poetry.org/docs/master/>`_ 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,50 @@ 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.
 
+Guidelines for 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 <https://semver.org/spec/v2.0.0.html>`_ and `trunk-based development
+<https://trunkbaseddevelopment.com/>`_, 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.
+
+Rationale
+~~~~~~~~~
+RDFLib has been around for more than a decade, and in this time both Python and
+RDF have evolved. RDFLib's public API has also accumulated some problems over
+time.
+
+There are more or less two ways to address the shortcomings of 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.
+
 .. _tests:
 
 Tests

docs/index.rst

@@ -90,6 +90,16 @@ API reference:
 .. * :ref:`genindex`
 .. * :ref:`modindex`
 
+Versioning
+----------
+RDFLib follows `Semantic Versioning 2.0.0 <https://semver.org/spec/v2.0.0.html>`_, 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
 --------------