Porting notes / deprecation docs

[Frederik Schwarzer]

Hi,

On 7/10/21 7:38 PM, Friedrich W. H. Kossebau wrote:
> Am Samstag, 10. Juli 2021, 18:00:13 CEST schrieb Frederik Schwarzer:
>> as mentioned earlier
> 
> Any pointers? :)

It was discussed in the weekly BBB meetings a few weeks ago.


>> 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?

Everything that is marked deprecated when KF6 sees the light of day.


>> 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.

The idea is to have the APIs that are being deprecated now documented 
when those APIs (and with it the API docs) are removed.
The audience is everyone who is starting the porting work when KF6 is 
already there for some time.

Yes it is manual work. However, since the documentation does not remove 
stuff that has been removed from the API, it's a thing of adding newer 
deprecation markers, which seems manageable.

Do you disagree?

Cheers,
Frederik