[Development] Deprecated vs deprecated-to-be-removed APIs in Qt

[Edward Welbourne]

Ivan Solovev (24 October 2024 16:32) wrote:
> 3. New names
>
> While looking through the sources, I noticed that many of the APIs
> simply got renamed. We have a lot of such cases for Qt 6.0, for
> example in QFuture-related APIs.
>
> Another typical example here is the renaming of the error() signal to
> errorOccurred(), which happened in many classes, because the old name
> was clashing with the getter. In some classes it was done before the
> module was released in Qt 6, so the old signal is already removed,
> while for the others it was changed later, so the old signal is
> deprecated.
>
> This is, probably, the most questionable category of deprecations.
> On one hand, if the function is renamed, then there was a purpose for that.
> Even if it was only for a better readability.
> On the other hand, if we drop all such deprecated function in Qt 7,
> the users will need to do massive updates in their code without any
> added value.

When a renaming is motivated only by improved readability or better fit
with other names in the system, it's a "this is a better way to do it,
so we've deprecated the old one" situation, where there is no compelling
reason to force people to rewrite their code, so don't schedule it for
deletion.

When a renaming is motivated by a functional need - such as to free up
the name for some other use - or by an issue where the old name was apt
to mislead developers calling the API, or reading code that calls it,
into thinking that the relevant API does something quite different to
what it actually does, then there is a case for deleting the old name.
In the former case it's to make way for something else to claim that
name.  In the latter case, it's to force those maintaining code that
exercises it to be aware that the name didn't mean what they might have
mistaken it for, and to make their code less likely to confuse folk
reading it, which may save them from bugs later.  That's a weaker
argument than "because the API is broken, no matter what you call it"
but may still warrant removal.

> I guess that needs to be evaluated on a case-by-case basis.

Yes - each deprecation should be considered in its own right.
When deprecating with intent to remove, reviewers need to see a clear
case for why removal is necessary, not merely nice-to-have.
What harm would be caused by retaining the old API ?

> For example, I'd say that all deprecated error() signals should be
> dropped in Qt 7. Also, the functions that got deprecated in early Qt 6
> versions (Qt 6.0 - 6.2) might be good candidates for removal.

As a general matter, I do no think *when* something got deprecated
should determine when or if ever it should be removed.  Rather, *why* it
is deprecated should be the basis for such decisions.

My understanding of the QtCS session's conclusion was that we can accept
a reality in which old classes contain dark corners (surrounded in
#if-ery and warning comments) cluttered with ancient artefacts of older
versions of the class.  As long as they're harmless and folk may be
calling them, we can just let them lurk in their dark corner.  Whenever
possible they should be inline.  They need not be documented, as long as
their deprecation markers or inline bodies include the information the
reader needs to discover what documented API to replace each with.  The
#if-ery around them can ensure that it's possible to make a lean build
that omits them all, for those to whom these relics are bloat.

	Eddy.