[Development] On deprecating functions

[André Pönitz]

On Mon, Mar 04, 2019 at 05:51:08PM +0100, Christian Ehrlicher wrote:
> Hi,
> 
> I recently introduced some new signals
> (Q(Double)SpinBox::textChanged, QComboBox::textActivated) as
> replacements for old ones to be able to avoid the use of
> QOverload<>::of in Qt6 and to better match their respective
> properties.

> Within those changes I also marked the old signals as deprecated
> with QT_DEPRECATED so the developer gets an information to no
> longer use this function in new code.

> This lead to a lot of warnings in old code which needs to be
> compiled with 5.9 and 5.12 (e.g. in QtCreator) which can't be
> fixed because there the new function is not yet available. It was
> requested to remove the QT_DEPRECATED decoration until e.g. 5.15.
> but I think then it's too later to be able to remove them with
> Qt6.

Yonder Old Code is kind of actively maintained, and to play its
role as guinea pig for Qt itself it makes sense to compile it with
Qt dev at times. I completely agree that the overloaded signals are
mildly annoying, and getting rid of them in the medium term is a
worthy goal by itself. So I certainly appreciate the introduction
of the non-overloaded text* versions, but what is going on top of
that currently is what I'd call tr("Throw out the baby with the
bath water").

The issue at hand is purely cosmetical. Either use of static_cast
or QOverload or qOverload is at most one extra line in user code
that will only ever be witnessed by someone looking directly at
those parts of the code. It's unfortunately a safe assumption that
in this particular case this might be one or less persons worldwide.

All possible workarounds that I am aware of (some of them even
being actively suggested as possible solution) are worse than that:

(1) Do not do anything: Anyone compiling the code will get the
warning. That's at least a dozen dayly, i.e. more than a magnitude
worse. Duh.  (1a) Some people compile with -Werror. While I will
happily argue that they deserve the outcome for unrelated reasons,
this still makes it: Duh!

(2) Replace the (QString) overloads with the (int) overloads and do
the data extraction manually. Given that Qt is about making coding
convenient and this is less convenient than before: Duh.

(3) Only suppport Qt dev of the day. Hard sell to users and 
distributors, a.k.a. "Duh!"

(4) Only support a reasonably safe, a.k.a "antique", version of Qt.
Hard sell for various reasons, one of them is failing to play the
guinea pig role. DUH.

(5) Use #if (QT_VERSION / QT_VERSION_CHECK. To "fix" perfectly
valid code *for cosmetical reasons*? DUH!

Having *some* grace period for peaceful co-existence makes sense to
me. We can have a round of bikeshedding on what that period should
look like, but the very existence of LTS releases suggests that it
is ok for people to stick to LTS only. Qt Creator actually uses
"last LTS minus one minor release" so far, so asking for "last LTS"
is already a kind of concession. Truly personally, I'd even go for
"no deprecation at all *for purely cosmetical reasons*" as I've seen
too many taking route (5) because it was perceived too much effort
to keep up with "random" changes in Qt, but that's a different story. 

> See https://codereview.qt-project.org/252208 for the discussion
> and a possible solution here:
> https://codereview.qt-project.org/#/c/254909/
> 
> So what's the correct way to deprecate a function and not
> forgetting about QT_DEPRECATED later on as it happened with a lot
> of functions during Qt4 times?

Currently there's apparently no agreed policy beyond the usual
"submit a patch and find someone to +2 it".

The one I suggested in https://codereview.qt-project.org/#/c/254909/
makes sure that it is noticed at some time, and at that time there
was some period in between where people had a reasonable chance to
update their code base without facing immediate regressions. I
still don't think that is asked too much for a solution to a truly
cosmetical issue.

Andre'