[Development] QtCS2019 Notes from "API Review Process" session

[Volker Hilsheimer]

Hi,

Here and below are the notes from this session:

https://wiki.qt.io/Qt_Contributors_Summit_2019_-_API_Review_Process


Cheers,
Volker


Current processes as part of final release preparations:

* https://wiki.qt.io/API_change_review
* http://quips-qt-io.herokuapp.com/quip-0010-API-review.html

* agree that the current process is useful and should stay, but too late in the 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