Repository navigation
[ENH]: Backend versioning #30559
Description
Problem
Beyond our builtin backends there are a few third party ones. It is extremely difficult to evolve the backend API without hard-breaking these third party backends.
Issues with the current state:
- We've jumed hoops to work around API incompatibility in Add hatchcolor parameter for Collections #29044
- [MNT]: Revamp draw_path_collection() API #30547 suggests a one-time API break to make changes like Add hatchcolor parameter for Collections #29044 more tractable in the future
- Implement single axis zoom #30554 also introduces new functionality in the backend that should be propagated to all backends
Proposed solution
We define a backend version. It unambiguously describes the expected functionality of an interface.
- The current is version 1.0
- API changes result in a new backend version.
- Backends must define the version they are written for. All backends that do not explicitly specify a version are considered to be version 1.0.
- A Matplotlib version can decide to accept multiple backend versions, e.g. we could at some point accept v1.0, v2.0 and v3.0 and selectively call appropriate functions.
- We may later decide to drop support for v1.0 in which case we'd reject to load backends of that version.
This should allow to evolve the backend API and third partry backends alongside with grace transition periods so that we maintain maximal compatibility throughout the evolution.
Activity
anntzer commented on Sep 16, 2025
I think the problem is somewhat worse, because a lot of changes can end up affecting third-party backends even if they are not directly backend-related. To give two concrete examples, #28842 broke mplcairo because it removed implicit ft2font enum->int conversion (by switching to real enums), and #30335 will again break mplcairo (see #30335 (review), note that that conversation is marked as "resolved"). Of course, one approach would be to bump the version number for each of these changes, but e.g. I didn't notice that #28842 would be problematic until after it was merged.
I wonder whether we should just recommend to backend authors to pin the upper-supported matplotlib version and go through fewer contortions when doing these API changes (while remaining reasonable and avoiding them as much as possible).
timhoffm commented on Sep 16, 2025
I don't believe in upper-bound pinning. You cannot pin higher than the current relased version because the next release may be incompatible. This means that backends have to release synced on every Matplotlib release (essentially between the release candidate and the release) to prevent interrupted support for the newest matplotlib version. While interrupted support might be ok for some backends, it would be a serious usability issue for others; e.g. consider the PyCharm backend - it would be awful both for PyCharm and for matplotlib if PyCharm would claim you cannot use the latest version of matplotlib.
Overall, backends should be free to adopt such a policy if they can reasonably mange it, but we shouldn't make it a general recommendation.
On changes affecting third-party backends that are not directly backend-related: I think we cannot fully avoid these. The pragmatic approach is to raise awareness on the topic with core devs (could this break third party backends) and otherwise live with the consequences as we have to with any unintended/overlooked API breakage.
IMHO this all does not diminish the value of a defined evolution of the backend API. - Just because it's not perfect does not mean it's not an improvement.
Semi-OT: Do we have a full overview of existing backends? If not should we encourage backend developers to announce their backends with us so that we have a clearer picture and possibly up-front communication and maybe even discussion possibilities?
anntzer commented on Sep 16, 2025
I think this would be nice to have. Something like "we encourage backend developers to make themselves known; we will ping them on possibly breaking changes to the backend API to give them time to adapt" (this doesn't mean that we wlill necessarily wait for them to fix whatever needs to be fixed on their side, but at least they get a heads up and can participate in the discussion).
timhoffm commented on Sep 16, 2025
How could we do this? We need:
I'm inclined to use a Github issue for both. What do you think?
anntzer commented on Sep 16, 2025
I think third-party backends can indeed register themselves under third-party packages, and a long-running tracking issue to which people can subscribe seems the easiest as well.
timhoffm commented on Sep 29, 2025
Coming back to the original topic on backend versioning. Now would be a good time to introduce it.
For as start it is sufficient to just define these and explain how backends declare their version. We do not yet have to query the values in code yet as we have compatibility workarounds. But this would let backends that use the new path collection parameters give a chance to declare they are v2.
Worst case with introducing now would be that we decide the versioning is not needed and we withdraw the concept again.
DOC: Introduce backend versions
DOC: Introduce backend versions
DOC: Introduce backend versions
DOC: Introduce backend versions
DOC: Introduce backend versions
DOC: Introduce backend versions