qt6-migration-pipeline/migration/MIGRATION_CHECKLIST.md

Migration checklist and template

Purpose This document standardizes the per-module migration steps to Qt6/C++20 and the minimal CMake/Docker changes required so new folders (./Lts, ./...) can be migrated repeatedly and reproducibly.

Preconditions

• app/Dockerfile and app/run_docker.sh are present and produce a Qt6 dev image with these tools: cmake (>=3.20), ninja, clang/gcc with C++20, pkg-config, libpoppler-qt6-dev, python3 + aqtinstall, and dependencies needed for Log4Qt.
• cmake/ contains helper modules created during earlier migration (Qt6-first shim, NGLMacros.cmake, FindPopplerQt5.cmake).

Per-module migration steps (template)

1. Add module to repo (new folder under ./): keep sources in place.
2. Create or adapt CMakeLists.txt for module:
   • Add a top-level target and use find_package(Qt6 REQUIRED COMPONENTS Widgets Core Gui) or the project's required Qt modules.
   • Use project-wide cmake/NGLMacros.cmake helper macros to set AUTOUIC/AUTOMOC/AUTORCC compatibility.
   • If the module uses Poppler, rely on cmake/FindPopplerQt5.cmake so existing find_package(PopplerQt5) calls remain valid.
   • Set C++ standard: target_compile_features(${proj} PUBLIC cxx_std_20) or -DCMAKE_CXX_STANDARD=20 in configure.
3. Source edits checklist (common fixes):
   • qAsConst -> std::as_const
   • QLibraryInfo::location(...) -> QLibraryInfo::path(...)
   • QVariant::type() usages: replace logging with typeName()/metaType() or use var.metaType()
   • QDateTime(..., Qt::UTC) -> QTimeZone::utc()
   • Replace Qt key operator+ with operator| for QKeyCombination/QKeySequence
   • qChecksum(...): use QByteArrayView overload
   • Poppler: prefer poppler-qt6 API adjustments (unique_ptr release or adopt ownership as needed)
   • Replace QMouseEvent::localPos() with position() where necessary
4. Add resources (.qrc) into target via qt_add_resources when building with Qt6.
5. Tests: add GoogleTest scaffolding under tests/gtest for module-specific unit tests.
6. CMake: keep old find_package(PopplerQt5) calls — cmake/FindPopplerQt5.cmake will map to poppler-qt6.
7. Local verification: run migration/migrate_module.sh and inspect output in ./build. Fix compile/test failures iteratively.
8. Commit: small, focused commits per change group (CMake, API fixes, tests). Add Co-authored-by trailer if requested.

Automation / CI suggestions

• Create a GitHub Actions job (or CI) that runs ./final-migration/run_final_migration.sh to verify the whole tree after each merge.
• Optionally enable a migration pipeline job that accepts a module path and runs migration/migrate_module.sh (use matrix for multiple modules).
• Consider adding clang-tidy/clang-format step with a strict ruleset after migration completes.

Notes

• Keep build/ ignored and out of Git. Use tags/releases for stable snapshots.
• If a module depends on third-party libs, add detection or build steps into app/Dockerfile or cmake/Find* helpers.

Use the included migration/migrate_module.sh to run and test each migration iteration reproducibly in Docker.