# Qt5/C++11 to Qt6/C++23 Migrationsplan

## 📋 Ausgangslage

### Projektstruktur
```
$PROJDIR_MIGRATE_QT5_TO_QT6 = /home/torsten/swy/sandbox/qt-migration-legatus
├── qt5-before/qt5-legatus-legacy/     (Qt5/C++11 Legacy-Code)
└── qt6-after/qt6-migrated-legatus/    (Qt6/C++23 migrierter Code)
```

### Submodule Konfiguration
- **Submodule**: `qt-migration-legatus` zeigt auf `feature/qt6-migration-basis-modules` (commit d176b5e)
- **Quellverzeichnis**: `qt5-before/qt5-legatus-legacy/` enthält vollständigen Qt5-Code mit CMakeLists.txt
- **Zielverzeichnis**: `qt6-after/qt6-migrated-legatus/` enthält bereits migrierte Module

### Bereits migrierte Module (Stand: Session a41bb15a)
✅ **Lts/Common** - Vollständig migriert, Tests erfolgreich (1/1 bestanden)
✅ **Lts/DDS** - Struktur vorhanden
✅ **Lts/Plugins** - Struktur vorhanden
✅ **Lts/Projects** - Struktur vorhanden
✅ **Lts/Proxies** - Struktur vorhanden
✅ **Lts/Services** - Struktur vorhanden
✅ **TetraIF** - Teilweise migriert
✅ **Z** - Teilweise migriert (nglwidgets, QtSingleApplication, qsql_informix, WMS_Interface)

### Infrastruktur
- ✅ Docker-Image: `migration-pipeline:ubuntu26.04` (Ubuntu 26.04, Qt 6.8.3)
- ✅ CMake 3.16+, C++23
- ✅ CI-Workflow mit `submodules: recursive`
- ✅ Migrationsskripte aktualisiert für Submodule-Pfade

---

## 🎯 Migrationsziele (aus combined-migration-compact.prompt.md)

### Hauptziele
1. **Qt5 → Qt6** Upgrade aller Module
2. **C++11/14/17 → C++23** Modernisierung
3. **Qt Core, Gui, Widgets** explizit verlinken
4. **QRegExp → QRegularExpression** ersetzen
5. **QDesktopWidget → QScreen**-basierte APIs
6. **QTextCodec** entfernen, Qt6-safe text handling
7. **SIGNAL/SLOT** alte Syntax → function-pointer connect syntax
8. **0/NULL** → `nullptr` ersetzen

### C++23 Modernisierung
- `auto` wo offensichtlich
- Strukturierte Bindings wo klarer
- Raw Pointer → `std::unique_ptr` / `std::shared_ptr`
- `std::make_unique` / `std::make_shared`
- `std::string_view` (lifetime safety beachten)
- `std::span` für non-owning contiguous data
- `.contains()` statt `find(...) != end()`
- Algorithms/Ranges statt manueller Loops
- `[[nodiscard]]` wo sinnvoll
- Early Returns statt nested control flow
- `std::optional` monadic operations
- `constexpr`, `if constexpr`, concepts, `requires`
- `noexcept`, `override`, `final`, `= default`, `= delete`
- `enum class` statt unscoped enums
- `std::print` / `std::println` (wenn unterstützt)
- Typed `std::chrono`, `std::jthread`

### Safety Rules
- ✅ Semantics first, modernize second
- ❌ KEINE Behavior Changes (außer Qt6 compatibility)
- ❌ KEINE Code Cleanup
- ❌ KEINE Umbenennungen
- ❌ KEINE Function/Class Extractions
- ❌ KEINE Logic Restructuring
- ❌ KEINE stylistic rewrites
- ❌ KEINE opportunistic improvements

---

## 📝 Migrationsphasen

### Phase 1: Vorbereitung und Analyse
**Todo-ID: prepare**
- [x] Submodule initialisieren: `git submodule update --init`
- [x] Docker-Image bauen: `docker build -t migration-pipeline:ubuntu26.04 ./app`
- [x] Bereits migrierte Module identifizieren
- [ ] Vollständige Inventur aller noch zu migrierenden Dateien
- [ ] Migrationsskripte für verbleibende Module vorbereiten

### Phase 2: Lts-Module komplett migrieren
**Todo-ID: lts-modules**
**Dependencies: prepare**

Bereits migriert:
- [x] Lts/Common
- [ ] Lts/DDS (prüfen, ob vollständig)
- [ ] Lts/Plugins (alle Untermodule prüfen)
- [ ] Lts/Projects (alle Untermodule prüfen)
- [ ] Lts/Proxies (alle Untermodule prüfen)
- [ ] Lts/Services (alle Untermodule prüfen)

**Vorgehen pro Modul (mit Test- und Docker-Validierung):**
1. `./migration/migrate_module.sh Lts/<Modul> --jobs 4`
2. **Tests erstellen**: Für jede Code-Änderung mindestens 3 Tests hinzufügen
   - Tests in `qt6-after/qt6-migrated-legatus/tests/` ablegen
   - Dateinamen: `test_<name>.cpp`, `<name>_test.cpp`, `<name>test.cpp`, oder `<name>gtest.cpp`
   - Tests in CMake registrieren (CTest)
