Qt CMake API Review

From Qt Wiki
Jump to navigation Jump to search


CMake API Review change creation

Currently the collection of which new API needs to be reviewed is not scripted and done manually.

Below is a list of commands that can help with determining / filtering for new API for a new Qt minor version.

Requirements:

Commands:

fd Macros.cmake # 1
tig origin/6.2..origin/6.3 -- '*Macros.cmake' '*Public*.cmake' # 2
git diff origin/6.2..origin/6.3 -- '*Macros.cmake' '*Public*.cmake' # 3
git log -p -Sdefine_property origin/6.2..origin/6.3 # 4
git log -p -Sfunction\(qt6_add_ origin/6.2..origin/6.3 # 5

# 6
git checkout origin/6.2
git checkout origin/6.3 -- '*Macros.cmake' '*Public*.cmake'
git commit -m "WIP: CMake public API review" -m "Task-number: QTBUG-100099"
git push gerrit HEAD:refs/for/6.3

Most of our public CMake API is contained in files called Qt6FooMacros.cmake. These can be found with fd as done in #1.

Some of them might also be in files called QtFooPublicHelpers.cmake. #2 uses tig to show commits that touched such files between two minor Qt versions, 6.2 and 6.3. To view the diff, #3 can be used.

A few more heuristics are shown in #4 and #5 which try to look for new properties and newly introduced functions that start with qt6_add_.

To follow the example of how API review is done for Qt C++ code, we might want to push the 6.2 -> 6.3 diff of relevant files, where the parent commit is the tip of origin/6.2, as done by the scripts in qtqa.git/scripts/api-review/ See https://bugreports.qt.io/browse/QTBUG-99883 and http://quips-qt-io.herokuapp.com/quip-0010-API-review.html for some details on how those are generated and what they look like.

To do that manually for CMake, one can run the commands as shown in #6. Make sure to do that in all qt repos and tag all the changes with a topic in Geritt, e.g. cmake_api_review_6_3.

The result would look something like https://codereview.qt-project.org/c/qt/qtbase/+/391187/1

After preparing and pushing the 6.2 and 6.3 diff, it's useful to filter out the implementation details and boring parts.

The result would look something like https://codereview.qt-project.org/c/qt/qtbase/+/391187/3

An additional step that can be done to facilitate an online review with multiple parties is to prepare a markdown document with the stubs of all API changes / short descriptions, and then share that via the VSCode share feature to collect action points on how to address the API review feedback.

That would look something like https://git.qt.io/alcroito/qt6-cmake-api-review/-/blob/5d38774d639a4ecbd584645b870ff78229eed9ff/api_review_qt_6_3.md