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

[Ivan Solovev]

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.

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,

------------------------------

Ivan Solovev
Senior Software Engineer

The Qt Company GmbH
Erich-Thilo-Str. 10
12489 Berlin, Germany
ivan.solovev at qt.io
www.qt.io

Geschäftsführer: Mika Pälsi,
Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht
Charlottenburg, HRB 144331 B