Porting notes / deprecation docs

[Friedrich W. H. Kossebau]

Am Samstag, 10. Juli 2021, 18:00:13 CEST schrieb Frederik Schwarzer:
> as mentioned earlier

Any pointers? :)

> I would like to document classes/methods/etc that
> are going to be deprecated during KF6 development.

Can you help confused-on-first-read people by explaining what "deprecated 
during KF6 development" is referring to? Deprecated during KF5 development and 
no longer be available in KF6? Not yet deprecated due to no existing 
replacement, but with replacement planned in KF6?

> For that I scraped up all the deprecation macros from the frameworks and
> edited them to be more unified.

That sounds like duplication of data, and worse, a manual copy of a certain 
state, which also needs to be manually maintained to be up-to-date to stay 
useful.

In general I am also curious what audience is targeted by the planned 
documentation and in which work-flows that documentation should solve which 
needs, and what other solutions are there which would not satisfy those needs 
well enough?

In general, for API already deprecated now during lifetime of KF5 we are 
adding porting notes to the very API itself. Which is also the place as API 
consumer I would be hoping for to get all needed information straight in one 
go, instead of having to jump to other places, which might even get out of 
sync or focus of developers (remember that current online docs of api.kde.org 
also only provide docs for latest version (and even the development one, not 
just the latest released).

And this is a change to what happened in kdelibs4 times, where most 
deprecation happened in the development branches for what became KDE 
Frameworks, so there also was no API documentation maintained at the same 
time. So copying the approach taken for the KDE Frameworks porting notes would 
not be needed here 1:1 for what I understand.

Instead we would need to add documentation for those things which are again 
deprecated (well, removed rather) during preparation of KF6, where the 
replacement also only will be in KF6, so no-one can port before.

Cheers
Friedrich