[Development] Deprecation/removal model going into Qt 6
marc at kdab.com
Tue Jun 4 18:45:26 CEST 2019
This is not meant to be a summary of the thread so far, but the
definition of a possible solution space:
= The meaning of deprecation
I think of deprecation as a means to tell users that the designers of
the deprecated API think that there is some deep flaw in the API that
makes it harder to use correctly or easier to use incorrectly. Or
lacking in any other desirable software quality realm, and yes that
One important aspect of deprecation, IMO, is that the deprecated API
will be less likely to be properly maintained. So, e.g. by deprecating
QLinkedList, we tell the users that we do _not_ intend to make it
feature-compatible with std::list, e.g. by adding splice(). Users may
continue to use the class, but they will not enjoy the same progress
that other Qt classes or std::list will exhibit.
I don't think, that, apart from the usual nay-sayers who don't want
anything to change, but also don't contribute, there's much disagreement
over how and what to _deprecate_.
= The deprecation life-cycle:
The question really is: if an API is deprecated, then what? We have, so
far, removed deprecated APIs from the library, or moved it to a
QtXSupport library, which later got removed, too. I think the most Angst
comes from the removal part here.
Let me try to define the deprecated API lifecycle as follows (dare I
call it 4D? :)
1. Deprecate the API in Qt vX.Y, add the new API (if any, some APIs many
simply move down a storey into C++, like Q_FOREACH vs. ranged for-loops;
sometimes, Qt will realise that it's not able to support some API any
longer, like XMLPatterns, or, I'd say, Q*SharedDataPointer)
2. Delete all uses of the deprecated API from Qt itself
3. Disentangle the deprecated API from Qt. With this I mean that we take
the steps necessary, at a point in time when we can, to make a Qt built
sans deprecated APIs as BiC as possible with one that isn't stripped of
deprecated APIs. The usual way to do this is to move the implementation
inline into the header file and make it wrap the new API. The point in
time traditionally was v(X+1).0, but see below.
4. Decommission the deprecated API. With this I mean either remove it,
or spin it off into a library which is no longer maintained by the Qt
Project. The hope being, that someone (TQC, KDAB, Kevin Kofler) picks up
maintenance of said library. This can be done at the same time as (3),
= Deprecation and BiC
All the above, except, possibly, the decommissioning stage, are SC.
Disentanglement is, however, BiC. We have traditionally used new major
versions as a flag day to do disentanglement, and it seems to some, and
this is why Peppe started this thread, that the plan is for it to also
be the flag day for decommissioning.
I think we could make the experience for our users a lot less painful if
we allowed ourselves the liberty to break BC by disentangling deprecated
API within major release cycles. I don't think anyone actually needs BC
from 5.0 to 5.13, and for all intents and purposes, 5.13 is not BC with
5.0, because, as attested in this thread, there are behaviour changes
which make it unlikely that an application compiled against 5.0 runs
without modifications against 5.13.
It seems to me to be a good compromise to disentangle deprecated API
right after an LTS. Whether to keep BC-for-DPF (binary compatibility for
deprecation-free programs, with apologies to Hans Boehm) across two or
three LTS releases is another question. I'm tending towards three. But
this would be BiC in the current process.
We should come to a conclusion about the meaning of deprecation, the
life-cycle of deprecated APIs (e.g. how maintained are they, from
deprecation to decommissioning?), the time-spans between the four D's,
and, as a corollary, the weakening of our BC guarantees to exclude
Personally, I have no problem with disentangling the API sooner, like
Personally, I also have no problem with decommissioning the API later
(like not drop stuff first deprecated in vX.Y before v(X+2).0), but this
does not seem to be the plan atm.
But once an API has been identified as ... for want of a better word:
bad, and a better alternative added, we should never hesitate to
deprecate the old one.
More information about the Development