rdflib
rdflib copied to clipboard
RDFLib
docs: guidelines for public interface management
Summary of changes
These guidelines sets out some approaches for managing our public interface, it presents options for integrating code related to breaking changes into the main branch while still allowing control as to when those changes are released to users.
Happy for any suggestions, there may be better options or problems with these options that I'm overlooking.
Checklist
- [x] Checked that there aren't other open pull requests for the same change.
- [x] Checked that all tests and type checking passes.
- [x] Considered granting push permissions to the PR branch, so maintainers can fix minor issues and keep your PR up to date.
Coverage increased (+0.002%) to 90.635% when pulling a474638c05722745385e0fbf689dab8254378a3d on aucampia:iwana-20220826T2154-adr_interfaces into a563a202e797cb4b2816fe59d34bdaf383d77ea2 on RDFLib:master.
A colleague of mine (@nikitabarskov) pointed out to me today that google does do what I'm suggesting here [ref], so there is some precedent for this approach. Google has for example google.cloud.bigquery and google.cloud.bigquery_v2 - the one difference is that they use bigquery_v2 instead of bigquery.v2, which is what my guideline amounts to.
I would have gone for rdflib_v7 though, but for the issues it causes with sphinx, as sphinx does not like having multiple top level modules the way we use it. I will have another look at sphinx to see if I can't maybe make it work like that, another option is to use rdflib.rdflib_v7, but I'm not sure that is better than rdflib.v7.
More precedent/prior art that I found which:
https://github.com/cloudevents/sdk-python/blob/6648eb52aac2c3ec643b9df62a53d5f57b3ef033/cloudevents/sdk/event/v1.py
This is arguably even more similar to what I'm proposing here.
Just to re-emphasize why this matters:
Every time we break our interface we push a significant cost onto our users, the more it costs them to use RDFLib, the less they like it. There are many ways in which we can batch breaking changes and release it in a coordinated fashion without releasing a new major version every release, and we really should be doing that. Rushing interface changes out to users makes our lives harder and is not that helpful to them either.
I'm going to clean this up a bit this week, the essence of it will stay the same but I will improve the writing and clarity slightly.
If there is no further feedback, I will merge it next weekend.
As discussed in https://github.com/RDFLib/rdflib/discussions/2395 I think this is too ambitious, I will make it a draft and likely close it soon.