mpabi
110 lines
4.1 KiB
Markdown
110 lines
4.1 KiB
Markdown
# 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.
|