Hi,
so there has been a bit more discussion in today's KF6 weekly meeting
about how to proceed with porting docs.
- Porting documentation needs an entry page pointing to the several
resources like C++ deprecations, Qt6 porting guides, KF6 porting
notes
- KF6 porting notes should follow a similar approach like Qt6 porting
(first compile with the latest KF5 version, which will be part of
distros for quite some time and get rid of all deprecation warnings
and then make it compile against KF6)
- Might it be a good idea to document a selected set of API
deprecations to have them in a readable format? Candidates are ones
where it needs more that one or two lines of explanation
- If not documented separately, should existing deprecation messages
be improved? "no known users" might not be enough for the "unknown
users" in 3rd-party applications who get that message
- Is it possible/desirable to keep the latest KF5 API docs as it is
generated on api.k.o to have deprecation messages with clickable links
to replacements?
Opinions/additions?
Cheers,
Frederik
On 7/11/21 2:24 PM, Frederik Schwarzer wrote:
Hi,
On 7/10/21 11:54 PM, Friedrich W. H. Kossebau wrote:
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.
https://mail.kde.org/pipermail/kde-frameworks-devel/2021-June/117653.html
Of course that out-of-context sentence at the end does not represent
properly what has been said by people then. Some follow-up discussion
lead to the "just grep it and put it somewhere first" approach.
What I take out of this now is that I need to be more phony about what I
am planning on doing.
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.
Those are all very good points that I wish I had learned about weeks
ago. ;)
About automating the extraction process:
Sometimes it is better for a (kind-of) one-shot action to do it manually
instead of writing a tool that maybe is harder to do than anticipated
and in the end there is an 80% finished tool that's not suitable for the
job (yet) and the actual work is not done because everyone is waiting
for the perfect solution. I suspect, I am not the only one who went down
that road one time or another. :D
Regarding single source of truth:
There was the argument that the deprecation macros would be removed at
some point and then 3rd-party developers would be left alone with just
removed API. In that scenario the extracted information would have
become that single source of truth.
That argument does not hold, of course, if we (as you suggest) promote
the porting steps as they are currently suggested for Qt porting. I need
to dig into that a bit to better understand the process.
I would like to hear more opinions about this, even if they just agree
with points already made.
Thanks so far.
Cheers,
Frederik