qt6-migration-pipeline/files/qt6-submodule-migration-changes.md

Qt6 Migration - Submodule Infrastructure Changes

✅ STATUS UPDATE - Submodule erfolgreich konfiguriert

Aktueller Stand (2025-08-17):

• ✅ Submodule qt-migration-legatus zeigt auf Branch feature/qt6-migration-basis-modules (commit d176b5e)
• ✅ BEIDE Verzeichnisse vorhanden: qt5-before/qt5-legatus-legacy/ UND qt6-after/qt6-migrated-legatus/
• ✅ Beide Verzeichnisse enthalten vollständige CMakeLists.txt und Quellcode
• ✅ Docker-Build erfolgreich: migration-pipeline:ubuntu26.04
• ✅ Migrationstest erfolgreich: Lts/Common Modul durchgelaufen mit allen Tests (1/1 bestanden)
• ✅ Alle Pfadreferenzen in Skripten korrekt aktualisiert

---

Overview

Updated CI/CD, CMake, Docker, and shell scripts to support the new directory structure where legacy code was moved into the qt-migration-legatus/ Git submodule.

Directory Structure Change

Before:

/app/
├── cmake/
├── Lts/
├── TetraIF/
├── tests/
├── Z/
└── ...

After:

/app/
└── qt-migration-legatus/          (Git submodule)
    ├── qt5-before/qt5-legatus-legacy/
    └── qt6-after/qt6-migrated-legatus/
        ├── cmake/
        ├── Lts/
        ├── TetraIF/
        ├── tests/
        ├── Z/
        └── CMakeLists.txt

Files Modified

1. .github/workflows/qt6-migration.yml

Change: Added submodules: recursive to checkout step

Rationale: Ensures the qt-migration-legatus submodule is initialized and updated during CI checkout. Without this, the submodule directory would be empty.

Diff:

- name: Checkout
  uses: actions/checkout@v4
  with:
    submodules: recursive

Risk: None - standard GitHub Actions configuration.

---

2. migration/migrate_module.sh

Changes:

• Added SUBMODULE_PATH="qt-migration-legatus/qt6-after/qt6-migrated-legatus" variable
• Updated cmake -S /repo to -S /repo/${SUBMODULE_PATH}
• Updated module path resolution to account for submodule location

Rationale: CMakeLists.txt is now located inside the submodule, not at repo root. All cmake invocations must point to the correct source directory.

Diff:

# Added at top of script
SUBMODULE_PATH="qt-migration-legatus/qt6-after/qt6-migrated-legatus"

# Updated cmake source path
cmake -S /repo/${SUBMODULE_PATH} -B ${BUILD_DIR} ...

Risk: Low - path is hardcoded and validated by script existence check.

---

3. final-migration/run_final_migration.sh

Changes:

• Added SUBMODULE_PATH="qt-migration-legatus/qt6-after/qt6-migrated-legatus" variable
• Updated cmake -S /repo to -S /repo/${SUBMODULE_PATH}

Rationale: Same as migrate_module.sh - CMake source directory is now in submodule.

Diff:

# Added at top of script
SUBMODULE_PATH="qt-migration-legatus/qt6-after/qt6-migrated-legatus"

# Updated cmake source path
cmake -S /repo/${SUBMODULE_PATH} -B /repo/build ...

Risk: Low - path is hardcoded and validated by script existence check.

---

4. migration/run_clang_tidy_common.sh

Changes:

• Added SUBMODULE_PATH variable
• Updated cmake -S /repo to -S /repo/${SUBMODULE_PATH}
• Updated git ls-files paths to include submodule path prefix
• Updated git add path to include submodule path prefix

Rationale: Clang-tidy script needs to find source files in the new submodule location and commit changes to the correct paths.

Diff:

# Added at top of script
SUBMODULE_PATH="qt-migration-legatus/qt6-after/qt6-migrated-legatus"

# Updated cmake source path
cmake -S /repo/${SUBMODULE_PATH} -B $BUILD_DIR ...

