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. 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 [email protected] https://lists.qt-project.org/listinfo/development
