stem-launcher/doc/migration-stem-launcher.md

Migracja rv-launcher do stem-launcher

Status: M1–M3 wdrożone lokalnie; M4 (zmiana nazwy zdalnego repo) celowo odłożone do zakończenia okresu zgodności Data: 2026-07-14

Dlaczego zmieniamy nazwę

Launcher obsługuje już kod natywny AMD64 i Hazard3, a plan obejmuje RP2350 RISC-V, RP2350 ARM, fizykę i kolejne serie STEM. Nazwy rv-launcher, rvctl, RV_* i ~/dev/workspace/rv błędnie sugerują narzędzie ograniczone do RISC-V.

Docelowy słownik:

Obecnie	Docelowo
rv-launcher	stem-launcher
rvctl	stemctl
rvctl.py	wewnętrzny moduł launchera; nazwa nie jest publicznym API
RV_*	STEM_*
.rv/	.stem/
~/dev/workspace/rv	~/dev/workspace/stem
profil host	native-amd64
profil rv32i	hazard3-sim

Zasada migracji

Najpierw dostarczamy zgodność w kodzie, a dopiero później zmieniamy nazwę repo na serwerze. Odwrotna kolejność zepsułaby bootstrap, token records, remotes, ścieżki dokumentacji i istniejące workspace uczniów.

Etapy

M1 — alias CLI (wdrożone)

• dodać wykonywalny stemctl wskazujący tę samą implementację;
• pozostawić rvctl jako wrapper;
• pomoc i nowe materiały pokazują wyłącznie stemctl;
• rvctl drukuje jednorazowe ostrzeżenie o wycofaniu na stderr, ale zachowuje format stdout potrzebny skryptom.

M2 — konfiguracja i ścieżki (wdrożone)

• dodać wersjonowaną migrację workspace.json;
• nowe zmienne STEM_* mają pierwszeństwo, stare RV_* są fallbackiem;
• jeśli istnieje /workspace/.stem, użyć go;
• jeśli istnieje tylko /workspace/.rv, użyć go i zaproponować migrację;
• komenda stemctl workspace doctor pokazuje użyte ścieżki i runtime;
• komenda stemctl workspace migrate --dry-run nie zmienia danych, tylko pokazuje plan.

Migracja katalogu stanu musi być atomowa na pojedynczym filesystemie i nigdy nie usuwa starego katalogu przed zweryfikowaniem nowego.

M3 — profile i kontenery (wdrożone)

• wprowadzić native-amd64, hazard3-sim, rp2350;
• zachować aliasy host -> native-amd64 oraz rv32i -> hazard3-sim;
• kontenery otrzymują labels z nazwą kanoniczną, nie aliasem;
• wyniki zapisują nazwę kanoniczną oraz opcjonalne requested_alias.

M4 — repo Gitea (odłożone)

Po wydaniu kompatybilnego launchera:

1. utworzyć lub zmienić nazwę na edu-tools/stem-launcher;
2. zaktualizować workspace-info, bootstrap i token records;
3. sprawdzić clone/fetch/push przez nowe URL;
4. pozostawić pod edu-tools/rv-launcher przekierowanie albo małe repo z komunikatem migracyjnym, zależnie od możliwości Gitea;
5. nie usuwać starej nazwy podczas trwającego semestru.

Zmiana repo na Gitea jest operacją administracyjną i nie jest wykonywana przez samą aktualizację dokumentacji.

M5 — wycofanie kompatybilności

Stare nazwy można usunąć dopiero, gdy:

• wszystkie serie w workspace-info wskazują nowe CLI i repo;
• CI nie używa rvctl, RV_*, .rv ani profili host/rv32i;
• obraz pracowni został odświeżony;
• co najmniej jeden pełny cykl zajęć przeszedł na stemctl;
• dostępna jest instrukcja ręcznego odzyskania starego workspace.

Testy migracji

1. Nowa instalacja bez istniejącego workspace.
2. Istniejący workspace /rv z kartami i bez aktywnych kontenerów.
3. Workspace z .rv/<instance> i zatrzymanym kontenerem.
4. Store tokenów wskazujący repo rv-launcher.
5. Remotes bez sekretu oraz remotes z historycznym tokenem w URL.
6. Równoległe instancje profili host i rv32i.
7. Ponowne wykonanie migracji — wynik musi być idempotentny.
8. Rollback konfiguracji bez utraty repo, branchy, artefaktów i logów.

Kryterium zakończenia

Uczeń po migracji wykonuje:

stemctl series cards fetch inf bss
stemctl test native-amd64 inf bss 1
stemctl debug hazard3-sim inf bss 1
stemctl deploy rp2350 inf bss 1 --target rp2350-rv --device /dev/bus/usb/001/006

Istniejący skrypt używający rvctl debug rv32i nadal działa w zadeklarowanym okresie kompatybilności i trafia do tego samego kanonicznego profilu.