Porting notes / deprecation docs

[Friedrich W. H. Kossebau]

Am Samstag, 10. Juli 2021, 22:47:58 CEST schrieb 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 see. As contributor on occasions only myself, please refer to the respective 
meeting notes some thankfully write, so one can read up on more background, 
and such a planned task ideally would be backed up by a task board entry on 
phabricator, so people can coordinate and track things about it in an async 
manner.

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

Okay. Not a good idea IMHO. There should be a single place of information, and 
we have that already with the current KF5 API docs. I hope no-one plans to 
just remove them from the website, though, Well, then there are also the 
offline docs in QCH format as backup generated during the builds and packaged 
by good distributions ;)

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

Ideally that audience should get the recommendation to first port away from 
deprecated API using the last released version of KF5 and Qt6. That way they 
are able to do a big chunk of the work while being able to maintain a fully 
working state of their software, without serious regressions. Once that 
checkpoint is reached, then go for porting all those things which disappeared/
changed in KF6 & Qt6 without any preparations in KF5 & Qt5.

Remember that this is not just KF 5 -> 6, but also Qt 5 -> 6. And perhaps even 
C++11 -> C++17. IMHO only those would recommend to port directly from one set 
of APIs to an other one without any intermediate checkppints for the working 
sate of the software who want to secure their job for a while, because it will 
take ages to fix all the regressions introduced during the port. Unless the 
company/community goes down in the meantime, because the ported software does 
not get done.

BTW, even the Qt Company recommends that step-by-step approach, and they 
surely do want to have their customers be successful in a short time ;) ->
https://doc.qt.io/qt-6/portingguide.html

That is also why some of us invested so much of our time into properly tagging 
API with deprecations warning macros and visibility guards, so porting can be 
done step by step away from the old AP assisted by the compiler, always having 
a working software. Because we have been through some porting in KDE and 
learned our lessons, haven't we... ;)

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

While perhaps it might be a nice thing to have a shortcut list of API that is 
deprecated in KF5 times, as a manifest to look-up things, ideally we find ways 
to auto-generate that from the existing API markup.

After all KDE is a software developing community, so we should be able to 
automate that, no? ;)

So, I can only really ask to keep documentation of KF5's deprecated API in one 
place, and do it properly there, with nice examples, already now useful to 
those who port away when they can. And that place should be the current KF5 
API docs.
Even more as people come and go, and having yet another place which needs to 
be kept even more manually up-tod-ate does not improve things, it adds more 
risk to have outdated unmaintained information. As you could see in review, it 
already now needs poking in every second review to have proper documentation. 
And then also do that in some separate content?

What would be very good to have though IMHO, are preparations of the porting 
documentation of that API which is not deprecated in KF5, but will be replaced 
by something else in KF6 (because it cannot be done earlier for reasons). The 
KF6 task board should have some data about such plans.
Such documentation will need a place and a structure, so also need someone to 
work on and prepare it, so developers can put in the data once those 
replacements are created during KF6 init phase.

My 2 cents

Cheers
Friedrich