From 6486a8bf0f765861e8da154096e56fbc885fd4d8 Mon Sep 17 00:00:00 2001 From: Iwan Aucamp Date: Mon, 22 May 2023 20:13:49 +0000 Subject: [PATCH 1/5] 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: - https://github.com/RDFLib/rdflib/discussions/2395 - https://github.com/RDFLib/rdflib/pull/2108 - https://github.com/RDFLib/rdflib/discussions/1841 --- docs/developers.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++- docs/index.rst | 10 ++++++++++ 2 files changed, 55 insertions(+), 1 deletion(-) diff --git a/docs/developers.rst b/docs/developers.rst index 43e88385b..08859ce90 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,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 `_ 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. + +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 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 -------------- From b5517b97a69712fef736e43c256c09198ba4982d Mon Sep 17 00:00:00 2001 From: Iwan Aucamp Date: Mon, 22 May 2023 20:55:33 +0000 Subject: [PATCH 2/5] reword the rationale for breaking changes guidelines --- docs/developers.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/developers.rst b/docs/developers.rst index 08859ce90..f580c91a5 100644 --- a/docs/developers.rst +++ b/docs/developers.rst @@ -95,11 +95,11 @@ 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. +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 to do. -There are more or less two ways to address the shortcomings of RDFLib's public -API: +There are more or less two ways to approach breaking 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. From a919aa6e88bd45d1acf8d33b2f2df5fae6a41139 Mon Sep 17 00:00:00 2001 From: Iwan Aucamp Date: Mon, 22 May 2023 20:56:28 +0000 Subject: [PATCH 3/5] simplify sentence --- docs/developers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers.rst b/docs/developers.rst index f580c91a5..d5e5d98f9 100644 --- a/docs/developers.rst +++ b/docs/developers.rst @@ -97,7 +97,7 @@ 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 to do. +breaking changes. There are more or less two ways to approach breaking RDFLib's public API: From 0cd1b7476bf09654785d14cae2d97bff4605986e Mon Sep 17 00:00:00 2001 From: Iwan Aucamp Date: Mon, 22 May 2023 20:57:34 +0000 Subject: [PATCH 4/5] simplify sentence --- docs/developers.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/developers.rst b/docs/developers.rst index d5e5d98f9..14febd1fb 100644 --- a/docs/developers.rst +++ b/docs/developers.rst @@ -99,7 +99,8 @@ 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 approach breaking RDFLib's public API: +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. From f706279a88fef705c8d3e3becd9f1fa3fd5d64e1 Mon Sep 17 00:00:00 2001 From: Iwan Aucamp Date: Mon, 22 May 2023 20:57:34 +0000 Subject: [PATCH 5/5] Add guidelines for deprecation --- docs/conf.py | 1 + docs/developers.rst | 42 +++++++++++++++++++++++++++++++++++++++--- 2 files changed, 40 insertions(+), 3 deletions(-) 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 14febd1fb..759e017ea 100644 --- a/docs/developers.rst +++ b/docs/developers.rst @@ -71,8 +71,15 @@ 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 -------------------------------- +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. @@ -92,8 +99,11 @@ 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 @@ -116,6 +126,32 @@ 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