[Development] Deprecation/removal model going into Qt 6

[Lisandro Damián Nicanor Pérez Meyer]

Hi!

On Tue, 4 Jun 2019 at 13:46, Mutz, Marc via Development
<development at qt-project.org> wrote:
>
> 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_.

Agreed.

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

Sounds good.

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

The part of doing BiC in major versions is (also?) due to SONAME as
it's (currently) only limited to major versions:

$ objdump -x /usr/lib/x86_64-linux-gnu/libQt5Core.so.5.11.3 | grep SONAME
 SONAME               libQt5Core.so.5

SONAME *must* be changed with each release that breaks binary
incompatibility. Possible solution? Maybe using SONAMEs like major.lts
could work. In this way with each new LTS SONAME could be 6.1, 6.2,
etc.

But there is also a *huge* amount of libraries/applications that won't
get ported in due time. If we get to this we get back to what boost
and other does, and clearly has showed it's not the way to go.
Possible solution? *Maybe* if moving API to it's own left-to-die
library and having a *real easy* way to integrate it in existant
projects.

And even then, with all the experience of maintaining Qt from the last
Qt4 days until now, I still think this is a solution only to be done
with major releases. Whatever faster is a call for problems.

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

I personally only disagree with your proposed cadence of the BiC
changes, but yes, at some point BiC changes should happen.

-- 
Lisandro Damián Nicanor Pérez Meyer
http://perezmeyer.com.ar/
http://perezmeyer.blogspot.com/