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

[Nicolas Fella]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20241024/2437cf71/attachment.htm>