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

[Alex Blasche]

Hi,

Let's move forward with the given patch. Patch discussion seems to have mostly settled with only marginal (if any) improvement discussions.

Once this has merged I propose we simply start going systematically through the code base per directory or module (depending on reasonable number of cases for each block) and make a proposal for macro conversion. Then the review process can settle on individual merits for each case.

--
Alex


________________________________________
From: Development <development-bounces at qt-project.org> on behalf of Nicolas Fella via Development <development at qt-project.org>
Sent: Thursday, 24 October 2024 19:36
To: development at qt-project.org
Subject: Re: [Development] Deprecated vs deprecated-to-be-removed APIs in Qt

Am 24.10.24 um 16:32 schrieb Ivan Solovev via Development:

Hi,

following up on the Deprecation vs Compatibility discussion from
the Qt Contributor Summit [0], I implemented a macro that allows to mark
the APIs as deprecated and to-be-removed in the Next Major Release [1].

[0]: https://wiki.qt.io/QtCS2024_Deprecate
[1]: https://codereview.qt-project.org/c/qt/qtbase/+/599356

The patch is still in review, so the actual macro name might change.

However, the most important point on my email is to come up with a consistent
policy of using the macro. In other words, we need to decide, which of the
deprecated APIs should be gone in Qt 7, and which should stay.

Please share your ideas and opinions. And also feel free to comment directly
on the related epic in Jira: https://bugreports.qt.io/browse/QTBUG-130004

As for me, I see three major categories of deprecations:

1. Deprecations of incorrect or unsafe APIs

Such APIs were deprecated because using them can lead to errors.
One example of such incorrect APIs can be QScopedPointer::take(), because it
allows the pointer to escape from the scope (see [2]).
Another example is the QAbstractOAuth2::scope() getter (and the respective
setter) [3], because the same property was incorrectly used for two use-cases.

[2]: https://codereview.qt-project.org/c/qt/qtbase/+/319899
[3]: https://codereview.qt-project.org/c/qt/qtnetworkauth/+/579982

I think that it makes sense to drop all such APIs in the next major release.

2. API improvements

Some APIs got deprecated because there are new versions that follow more modern
API design principles.

For example, we have a deprecated

  quint16 qChecksum(const char *s, qsizetype len, Qt::ChecksumType standard)

and a new overload taking QByteArrayView instead of const char * and qsizetype.
While the new code should prefer using the QBAV overload, the old (and
hopefully well-tested) code can still keep passing the pointer + size without
and drawbacks.

So, I'd say that such deprecated methods should stay in Qt 7.

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.


Speaking from an API consumer POV it would help a lot if the reason for the deprecation is clearly stated in the documentation.

It's very useful to know whether a new API is a 100% compatible replacement just with a different name (and I can do a simple search&replace) or there's some subtle difference that I need to test for.

When porting KDE I sometimes looked into the implementation to figure this out, but I'd rather not have to do that.

I guess that needs to be evaluated on a case-by-case basis.
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.
But that's only my opinion.

Best regards,

Cheers

Nico