Qt CMake API Review
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:
- git - https://git-scm.com/downloads
- fd - https://github.com/sharkdp/fd
- tig - https://jonas.github.io/tig/
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