Hi,
Eddy and Ivan did a great job in documenting how to formally deprecate API in
at https://wiki.qt.io/Deprecation . It's not only giving you the right macros
to use ... it also contains some suggestions for which version to do it.
About the Qt version to deprecate an API for, the page says:
When deprecating an old API in favor of a new one, it is a kindness to
client code
maintainers to set the version at which the deprecation takes effect to a
future version,
such as three minor versions after the new API was added, to give ample
time to adapt
to it. All the same, you must prepare all of Qt's code for the transition
promptly, as if
the deprecation took effect as soon as its commit integrated.
I see why this 'conservative' approach is beneficial. Projects like Qt Creator
tend to support multiple Qt versions, and immediately deprecating an old API in
the same version the replacement API got added makes this hard to handle.\
Anyhow, it creates a challenge for documentation. Take e.g.
https://doc-snapshots.qt.io/qt6-6.6/qtfuture-obsolete.html
The methods are formally marked as deprecated for Qt 6.10. But the methods are
already in the '-obsolete' page for Qt 6.6, which leaves the API in a weird
in-between state.
I see two fixes for this;
- Keep the documentation API fix separate from the header file fix, and only
merge it when Qt 6.9 got branched. This requires 'someone' to follow up on
these things, though, more than a year after the deprecation decision has been
made.
- Deprecate the API already _in the documentation_ for 6.6, but only follow up
with the compiler warning in Qt 6.10.
I'm actually in favor of the second approach; documentation is mostly read when
writing _new_ code, and that should already be written with the new API. But
it's not something we've done so far, IMO.
Do you agree?
Kai
--
Kai Köhne, Director R&D | The Qt Company
The Qt Company GmbH, Erich-Thilo-Str. 10, D-12489 Berlin
Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, HRB
144331 B
--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development