3. **Docker-Validierung** (obligatorisch vor Commit):
   ```bash
   # Configure im Docker-Container
   docker run --rm -v $(pwd):/repo migration-pipeline:ubuntu26.04 \
     cmake -S /repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus \
           -B /repo/build -G Ninja -DCMAKE_BUILD_TYPE=Debug
   
   # Build im Docker-Container
   docker run --rm -v $(pwd):/repo migration-pipeline:ubuntu26.04 \
     cmake --build /repo/build --parallel
   
   # Tests im Docker-Container
   docker run --rm -v $(pwd):/repo migration-pipeline:ubuntu26.04 \
     ctest --test-dir /repo/build --output-on-failure
   
   # Policy-Check im Docker-Container
   docker run --rm -v $(pwd):/repo migration-pipeline:ubuntu26.04 \
     python3 /repo/ci/check_pr_policies.py
   ```
4. **Fehlerklassifikation**:
   - **Environment-Failures** (command not found, missing package): `ci/Dockerfile.ci` aktualisieren, Image neu bauen
   - **Project-Failures** (compile/link errors, test failures): Code fixen
5. Bei Erfolg: clang-tidy laufen lassen, Changes commiten

### Phase 3: TetraIF komplett migrieren
**Todo-ID: tetraif**
**Dependencies: lts-modules**

- [ ] TetraIF Hauptcode migrieren
- [ ] Alle Includes und Abhängigkeiten prüfen
- [ ] Tests erstellen (mind. 3 Tests pro Code-Änderung)
- [ ] **Docker-Validierung** (Configure → Build → Test → Policy)
- [ ] clang-tidy Integration testen

### Phase 4: Z-Module komplett migrieren
**Todo-ID: z-modules**
**Dependencies: tetraif**

Bereits teilweise migriert:
- [x] Z/src/nglwidgets
- [x] Z/src/QtSingleApplication
- [x] Z/src/qsql_informix
- [x] Z/src/WMS_Interface
- [ ] Fehlende Z-Module identifizieren und migrieren

**Vorgehen pro Modul** (wie Phase 2 mit Test- und Docker-Validierung)

### Phase 5: Vollständige Build-Validierung
**Todo-ID: full-build**
**Dependencies: lts-modules, tetraif, z-modules**

- [ ] `./final-migration/run_final_migration.sh --jobs 6` ausführen
- [ ] **Docker-Validierung komplett**:
  - [ ] Configure: `cmake -S qt6-after/qt6-migrated-legatus -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug`
  - [ ] Build: `cmake --build build --parallel`
  - [ ] Test: `ctest --test-dir build --output-on-failure`
  - [ ] Policy: `python3 ci/check_pr_policies.py`
- [ ] Alle Tests bestehen (CTest)
- [ ] Policy-Check erfolgreich

### Phase 6: CI/CD Validierung
**Todo-ID: ci-validation**
**Dependencies: full-build**

- [ ] CI-Workflow lokal simulieren
- [ ] Submodule checkout testen
- [ ] Alle Migrationsschritte im CI-Kontext verifizieren
- [ ] Build-Artefakte prüfen
- [ ] Test-Logs analysieren
- [ ] **Docker-Image als Source of Truth**: `lifemaps/ci-cpp:latest` (oder `migration-pipeline:ubuntu26.04`)
  - Bei fehlenden Tools: `ci/Dockerfile.ci` minimal aktualisieren
  - Image neu bauen und Validierung wiederholen

---

## 🧪 Validierungskriterien

### Pre-Migration (lokal)
- [x] `git submodule update --init` erfolgreich
- [x] Docker-Image Build erfolgreich
- [x] Lts/Common Migration erfolgreich getestet
- [ ] Vollständige Inventur aller Module

### Post-Migration (lokal)
- [ ] Configure im Docker-Container erfolgreich
- [ ] Build im Docker-Container erfolgreich
- [ ] Alle Tests bestehen (`ctest --test-dir build --output-on-failure`)
- [ ] Policy-Check erfolgreich (`python3 ci/check_pr_policies.py`)

### CI-Validierung
- [ ] Checkout mit Submodules erfolgreich
- [ ] Lts/Common Migration Step erfolgreich
- [ ] Lts/DDS Migration Step erfolgreich
- [ ] Final Migration Build ohne Fehler
- [ ] CTest läuft und besteht
- [ ] Workflow-Zeit < 120 Minuten

---

## 📊 Fortschrittsübersicht

