HEADS-UP: from now do new deprecations in KF API by *_DEPRECATED_* macros only using upcoming version number

Friedrich W. H. Kossebau kossebau at kde.org
Sun Nov 3 21:48:37 GMT 2019


Hi,

with KF 5.64 now branched and thus the new deprecation macros going to be 
released for the first time, now please make sure when in the future marking 
API as deprecated to use the correct current version, i.e. the one where the 
deprecation will be made public the first time.

So if pushing a commit which deprecates API, make sure the "x" is matching the 
upcoming version of KF where the deprecation will be released the first time:

#if KFOO_ENABLE_DEPRECATED_SINCE(5, x)
/**
 * @deprecated Since 5.x. Use bar(). // Sadly doxygen needs data duplicated
 */
KFOO_DEPRECATED_VERSION(5, x, "Use bar()")
void foo();
#endif

((In a perfect world this boilerplate/duplication would not be needed and 
tools would automate this for us, but for now we have to do it manually.))

Do _not_ use an older KF version where the API might already have been 
considered deprecated, but was forgotten to be marked. Use the upcoming KF 
release version only.


In the last weeks, since 5.63 was branched, while the new deprecation macros 
generated with ECMGenerateExportHeader were introduced you may have seen also 
lots of older versions being used. But that was fine due to the macros not yet 
been released and changes done to be historically correct, like also matching 
any already existing version info in the API dox by the @deprecated tag. 
Hopefully we have catched any existing KF API which has been considered 
deprecated before.

But now with KF 5.64 being branched and going to be officially released 
exposing the new deprecation macros and thus the options to control visibility 
of and warnings about deprecated KF API, people using KF libraries in their 
software will e.g. start to use the *_DISABLE_DEPRECATED_BEFORE_AND_AT macros, 
to protect themselves against usage of API deprecated the first time up to a 
certain version, for which they have checked their code builds fine against.
And we would thus ran chance to break their software builds if we now marked 
more API as being deprecated in previous versions in future KF releases. Not 
our mission :)

Cheers
Friedrich




More information about the Kde-frameworks-devel mailing list