Add migration helpers: migrate_module.sh and MIGRATION_CHECKLIST.md\n\nProvide a repeatable migration script and checklist to standardize adding modules (./Lts, ./...) for Qt6/C++20 migration.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

migration/MIGRATION_CHECKLIST.md

@@ -0,0 +1,41 @@
+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.

migration/migrate_module.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# migration/migrate_module.sh
+# Usage: ./migration/migrate_module.sh <module-path> [--jobs N]
+# Runs a reproducible configure/build/test of the specified module inside the app docker
+
+MODULE_PATH=${1:-}
+if [[ -z "$MODULE_PATH" ]]; then
+  echo "Usage: $0 <module-path> [--jobs N]"
+  exit 1
+fi
+
+JOBS=4
+shift || true
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --jobs) JOBS="$2"; shift 2;;
+    -j*) JOBS="${1#-j}"; shift;;
+    *) echo "Unknown arg: $1"; exit 1;;
+  esac
+done
+
+# Ensure path is relative to repo root
+MODULE_ABS="/repo/$(realpath --relative-to=$(pwd) "$MODULE_PATH")"
+
+# Use app/run_docker.sh to run the migration inside the prepared Qt6 image
+# The container will configure just the requested module in a clean build directory.
+
+./app/run_docker.sh ../sandbox -- bash -lc   "set -euo pipefail && export LD_LIBRARY_PATH=/opt/Qt/6.8.3/gcc_64/lib:\${LD_LIBRARY_PATH:-} && export QT_QPA_PLATFORM=offscreen && rm -rf /repo/build && mkdir -p /repo/build && cd /repo/build && \    cmake -S /repo -B /repo/build -G Ninja -DCMAKE_PREFIX_PATH=/opt/Qt/6.8.3/gcc_64 -DCMAKE_CXX_STANDARD=20 -DMIGRATE_MODULE=${MODULE_PATH} -DBUILD_TESTING=ON && \    cmake --build /repo/build -- -j${JOBS} && ctest --test-dir /repo/build --output-on-failure"
+
+echo "Migration run for module ${MODULE_PATH} finished. Check ./build for logs and artifacts."