feat: add three-profile STEM container workflow

2026-07-14 17:49:36 +02:00
parent 9c0b833371
commit 61d00a6992
12 changed files with 1819 additions and 882 deletions
@@ -0,0 +1,109 @@
+# 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:
+
+```bash
+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.