QtCS2024 Quo Vadis, TTLOFIR

Abstract

"Things to look out for in review" (https://wiki.qt.io/Things_To_Look_Out_For_In_Reviews) started as a low-entry-barrier way to collect guidelines surrounding code^Wgit-versioned contributions, to be distributed to "official" documents as time goes by. While I believe it had a positive impact on many Qt contributors already in the present form, I still see (too) many of the issues, discussed there, in approved code, suggesting that it may be time to migrate some of the content to said "official" format (QUIP? Qt Coding Standard (no, not the whitespace formatting guideline that currently carries the name)). Also, the number of contributions to TTLOFIR from others than myself remains relatively small (with an explicit shout-out to those who did contribute!). Seeing as the number of Qt contributors only continues to grow (itself a very healthy sign), I think the project is facing a bit of "didn't know; if known, didn't read; if read; didn't understand; if understood, didn't apply" going on. So this session is both to spread awareness, as well as discuss how the process to migrate TTLOFIR items to a more "official" format could look like.

Minutes

• Owner: Marc Mutz
• Notes taker: Volker Hilsheimer

• TTLOFIR wiki page a collection of things we learn
  • great source of knowledge
• not meant for deep linking into from code or commit messages
• was not meant to be a coding standard, but we don't really have anything else
  • coding style not really consistently used, not updated (e.g. wrt C++17)
  • we have some API design rules; not very visible, and also not well disseminated
• if it should become the de-facto coding and API-design standard, we need to move it to something more authoritative than a wiki page
  • as it is, maintainers can disagree with certain guidelines
  • e.g. as a QUIP, changes would go through an official approval process

• Items on the list that must be adhered to need to go through a review process
  • items that define technical aspects of our API that we cannot easily change (e.g. because of ABI or API compatibility)
  • makes sure that everyone can be aware of it, can be on-boarded
  • QUIP process facilitates the discussion, and what gets approved has authority
  • maintainers shouldn't light-heartedly override those rules based on personal preference (e.g. trailing comma in enums, passing small types by value)

• How can we enforce the rules
  • a bot could be implemented
  • extending the sanity bot if parsable (although preferably not in Perl)
  • clazy resulted from a similar process at KDAB
  • could use a static analyzer
    • Axivion is running but not exposed yet
  • set of rules could be defined per repo, e.g. maintainer does select which rules to care about
    • fragments the policy, which is in general not a good idea

• Header Review process in general
  • turning actions that cannot be taken immediately into blocking JIRA tickets
  • helps e.g. the Pyside or documentation team to identify APIs that are still subject to change

• Actions
  • Marc to start with selecting items from the wiki page and moving into a QUIP proposal