qt-migration-legatus/docs/scripts-usage.md

scripts/

Dieses Verzeichnis enthält Hilfsskripte für den Demo- und Benchmark-Workflow rund um:

• Qt5 → Qt6
• C++11 → C++23
• Copilot CLI
• Entire CLI
• Scaleway BYOK / OpenAI-kompatibler Provider
• lokale Reproduzierbarkeit der Migration

Übersicht

create-qt5-legacy-benchmark.sh

Erzeugt das Legacy-Beispielprojekt unter:

qt5-before/qt5-legacy-migration-benchmark

Das Projekt ist absichtlich veraltet aufgebaut, um eine realistische Migration zu erzwingen, z. B. mit:

• QRegExp
• QDesktopWidget
• QTextCodec
• alter SIGNAL/SLOT-Syntax
• Qt5::Core, Qt5::Gui, Qt5::Widgets
• C++11

run-entire-copilot-migration.sh

Standard-Workflow für eine Copilot-CLI-Migration mit Entire:

1. Entire für Copilot CLI aktivieren
2. Baseline committen
3. Copilot-Session starten
4. Ergebnis committen
5. Checkpoints anzeigen
6. letzten Stand mit Entire erklären

Dieses Skript ist für den normalen Migrationslauf gedacht.

Modellwahl: Das Skript akzeptiert optional ein Modell als zweiten Parameter.

Default:

./scripts/run-entire-copilot-migration.sh

verwendet intern:

copilot --model "qwen3.5-397b-a17b"

Mit explizitem Modell:

./scripts/run-entire-copilot-migration.sh qt5-before/qt5-legacy-migration-benchmark gpt-5

run-entire-copilot-migration-with-optional-rewind-resume.sh

Wie das Standardskript, aber zusätzlich mit optionalem:

• entire checkpoint rewind
• entire session resume <branch>

Modellwahl: Auch dieses Skript akzeptiert optional ein Modell als zweiten Parameter.

Beispiel:

./scripts/run-entire-copilot-migration-with-optional-rewind-resume.sh qt5-before/qt5-legacy-migration-benchmark claude-sonnet-4

Wichtig:
Die Entire-Dokumentation ist bei Copilot CLI in Bezug auf Rewind/Resume nicht ganz konsistent.
Die Copilot-CLI-Seite beschreibt Rewind und Resume, während die allgemeine Agent-Übersicht teils eingeschränkte Aussagen macht.

Darum behandelt dieses Skript Rewind/Resume bewusst als optional und fehlertolerant.

use-scaleway-copilot-debug.sh

Hilfsskript zum Setzen einer Scaleway OpenAI-kompatiblen BYOK-Konfiguration für Copilot CLI.

Typischer Zweck:

• Provider-Umgebungsvariablen setzen
• Copilot CLI mit Scaleway testen
• Modellname konfigurieren
• Token-Limits für nicht im Copilot-Katalog enthaltene Modelle explizit setzen
• Debugging eines externen Providers vereinfachen

Ein typischer Inhalt wäre z. B.:

• COPILOT_PROVIDER_TYPE=openai
• COPILOT_PROVIDER_BASE_URL=https://api.scaleway.ai/v1
• COPILOT_PROVIDER_API_KEY=...
• COPILOT_MODEL=qwen3.5-397b-a17b
• COPILOT_PROVIDER_MAX_PROMPT_TOKENS=...
• COPILOT_PROVIDER_MAX_OUTPUT_TOKENS=...

---

NOTE: Secret in .envrc hinterlegen

Das Secret für den verwendeten LLM-Provider soll nicht direkt in die Skripte geschrieben oder committed werden.

Lege den API-Key stattdessen in einer lokalen .envrc ab, z. B.:

export SCW_SECRET_KEY="YOUR_PROVIDER_SECRET_HERE"

oder allgemeiner:

export OPENAI_API_KEY="YOUR_PROVIDER_SECRET_HERE"

Danach die Umgebung neu laden, z. B. mit:

direnv allow

oder die Datei manuell sourcen, falls du kein direnv verwendest.

Wichtig:

