QtCS2021 - Documentation test builds in the CI system: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
m (Fixed links)
 
Line 10: Line 10:


==Notes==
==Notes==
* Quick presentation by Topi and Paul
** Background
*** Time consuming​: We spend an unreasonable amount of time cleaning up QDoc warnings.​
*** No safety net​: Warnings enter the code base, cleanup happens after-the-fact.​
*** Monitoring​: We track qdoc warnings and how they develop over time. Is this an effort better spent doing something else?​
*** COIN​: CI blocks compiler warnings, why not QDoc warnings?​
** Proposal
*** Provision the tools we need in one CI configuration​.
*** Enforcement per module​.
*** Dealing with special cases​.
** The nitty-gritty​
*** Tools provisioning:​ https://codereview.qt-project.org/c/qt/qt5/+/331624​
*** QDoc-specific instructions during testing:​ https://codereview.qt-project.org/c/qt/qtbase/+/331625​
*** QDoc warning documentation:​ https://doc.qt.io/qt/qdoc-warnings.html​


* Per repo only, warnings for cross-linking references will be disregarded for technical reasons.
*Quick presentation by Topi and Paul
* One Ubuntu configuration only, as that's where release docs are built.
**Background
* Per module control, meaning modules can be excluded in special cases.
***Time consuming​: We spend an unreasonable amount of time cleaning up QDoc warnings.​
***No safety net​: Warnings enter the code base, cleanup happens after-the-fact.​
***Monitoring​: We track qdoc warnings and how they develop over time. Is this an effort better spent doing something else?​
***COIN​: CI blocks compiler warnings, why not QDoc warnings?​
**Proposal
***Provision the tools we need in one CI configuration​.
***Enforcement per module​.
***Dealing with special cases​.
**The nitty-gritty​
***Tools provisioning:​ https://codereview.qt-project.org/c/qt/qt5/+/331624<nowiki/>​
***QDoc-specific instructions during testing:​ https://codereview.qt-project.org/c/qt/qtbase/+/331625<nowiki/>​
***QDoc warning documentation:​ https://doc.qt.io/qt/qdoc-warnings.html<nowiki/>​


=== Discussion ===
*Per repo only, warnings for cross-linking references will be disregarded for technical reasons.
* Enforcing no warnings would be good; potential problem: introducing new C++ standard features where QDoc struggles, for examples (e.g. when C++17 was introduces with Qt 6). What happens when C++20 shows up in Qt?
*One Ubuntu configuration only, as that's where release docs are built.
** Possibly port QDoc from C-based clang API to C++-based API
*Per module control, meaning modules can be excluded in special cases.
** Intention is to support development,  
 
* Effort needed from doc team and CI team? CI system?
===Discussion===
** Patches in Gerrit are in good shape, might need some further support from the CI team.
 
** Integration times extended by the doc build time required for each repo. E.g. qtbase adds maybe as much as 10 minutes (best guess).
*Enforcing no warnings would be good; potential problem: introducing new C++ standard features where QDoc struggles, for examples (e.g. when C++17 was introduces with Qt 6). What happens when C++20 shows up in Qt?
** Might run in parallel and not add integration time at all.
**Possibly port QDoc from C-based clang API to C++-based API
* Should doc builds run early to fail integrations early?
**Intention is to support development,
** Play around with alternatives to provide quick feedback.
*Effort needed from doc team and CI team? CI system?
**Patches in Gerrit are in good shape, might need some further support from the CI team.
**Integration times extended by the doc build time required for each repo. E.g. qtbase adds maybe as much as 10 minutes (best guess).
**Might run in parallel and not add integration time at all.
*Should doc builds run early to fail integrations early?
**Play around with alternatives to provide quick feedback.

Latest revision as of 11:55, 23 June 2021


Session Summary

Every release of Qt brings with it a lot of "fire fighting" in terms of getting rid of QDoc's warnings across all modules. We propose to block changes that introduce QDoc warnings in CI. This is a session to discuss the proposed solution to the problem.

Session Owners

  • Paul Wicking / Topi Reiniö (documentation.infrastructure@qt.io)

Notes

  • Quick presentation by Topi and Paul
    • Background
      • Time consuming​: We spend an unreasonable amount of time cleaning up QDoc warnings.​
      • No safety net​: Warnings enter the code base, cleanup happens after-the-fact.​
      • Monitoring​: We track qdoc warnings and how they develop over time. Is this an effort better spent doing something else?​
      • COIN​: CI blocks compiler warnings, why not QDoc warnings?​
    • Proposal
      • Provision the tools we need in one CI configuration​.
      • Enforcement per module​.
      • Dealing with special cases​.
    • The nitty-gritty​
  • Per repo only, warnings for cross-linking references will be disregarded for technical reasons.
  • One Ubuntu configuration only, as that's where release docs are built.
  • Per module control, meaning modules can be excluded in special cases.

Discussion

  • Enforcing no warnings would be good; potential problem: introducing new C++ standard features where QDoc struggles, for examples (e.g. when C++17 was introduces with Qt 6). What happens when C++20 shows up in Qt?
    • Possibly port QDoc from C-based clang API to C++-based API
    • Intention is to support development,
  • Effort needed from doc team and CI team? CI system?
    • Patches in Gerrit are in good shape, might need some further support from the CI team.
    • Integration times extended by the doc build time required for each repo. E.g. qtbase adds maybe as much as 10 minutes (best guess).
    • Might run in parallel and not add integration time at all.
  • Should doc builds run early to fail integrations early?
    • Play around with alternatives to provide quick feedback.
Retrieved from "https://wiki.qt.io/index.php?title=QtCS2021_-_Documentation_test_builds_in_the_CI_system&oldid=38472"