[Development] Deprecation/removal model going into Qt 6

[Mutz, Marc]

Hi,

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 
includes performance.

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), 
or later.


= 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.

= Summary

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 
deprecated API.

Personally, I have no problem with disentangling the API sooner, like 
vX.(Y+3)

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.

Thanks,
Marc