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 <module-path> 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.