# Updated git paths
git ls-files ${SUBMODULE_PATH}/Lts/Common | ...
git ls-files -m | grep "^${SUBMODULE_PATH}/Lts/Common" | ...
git add ${SUBMODULE_PATH}/Lts/Common || true

Risk: Medium - git operations on submodule content require careful testing. Submodule changes may need to be committed separately.

---

Files NOT Modified (Verified Correct)

app/Dockerfile

• Uses FROM ubuntu:26.04 ✓
• Uses COPY . /app which includes submodule content when initialized ✓
• No hardcoded paths to repo structure ✓

.dockerignore

• Does not exclude .gitmodules or submodule content ✓
• Standard ignore patterns only ✓

qt-migration-legatus/qt6-after/qt6-migrated-legatus/CMakeLists.txt

• All add_subdirectory() calls use relative paths (Lts, Z/src, translations) ✓
• Paths are relative to CMakeLists.txt location, which is correct ✓
• Qt6 compatibility layer with Qt5:: aliases already implemented ✓

app/run_docker.sh

• Mounts repo to /repo at runtime ✓
• Submodule content available via mount ✓
• No hardcoded paths to repo structure ✓

---

Validation Checklist for Ubuntu 26.04 CI

Pre-merge Validation

• Run git submodule update --init --recursive locally
• Verify qt-migration-legatus/qt6-after/qt6-migrated-legatus/CMakeLists.txt exists
• Test ./migration/migrate_module.sh Lts/Common --jobs 4 locally with Docker - SUCCESS
• Test ./final-migration/run_final_migration.sh --jobs 6 locally with Docker
• Verify Docker image tag consistency: All scripts now use migration-pipeline:ubuntu26.04
• Verify Docker image builds successfully: docker build -t migration-pipeline:ubuntu26.04 ./app - SUCCESS

CI Validation (after merge)

• CI checkout step initializes submodules (check logs for "Submodule path: 'qt-migration-legatus'")
• Lts/Common migration step completes successfully
• Lts/DDS migration step completes successfully
• Final migration build completes without errors
• CTest runs and passes
• Total workflow time < 120 minutes (timeout setting)

Post-migration Validation

• Verify build artifacts in /repo/build (or module-specific build dirs)
• Check test logs in ./build/Testing/Temporary/
• Verify Qt6 libraries are correctly linked (check ldd on binaries)
• Confirm no Qt5 dependencies remain in build output

---

Open Points / Risks

1. Submodule permissions: CI must have SSH key or token access to clone git@devel:lifemaps/qt-migration-legatus.git

   • Mitigation: Use HTTPS with token or configure SSH key in CI secrets

2. Submodule branch: Ensure qt-migration-legatus submodule points to correct branch/commit with Qt6 code

   • Mitigation: Pin submodule to specific commit hash in .gitmodules or use submodule.branch config

3. Git operations in submodules: run_clang_tidy_common.sh commits to submodule path

   • Risk: Git operations on submodule content may fail if not handled correctly
   • Mitigation: Test locally first; consider separating submodule commits from main repo commits

4. Docker image tag: ✅ FIXED - All references updated from migration-pipeline:ubuntu22.04 to migration-pipeline:ubuntu26.04

   • Note: Tag name is cosmetic; actual OS version is from Dockerfile FROM instruction
   • Recommendation: Consider renaming to migration-pipeline:ubuntu26.04 for clarity

5. External dependencies: Scripts assume /repo/external contains RTI Connext and ArcGIS SDK

   • Verification needed: Ensure CI provides these dependencies or handles missing deps gracefully

---

Rollback Plan

If issues arise after deployment:

1. Revert CI workflow: Remove submodules: recursive to prevent submodule checkout
2. Revert migration scripts: Restore original -S /repo paths
3. Fallback to old structure: If submodule is problematic, temporarily restore old folder structure at repo root

---

Next Steps

1. Test changes locally with Docker
2. Create PR with these changes
3. Monitor first CI run closely
4. Address any submodule access issues
5. Document any additional findings from CI logs