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:**
```yaml
- 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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
- [x] Run `git submodule update --init --recursive` locally
- [x] Verify `qt-migration-legatus/qt6-after/qt6-migrated-legatus/CMakeLists.txt` exists
- [x] 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
- [x] Verify Docker image tag consistency: All scripts now use `migration-pipeline:ubuntu26.04`
- [x] 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