"Does this need to be a breaking change?"
During the years as a Software Developer, I have been part of many teams making a lot of all task force style efforts to upgrade third-party dependencies or tools. The problem I see with it, is that it is often work that add zero business value. It adds significant cost, though. As a user of third-party tools, you don't have much choice. Even if you might feel productive as a developer when implementing these changes, think of all the other stuff you could do instead to improve your product or platform.
An example from Python: uv
warning: The `tool.uv.dev-dependencies` field (used in `pyproject.toml`) is deprecated and will be removed in a future release; use `dependency-groups.dev` instead
The change itself makes a lot of sense. There's a new PEP standard for how to declare the dependencies only needed for development. Most Package & Dependency management tools out there already had their own implementation of this feature and it is probably a good thing to use the standard. From a user perspective, this only mean that we need to make changes in all our Python projects. My suggestion is: why not support both options?
Maintainability vs Business Value
From a tooling developer perspective it is understandable that you don't want to maintain several ways of solving a problem. What about the Developer Experience of all the users of the tool out there? Imagine the teams maintaining many projects with 10, 40 or even 100 different Microservices and libraries. Each one in its own git repo.
Another Python example: Pydantic
The `dict` method is deprecated; use `model_dump` instead. Deprecated in Pydantic V2.0 to be removed in V3.0.
I like Pydantic, it is a very useful tool with great features. The 2.0 release also came with significant performance improvements. But this change doesn't make sense to me. I understand that it probably fits better within the domain of Pydantic itself.
Does this have to be a breaking change? I would suggest to have the both alternatives there. Yes, it might be a tiny bit more of maintenance for you as a Pydantic core developer. More importantly: your users can focus on adding value into their products instead of this mostly zero-added-value work.
Example three: SQLAlchemy
MovedIn20Warning: The ``declarative_base()`` function is now available as sqlalchemy.orm.declarative_base(). (deprecated since: 2.0)
This is probably also correct, from an internal SQLAchemy domain perspective. From a user perspective, this only means that we need to change a lot of existing code. The cost of having the code overlapping in two namespaces is probably low for the SQLAlchemy team.
I am also a maintainer of tools, and I've also made mistakes, or design choices that turned out to be not that great later on. But I also actively have made the decision to not force users to make the kind of changes that are described in this post. I don't want to break things for users of the tool because of design choices made in the past.
Should the users change their workflows?
The main thing I work on today is Python tooling for Polylith, that is a Monorepo architecture. The changes introduced by uv, Pydantic and SQLAlchemy isn't actually that much work for the developer teams using Polylith today. You'll have only one place in the source code where these changes are needed. This setup is robust, and is ready for breaking changes in the tools that are used. Sounds nice, doesn't it?
Top Photo by generated by Dall-E, prompted and modified afterwards by me.