• .envrc nicht committen
• Secrets nicht im Repository speichern
• Provider-Zugangsdaten nur lokal halten

---

Empfohlene Reihenfolge

1. Legacy-Projekt erzeugen

./scripts/create-qt5-legacy-benchmark.sh

2. Optional: Copilot mit Scaleway konfigurieren

source ./scripts/use-scaleway-copilot-debug.sh

Danach kannst du prüfen, ob die Variablen gesetzt sind:

echo "$COPILOT_PROVIDER_BASE_URL"
echo "$COPILOT_MODEL"

3. Migration mit Entire + Copilot starten

Standard mit Default-Modell:

./scripts/run-entire-copilot-migration.sh qt5-before/qt5-legacy-migration-benchmark

Standard mit explizitem Modell:

./scripts/run-entire-copilot-migration.sh qt5-before/qt5-legacy-migration-benchmark qwen3.5-397b-a17b

Mit optionalem Rewind/Resume:

./scripts/run-entire-copilot-migration-with-optional-rewind-resume.sh qt5-before/qt5-legacy-migration-benchmark qwen3.5-397b-a17b

---

Copilot-Prompt für die Migration

Die Migrationsskripte verwenden sinngemäß einen Prompt in dieser Richtung:

Migrate the legacy Qt5/C++11 desktop application to Qt6/C++23.

Requirements:
- Read the legacy source project from qt5-before/qt5-legacy-migration-benchmark
- Write the migrated project into qt6-after/qt6-migrated-benchmark
- Do not modify the legacy source tree in place
- Update CMake from Qt5 to Qt6
- Keep Core, Gui, and Widgets explicitly linked
- Replace QRegExp with QRegularExpression
- Replace QDesktopWidget / QApplication::desktop() usage with QScreen-based Qt6 APIs
- Remove legacy QTextCodec usage and use modern Qt6-safe text handling
- Modernize old SIGNAL/SLOT syntax to function-pointer connect syntax
- Replace legacy null pointer literals with nullptr
- Preserve the .ui and .qrc integration
- Preserve application behavior
- Upgrade the project from C++11 to C++23
- For every code change inside a method, add at least three tests covering the changed behavior
- Place all generated tests in qt6-after/qt6-migrated-benchmark/tests
- Update CMake so the migrated application and all tests build successfully with CTest
- Keep the test file naming compatible with repository policy checks
- Briefly explain each migration change

---

Entire-Hinweise

Entire erfasst bei unterstützten Agenten u. a.:

• Gesprächsverlauf
• Dateiveränderungen
• Zeitstempel
• Checkpoints bei Commits
• Session-Kontext auf dem Branch entire/checkpoints/v1

Typischer Entire-Grundablauf:

entire agent add copilot-cli
copilot --model "qwen3.5-397b-a17b"
git add .
git commit -m "..."
entire checkpoint list

---

Hinweise zu use-scaleway-copilot-debug.sh

Das Skript sollte gesourct werden, nicht als eigener Prozess laufen, damit exportierte Variablen in deiner aktuellen Shell erhalten bleiben:

source ./scripts/use-scaleway-copilot-debug.sh

oder kurz:

. ./scripts/use-scaleway-copilot-debug.sh

Außerdem:

• keine echten Secrets committen
• API-Keys nicht im Repo speichern
• sensible Werte aus .envrc oder bereits gesetzten Umgebungsvariablen übernehmen

Beispiel:

export SCW_SECRET_KEY="..."
source ./scripts/use-scaleway-copilot-debug.sh

---

Empfohlene Erweiterungen

Optional kannst du später noch ergänzen:

• build-qt6-after.sh
• run-ctest-qt6-after.sh
• compare-before-after.sh
• capture-copilot-env.sh

---

Kurzfassung

Der scripts/-Ordner enthält alles, um:

1. ein Legacy-Qt5-Projekt zu erzeugen,
2. Copilot CLI optional mit einem externen Modell zu konfigurieren,
3. Secrets lokal über .envrc bereitzustellen,
4. eine Qt6/C++23-Migration mit Entire zu dokumentieren,
5. und den Migrationslauf reproduzierbar zu machen.