### Migrierte Module (✅)
| Modul | Status | Tests | Build | Notes |
|-------|--------|-------|-------|-------|
| Lts/Common | ✅ Vollständig | 1/1 ✅ | ✅ | Basis erfolgreich |
| Lts/DDS | 🟡 Struktur vorhanden | ? | ? | Prüfung ausstehend |
| Lts/Plugins | 🟡 Struktur vorhanden | ? | ? | 60 Untermodule |
| Lts/Projects | 🟡 Struktur vorhanden | ? | ? | 5 Untermodule |
| Lts/Proxies | 🟡 Struktur vorhanden | ? | ? | 13 Untermodule |
| Lts/Services | 🟡 Struktur vorhanden | ? | ? | 47 Untermodule |
| TetraIF | 🟡 Teilweise | ? | ? | Migration läuft |
| Z | 🟡 Teilweise | ? | ? | Einige Submodule fertig |

### Noch zu migrieren (❌)
- Alle Untermodule in Lts/Plugins (60)
- Alle Untermodule in Lts/Projects (5)
- Alle Untermodule in Lts/Proxies (13)
- Alle Untermodule in Lts/Services (47)
- Restliche Z-Module

---

## ⚠️ Risiken und Gegenmaßnahmen

### Risiko 1: Submodule Permissions
**Problem**: CI benötigt SSH-Zugriff auf `git@devel:lifemaps/qt-migration-legatus.git`
**Mitigation**: SSH-Key in CI secrets konfigurieren oder HTTPS mit Token verwenden

### Risiko 2: Git Operations in Submodules
**Problem**: `run_clang_tidy_common.sh` committet in Submodule-Pfad
**Mitigation**: Lokal testen, Submodule-Commits separat von Main-Repo-Commits betrachten

### Risiko 3: Externe Dependencies
**Problem**: Skripte erwarten `/repo/external` mit RTI Connext und ArcGIS SDK
**Mitigation**: CI stellt Dependencies bereit oder behandelt fehlende Dependencies gracefully

### Risiko 4: Nested Git Repo
**Problem**: `qt5-legatus-legacy` hat eigenes .git-Verzeichnis
**Mitigation**: `git submodule update --init` OHNE `--recursive` verwenden

---

## 🔄 Rollback-Plan

Bei kritischen Problemen:

1. **CI-Workflow revertieren**: `submodules: recursive` entfernen
2. **Migration-Skripte revertieren**: Original `-S /repo` Pfade wiederherstellen
3. **Fallback**: Alte Ordernstruktur temporär am Repo-Root wiederherstellen

---

## 📈 Nächste Schritte (sofort)

1. **Logging-Fixes validieren**: Build im Docker-Container nach Logger-Fixes testen
2. **Inventur vervollständigen**: Alle noch zu migrierenden Dateien identifizieren
3. **Lts/DDS prüfen**: Ist das Modul vollständig migriert? Build testen
4. **Lts/Plugins**: Erste Untermodule migrieren (priorisiere Kernfunktionalität)
5. **TetraIF**: Migration abschließen und validieren
6. **Vollständigen Build testen**: `./final-migration/run_final_migration.sh --jobs 6`

---

## 🛠️ Wichtige Commands

### Submodule Management
```bash
# Submodule initialisieren
git submodule update --init

# Submodule auf Branch aktualisieren
git submodule update --remote

# Submodule Status prüfen
git submodule status
```

### Migration
```bash
# Einzelnes Modul migrieren
./migration/migrate_module.sh Lts/<Modul> --jobs 4

# Vollständige Migration
./final-migration/run_final_migration.sh --jobs 6

# Clang-tidy für Modul
./migration/run_clang_tidy_common.sh Lts/<Modul>
```

### Docker-Validierung (OBLIGATORISCH)
```bash
# Configure im Container
docker run --rm -v $(pwd):/repo migration-pipeline:ubuntu26.04 \
  cmake -S /repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus \
        -B /repo/build -G Ninja -DCMAKE_BUILD_TYPE=Debug

# Build im Container
docker run --rm -v $(pwd):/repo migration-pipeline:ubuntu26.04 \
  cmake --build /repo/build --parallel

# Tests im Container
docker run --rm -v $(pwd):/repo migration-pipeline:ubuntu26.04 \
  ctest --test-dir /repo/build --output-on-failure

# Policy-Check
docker run --rm -v $(pwd):/repo migration-pipeline:ubuntu26.04 \
  python3 /repo/ci/check_pr_policies.py
```

### Docker-Image bei fehlenden Tools
```bash
# ci/Dockerfile.ci bearbeiten (fehlendes Package hinzufügen)
# Dann Image neu bauen:
docker build -t migration-pipeline:ubuntu26.04 ./app

# Validierung wiederholen
```

---

## 📝 Session-Referenzen

- **Session a41bb15a-b5cc-4955-8d71-0169516fcef3**: Vorherige Migration-Sessions
- **Checkpoint 008-qt6-migration-infrastructure**: Letzte Infrastruktur-Updates
- **Submodule Branch**: `feature/qt6-migration-basis-modules` @ d176b5e

---

**Erstellt**: 2026-08-18
**Aktualisiert**: 2026-08-18 (Test- und Docker-Validierungsanforderungen integriert)
**Status**: Bereit für User-Feedback und Implementierung