stem-launcher/doc/series.md

Series

Ten dokument opisuje komendy rvctl do pracy z seriami, kartami pracy i zadaniami w kartach.

Zasada

Komendy kart pracy dzielimy na trzy poziomy:

• series - operacje na serii jako całości
• series cards - operacje na kartach w ramach serii
• series cards tasks - operacje na zadaniach w ramach karty

stemctl tworzy series_root, jeżeli katalog jeszcze nie istnieje. Gdy workspace-info jest dostępny, manifest jest jedynym źródłem listy serii i kart. Przypadkowe katalogi robocze nie pojawiają się w katalogu. Fallback przez original_series_root działa wyłącznie dla starego workspace bez manifestu.

Każda operacyjna seria jawnie deklaruje source_org. Docelowa konwencja to edu-<series-id>, na przykład freertos-c → edu-freertos-c. Jedno repo odpowiada jednej karcie; kolejnych wydań karty nie zapisujemy jako osobnych repozytoriów ani trwałych branchy, tylko jako historię, tagi i wydania tego repozytorium. Organizacja edu przechowuje control plane i katalog, nie setki repozytoriów kart.

Szybki przepływ

./stemctl workspace audit
./stemctl tokens compare
./stemctl series list
./stemctl series use freertos-c
./stemctl series cards list freertos-c
./stemctl card use FC02
./stemctl series cards fetch freertos-c FC02
./stemctl tasks list
./stemctl tasks switch 1

Dla karty bss właściwym repo jest lab-rv32i-strlen-bss-data-stack.

Serie

series list

Listuje wyłącznie operacyjne serie z manifestu workspace-info oraz liczbę kart już obecnych w lokalnym workspace. Logiczna seria może wskazywać wspólny, przejściowy katalog fizyczny przez workspace_dir; na przykład freertos-c jest obecnie mapowane na series/freertos.

./rvctl series list

Typowy wynik:

fiz         3   0
inf         9   5
freertos-c  11  11

Kolumny oznaczają: seria, liczba kart w źródłach, liczba kart pobranych do workspace.

series show SERIES

Pokazuje informacje o serii.

./rvctl series show inf

series use SERIES

Ustawia domyślną serię w workspace.json. Po tej komendzie skróty kart i zadań mogą korzystać z tej serii bez podawania jej za każdym razem.

./rvctl series use inf

Karty

series cards list SERIES

Listuje karty w wybranej serii.

./rvctl series cards list inf

Przykładowy wynik:

bss  lab-rv32i-strlen-bss-data-stack  source  rv32i-c / bss-data-stack

Pierwsza kolumna jest krótką nazwą karty. Pełna nazwa repo zostaje w drugiej kolumnie.

card use CARD

Ustawia domyślną kartę w aktualnie domyślnej serii. Dla serii inf:

./rvctl card use bss

Komenda zapisuje defaults.card w workspace.json.

card use SERIES CARD

Ustawia jednocześnie domyślną serię i domyślną kartę:

./rvctl card use inf bss

To jest odpowiednik:

./rvctl series use inf
./rvctl card use bss

series cards fetch SERIES CARD

Pobiera albo aktualizuje jedną kartę w workspace. CARD może być krótką nazwą albo unikalnym fragmentem pełnej nazwy repo.

./rvctl series cards fetch inf bss

Karta trafia do:

~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack

Po pobraniu rvctl przygotowuje remotes:

• r1 - repo źródłowe karty w edu-inf
• r1a - repo pracy w c2025-1a-inf

Remote r1a jest tworzony z tokena r1 i wskazuje na repo o tej samej nazwie co karta:

http://77.90.8.171:3001/c2025-1a-inf/lab-rv32i-strlen-bss-data-stack.git

series cards show SERIES CARD

Pokazuje informacje o karcie.

./rvctl series cards show inf bss

series cards submission SERIES CARD

Pokazuje albo stosuje konfigurację repo odpowiedzi dla karty.

./rvctl series cards submission inf bss --class c2025-1a-inf
./rvctl series cards submission inf bss --class c2025-1a-inf --task 4 --apply

Bez --apply komenda pokazuje plan. Z --apply ustawia remotes potrzebne do pracy z repo odpowiedzi. Jeżeli nie podasz --branch, branch jest liczony ze store tokenów i zadania, na przykład u1T1a.

Zadania w karcie

Zadania są częścią karty, dlatego trzymamy je pod series cards tasks. Do codziennej pracy z domyślną kartą można używać krótszego namespace tasks.

series cards tasks list SERIES CARD

Listuje zadania dostępne w konkretnej karcie. rvctl rozpoznaje zadania zapisane jako pliki lub katalogi task* w src/tasks, a także katalogi task* bezpośrednio w korzeniu karty.

./rvctl series cards tasks list inf bss

Skrót dla domyślnej karty:

./rvctl tasks list

Przykładowy wynik:

inf  bss  task1_bss           ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/src/tasks/task1_bss.c
inf  bss  task2_data          ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/src/tasks/task2_data.c
inf  bss  task3_stack_unused  ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/src/tasks/task3_stack_unused.c
inf  bss  task4_stack_strlen  ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/src/tasks/task4_stack_strlen.c

series cards tasks show SERIES CARD TASK

Pokazuje informacje o konkretnym zadaniu w karcie.

./rvctl series cards tasks show inf bss task1

Skrót dla domyślnej karty:

./rvctl tasks show 1

series cards tasks switch SERIES CARD TASK

Tworzy albo przełącza lokalny branch pracy dla wybranego zadania.

./rvctl series cards tasks switch inf bss 4

Skrót dla domyślnej karty:

./rvctl tasks switch 4

Nazwa brancha jest liczona automatycznie z użytkownika w tokens.json i numeru zadania. Dla użytkownika u1 i zadania task4_stack_strlen powstanie:

u1T4a

Jeżeli branch już istnieje, rvctl przełącza na niego repo. Jeżeli go nie ma, tworzy go od aktualnego commita karty. Branch dostaje upstream r1a/<branch>, na przykład r1a/u1T4a.

Na tym poziomie nie wprowadzamy osobnego fetch: zadania są pobierane razem z kartą przez series cards fetch albo razem z całą serią przez series fetch.

Aliasowanie Starych Komend

Stare komendy zostają jako aliasy kompatybilności:

list-series                         -> series list
list-cards inf                      -> series cards list inf
submission inf bss --class K        -> series cards submission inf bss --class K

Dokumentacja i nowe przykłady powinny promować namespace series.