Qt Contributors Summit 2019 - API Review Process

From Qt Wiki
Revision as of 16:16, 22 November 2019 by EdwardWelbourne (talk | contribs) (Use Wiki link rather than "external" link within this wiki !)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Current processes as part of final release preparations:

  • agree that the current process is useful and should stay, but it happens too late in the release process

Additional comments

  • hard to get APIs reviewed from people (even for TQtC-people)
  • the Python bindings require an early API freeze
  • want to involve documentation team (earlier)
    • API design issues tend to surface when writing documentation
    • Creator team triggers a process with the documentation team when .ui files change
    • Updating examples (or at least doc snippets) when we introduce new APIs; make sure that new best practices are demonstrated in examples
  • adding tests when introducing new APIs

Proposal

  • gerrit can trigger an API review when public headers change - require a separate +2 on API changes
    • add a topic/tag/label to make such changes searchable
    • any approver can give that +2
  • have a group of “API reviewers” that support the community with API design
    • knowledge of Qt and existing APIs and patterns
    • people from documentation and support teams might be good candidates
    • we don’t want to introduce more bureaucracy, or small group of extra-privileged community members

Other follow-up actions

  • improve documentation of API design principles, make existing documentation more visible, update it (modern C++, QML)

Other topics

  • some clang-based tooling could help to confirm basic API conformance (isBooleanProperty)
  • good collaboration tooling for screen sharing and real-time conversations would really help