docs: guidelines for public interface management

[aucampia]

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

• Checked that there aren't other open pull requests for
  the same change.
• Checked that all tests and type checking passes.
• Considered granting push permissions to the PR branch,
  so maintainers can fix minor issues and keep your PR up to date.

[coveralls]

Coverage increased (+0.002%) to 90.635% when pulling a474638 on aucampia:iwana-20220826T2154-adr_interfaces into a563a20 on RDFLib:master.

[ghost]

keen to try it out

[aucampia]

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.

[aucampia]

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.

[aucampia]

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.

[aucampia]

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.

[ghost]

👍

[aucampia]

As discussed in #2395 I think this is too ambitious, I will make it a draft and likely close it soon.