[Development] How to do deprecation

Lars Knoll lars.knoll at qt.io
Thu Jul 21 09:31:12 CEST 2022


Hi Eddy,

On 20 Jul 2022, at 16:50, Edward Welbourne <edward.welbourne at qt.io<mailto:edward.welbourne at qt.io>> wrote:

Hi all,

TL;DR: there's a new [[Deprecation]] wiki page, please review.

We noticed recently that some APIs had been wrapped in #if-ery on
QT_DEPRECATED_SINCE(major, minor) without having QT_DEPRECATED or one of
the QT_DEPRECATED_VERSION* macros prepended to the actual declarations
within that #if-ery.  This meant that when you build with
QT_DISABLE_DEPRECATED_BEFORE set to a recent enough version, the
declarations vanished but code that was still using it never got a
deprecation warning from the compiler, no matter how
QT_DEPRECATED_WARNINGS_SINCE was set.  So no-one had been warned to fix
their uses of deprecated API and the code that did so duly broke the
build.  Hopefully we can all agree that this is bad.

Agreed. I think part of the problem is that you currently need to do several things to properly deprecate a method.

* You need to wrap the method in QT_DEPRECATED since #ifdefs
* You need to add a QT_DEPRECATED_VERSION_X_maj_min macro before the declaration
* You need to document the method as deprecated using the \deprecated tag

It’s way too easy to make mistakes here. One solution could be to reduce this down to one way of deprecating:

QT_DEPRECATED_METHOD(method, major, minor, reason)

So instead of


#if QT_DEPRECATED_SINCE(6, 4)

    QT_DEPRECATED_VERSION_X_6_4("Use size() or length() instead.")

    inline qsizetype count() const { return d.size; }

#endif


You’d have:

    QT_DEPRECATED_METHOD(qsizetype count(), 6, 4, "Use size() or length() instead.”)

It should be possible to make this work using some macro magic, so that it’ll expand to the right declaration (with or without warning or removed) depending on Qt version and the QT_DISABLE_DEPRECATED_BEFORE setting.

Oh, and qdoc should of course pick up those things automatically, so you don’t need to add the qdoc tag in the docs :)

Cheers,
Lars



So I went looking for where we document how to do this properly and was
mildly surprised to find no such documentation.  If anyone happens to
know where it's documented, please do let me know.  I managed to find
docs for QT_DISABLE_DEPRECATED_BEFORE, QT_VERSION_CHECK and QDoc's
\deprecated, but none for various other related macros (despite some
search results, leading to pages in which the word DEPRECATED did not
appear) and certainly nothing covering how all the pieces fit together.

So I wrote a wiki page [0] about the process, as I understand it, and
managed to get some others to look it over and point out the more
obvious deficiencies of the first draft.  I think it is now ready for a
wider review and perhaps now would be a good moment for us to discuss
whether the process described (to the best of my ability) there is in
fact fit for purpose and whether there are caveats, restrictions or
further complications that should be documented, or further advice that
should be included there for those contemplating a deprecation.

* [0] https://wiki.qt.io/Deprecation

What I have described is merely what I understand to be current best (or
at least somewhat standard) practice; obviously, if better practice can
be devised, I'd love to know what it is.

In particular, one thing caught my attention when documenting the
defaults - if you predefine QT_DISABLE_DEPRECATED_BEFORE, then it is
used as the default for QT_DEPRECATED_WARNINGS_SINCE, which leads to no
deprecation warnings being given, because all the API that would be
warned about is simply omitted.  So you get compiler errors.  These are
usually less helpful than warnings, at least when the _X_ variants of
various macros are used, with even a half-way helpful message.  So
perhaps we should change the default values here.

When QT_DISABLE_DEPRECATED_BEFORE isn't predefined, it gets defined to
something suitably ancient and QT_DEPRECATED_WARNINGS_SINCE defaults to
the current version.  Perhaps that should remain the default, even when
QT_DISABLE_DEPRECATED_BEFORE is predefined.


I have also added a related section to Fabian's new page [1], covering
its application to deprecations.  Feedback on that page would, no doubt,
be generally appreciated.  Or, of course, you could just improve it
right there in the wiki; same for [[Deprecation]].  It's a wiki.

* [1] https://wiki.qt.io/Merging_breaking_changes_of_internal_API

If anyone feels enthusiastic about making a QUIP of either or both, I'd
be happy to help,

Eddy.
_______________________________________________
Development mailing list
Development at qt-project.org<mailto:Development at qt-project.org>
https://lists.qt-project.org/listinfo/development

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20220721/45cb297d/attachment-0001.htm>


More information about the Development mailing list