[Development] Deprecation/removal model going into Qt 6

[André Pönitz]

On Tue, Jun 04, 2019 at 06:45:26PM +0200, Mutz, Marc via Development wrote:
> = 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.

Correct. That *includes* (run time) performance. But it also includes other
aspects, like API consistency, time to market, cost of maintenance, etc. etc.

Different people certainly weigh different aspects differently, but in no
case we are in a situation where "run time performance trumps everything".

> 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().

Deprecating the class is plain overkill for that, it it positively hurts as
it makes the Qt offering (and this includes, *again*, a consistent API) less
complete.

All that's required for "telling the user" is one sentence in the docs, even
exactly the one you've just used.

> Users may continue to use the class, but they will not enjoy the same
> progress that other Qt classes or std::list will exhibit.

The continued use would be possible without the deprecation.
 
> 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_.

I am afraid you are completely wrong on this one, too:

You apparently aim at deprecating anything that's not part of your personal
usage pattern and/or that is designed to strike another balance between
run time performance, maintenance cost, API consistency etc. than the
one you personally prefer (which is, I take, "run time performance is
all that counts").

There's fundamental disagreement with your views on the reasons of deprecation
as such, and this attempt to stamp "naysayers" as irrelevant one way or the
other shows a fundamental misunderstanding of the Qt Governance Model,
which specifically mentions "Giving the community feedback" as a "Common User
contributions". So everyone you try to mark as "naysayer" here is _by
definition_ contributing.


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

... and that *before* the deprecation happens. 

Lately the deprecations left Qt in a state that was still using deprecated
API all over the place, with the people driving the deprecation generally
leaving "fixing" Qt itself and other Qt Project to others.

To put it bluntly: I consider this anti-social behaviour that is absolutely
*not* in line with the spirit of the Qt Project.

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

Fine.

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

Fine with me in principle, except that I'd suggest to only consider LTS
releases for Y.

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

*dropping* deprecated API should noy happen in minor releases, except when
there's strict consensus on the list to do that.
 
> 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.

Only when there's consensus what "bad" means. 

And please note that consensus is not established as long as there are
"naysayers" that you chose to dismiss.

Andre'