From cad367e6cb47c3f2ea0f0951649e82ae8dd82eea Mon Sep 17 00:00:00 2001 From: Iwan Aucamp Date: Fri, 2 Jun 2023 20:54:13 +0200 Subject: [PATCH] docs: add guidelines for breaking changes (#2402) 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: - https://github.com/RDFLib/rdflib/discussions/2395 - https://github.com/RDFLib/rdflib/pull/2108 - https://github.com/RDFLib/rdflib/discussions/1841 --- docs/conf.py | 1 + docs/developers.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++- docs/index.rst | 10 ++++++ 3 files changed, 93 insertions(+), 1 deletion(-) 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 --------------