Re: Re : KApiDox move from dedicated server to Jenkins
Hi, On 9/10/21 21:17, Ben Cooksley wrote: On Sat, Sep 11, 2021 at 5:40 AM Carl Schwan wrote: We also are losing the krita/kmymoney/other app private api generation, but that maybe can be generated in another ci pipeline later. Not sure how much thses apps' developers are using it. This can likely be rectified if needed by including them within https://invent.kde.org/sysadmin/binary-factory-tooling/-/blob/master/apidocs/repos-to-process So, we would need to decide whether we want to have applications that only have private APIs documented? Where do we draw the line currently? In general I would say, just generate everything that has a Doxyfile ... but there might be good reasons against that regarding processing power? Cheers, Frederik
Re: Re : KApiDox move from dedicated server to Jenkins
Hi, On 9/10/21 19:39, Carl Schwan wrote: I see on an issue that I would qualify as blocking and it's the lack of the ECM generated doc: https://api-dev.kde.org/ecm. We are also losing the kube/sink doc (located at api.kde.org/doc/sink) but it's also available in readthedocs and ihmo it should be in Doxygen format. We also are losing the krita/kmymoney/other app private api generation, but that maybe can be generated in another ci pipeline later. Not sure how much thses apps' developers are using it. Thanks for the list. I will look into those. On the upside, I see that mauikit doc is finally correctly generated using qdoc. Yeah \o/ mauikit produces some warnings, in case someone wants to fix those (or tone down the warning level): https://binary-factory.kde.org/job/Generate_API_Documentation/13/consoleFull There are also other warnings and errors, I will look at soon. Those are secondary though, as in they have been there before. Cheers, Frederik
Re: KApiDox move from dedicated server to Jenkins
Hi, On 9/11/21 00:30, Ben Cooksley wrote: I've now completed transferring a copy of all of the Older API Documentation to https://api-dev.kde.org/legacy/ This is aliased in from elsewhere on the server, so it's contents won't be disturbed by the automatic generation process we have for new KApiDox based documentation. I also included the legacy CMake documentation when setting that up. If we could please update the front page to point there that should resolve this point. For me it makes more sense to keep the link to api.kde.org because once we switch to the new system, we would have to change that link again. Now with all the files in place (thanks for that :)) the links will just continue to work. Cheers, Frederik
KApiDox move from dedicated server to Jenkins
Hi, we have been working on getting KApiDox to run on Jenkins. This work has been taken way longer than I expected but has now reached a state close to finished. :) So I would like to invite you to check https://api-dev.kde.org/ for any show stoppers. Known issues (not show stoppers): - For now the Maintainers field defaults to "KDE Developers" for potential GDPR violation reasons, which needs to be figured out later. - Some modules contain formatting issues regarding markdown code blocks. These are also there in the current system and need to be checked at some point. - The "Older versions" links are broken. Since those docs are not generated anymore, we need to figure out a way to have them available statically. If we do not see any bigger issues, I would like to go live with the new system in a week or two. Thanks for your help. CHeers, Frederik
Re: Noteworthy changes when porting to C++17
On 7/19/21 5:52 PM, David Faure wrote: On dimanche 18 juillet 2021 02:34:24 CEST Frederik Schwarzer wrote: So the question is: did you notice things that have been removed from the C++ standard since C++11 that were used in our applications? I found a list of things that were removed from C++11 in C++17: http://www.cplusplus2017.info/removed-features-from-c17/ Maybe you can simply link to this document? Thanks for the link. :) Yes, it was my plan to link to such kind of information but I was also thinking of going into a bit more detail on one or two of those in case they were quite common in KDE land. But apparently this is not the case. Cheers, Frederik
Re: Noteworthy changes when porting to C++17
Hi, Thanks for the links. I know about those papers but I do not think we should point KF6 application porters there because the vast majority of the stuff mentioned is very unlikely to affect them. For now I will go with some general remarks here. Cheers, Frederik On 7/18/21 10:22 AM, David Redondo wrote: Hi I found these two papers http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1319r0.html http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0636r1.html Regards, David
Noteworthy changes when porting to C++17
Hi, since we are increasing the C++ standard requirement from 11 to 17 with KF6 and there were a few deprecations/removals in between, I wonder if any of those are noteworthy for people developing applications based on KDE Frameworks. What I mean by "noteworthy" is features that are commonly used or at least known to be used sometimes in our ecosystem. Things like the "register" keyword for example might not be found in high-level applications so pointing KDE developers to its removal might get you shrugs in return. What I have seen is that std::mem_fun was used within KIO and has been replaced by std::mem_fn. Not sure if that counts as "commonly used", though. Compiler vendors seem to be handling those removalss differently. The libstdc++ devs have not had deprecation warnings for at least some of the stuff that was deprecated in C++11, so they will not remove those any time soon. https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91383#c1 In libc++, the deprecation warnings were shown since C++11 and now with C++17 they removed some stuff. On Linux you will have to build with the -stdlib=libc++ option for clang to notice. See e.g. https://godbolt.org/z/6Y1eE3z4P for playing with it. But I digress ... So the question is: did you notice things that have been removed from the C++ standard since C++11 that were used in our applications? Cheers, Frederik
Re: Porting notes / deprecation docs
On 7/12/21 8:43 PM, Friedrich W. H. Kossebau wrote: Am Montag, 12. Juli 2021, 20:22:30 CEST schrieb Frederik Schwarzer: On 7/12/21 7:38 PM, Friedrich W. H. Kossebau wrote: Now what is meant by "clickable links to replacements" exactly? Any example for what you have in mind? (Just in case, Doxygen usually itself already generated automatic links to the functions (just needs complete signature, incl. const), see also https://www.doxygen.nl/manual/autolink.html but then I would guess you know that) Yes, that's what I meant. api.k.o does have clickable links (if done properly) but compiler warnings do not. That's why it would be good to keep the KF5 api docs. Ah, so html pages on a server/local docs in QCH vs. compiler log, I see :) If we put URLs in the messages, we could click them in Konsole. ;) Any insight on how you kept the KDE 2-4 apidocs alive? Mainly defending against admin wanting to clean up dead stuff and just wiping the current freak setup behind api.kde.org ;) (which is https:// invent.kde.org/websites/quality-kde-org) Right now the kdelibs 2-4 docs are no longer regenerated (at the time when I got involved only the 4 one still was, but now also no longer is, and just is static files on the web server. I did some URL updates e.g. for trolltech.com- qt.io using mass regexp replacements on them). IIRC main file of the generation is https://invent.kde.org/websites/quality-kde-org/-/blob/master/apidox/src/ gendox.sh But I dropped out when there were people talking about their progress in writing a replacement and put my hopes & bet on them. But seems life got in then it seems... I cannot check what is used on the server but I was told https://invent.kde.org/frameworks/kapidox/-/blob/master/src/kapidox_generate would be the script that generates apidocs on the server. Maybe someone can clarify? CHeers, Frederik
Re: Porting notes / deprecation docs
On 7/12/21 7:38 PM, Friedrich W. H. Kossebau wrote: Some hopefully helpful quick comments from couch: Am Montag, 12. Juli 2021, 19:14:17 CEST schrieb Frederik Schwarzer: - 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 Yes, ideally that should be backed up by some web page perhaps, informing anyone how to get in touch with whom to make a user and their needs known, for finding a solution. - 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? When doing my own little contributions to keep api.kde.org alive last year, I also made sure to have the so far existing kdelibs 2-4 API still available, see https://api.kde.org/history.php (reached via "Old KDE Versions" from api.kde.org mainpage). The same hopefully can be done for KF5 (and other libraries who would need versioned docs). Now what is meant by "clickable links to replacements" exactly? Any example for what you have in mind? (Just in case, Doxygen usually itself already generated automatic links to the functions (just needs complete signature, incl. const), see also https://www.doxygen.nl/manual/autolink.html but then I would guess you know that) Yes, that's what I meant. api.k.o does have clickable links (if done properly) but compiler warnings do not. That's why it would be good to keep the KF5 api docs. Any insight on how you kept the KDE 2-4 apidocs alive? Cheers, Frederik
Re: Porting notes / deprecation docs
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
Re: Porting notes / deprecation docs
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
Re: Porting notes / deprecation docs
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
Re: Porting notes / deprecation docs
On 7/10/21 6:17 PM, Ahmad Samir wrote: On 10/07/2021 18:00, Frederik Schwarzer wrote: Hi, as mentioned earlier, I would like to document classes/methods/etc that are going to be deprecated during KF6 development. For that I scraped up all the deprecation macros from the frameworks and edited them to be more unified. Good work, that must have been a huge task! (82 frameworks ... :)). grep ran a few seconds to give me a 2600 lines text file, which I then had to edit to be more readable, which took me several hours. :) The hard part is still about to come. :) As for the location, I would probably start putting content in the community wiki to a place like https://community.kde.org/Frameworks/KF6_Porting_Notes. Does anyone see a problem with that? Might is be better to write such docs in markdown or restructured text for being better suited for a more modern location? A wiki page is not most friendly way of editing huge technical documents. Personally, I think a markdown file in a git repo would be great, and then it can be "published" to a wiki page or a static web page on one of KDE's web sites. Or, we start with an markdown text file, then after it's fleshed out / polished, put it in the wiki, editing/adding a small section here or there would be easier. (But I do prefer text files, much easier to edit in my usual editor of choice). Yes, I agree. A text file in Git is also better for tracking changes. FWIW, there is supposed to be a KF6 meeting soon[1]. Not sure if we'll start this week or the next one though. I have the Mondays on my calendar now. :)
Porting notes / deprecation docs
Hi, as mentioned earlier, I would like to document classes/methods/etc that are going to be deprecated during KF6 development. For that I scraped up all the deprecation macros from the frameworks and edited them to be more unified. Now I need some opinions. For once, there is still some stuff in deprecation from KDE4 times. E.g. void setDoScanFile(bool scanFile); from kiowidgets. I looked up a few of them in https://community.kde.org/Frameworks/Porting_Notes but they are not mentioned there. Do you think these need to be mentioned in current porting notes as well or have they been deprecated for long enough to consider them "over with"? As for the location, I would probably start putting content in the community wiki to a place like https://community.kde.org/Frameworks/KF6_Porting_Notes. Does anyone see a problem with that? Might is be better to write such docs in markdown or restructured text for being better suited for a more modern location? Thanks! Cheers, Frederik
