# 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-`, 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 ```bash ./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`. ```bash ./rvctl series list ``` Typowy wynik: ```text 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. ```bash ./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. ```bash ./rvctl series use inf ``` ## Karty ### `series cards list SERIES` Listuje karty w wybranej serii. ```bash ./rvctl series cards list inf ``` Przykładowy wynik: ```text 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`: ```bash ./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ę: ```bash ./rvctl card use inf bss ``` To jest odpowiednik: ```bash ./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. ```bash ./rvctl series cards fetch inf bss ``` Karta trafia do: ```text ~/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: ```text 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. ```bash ./rvctl series cards show inf bss ``` ### `series cards submission SERIES CARD` Pokazuje albo stosuje konfigurację repo odpowiedzi dla karty. ```bash ./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. ```bash ./rvctl series cards tasks list inf bss ``` Skrót dla domyślnej karty: ```bash ./rvctl tasks list ``` Przykładowy wynik: ```text 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. ```bash ./rvctl series cards tasks show inf bss task1 ``` Skrót dla domyślnej karty: ```bash ./rvctl tasks show 1 ``` ### `series cards tasks switch SERIES CARD TASK` Tworzy albo przełącza lokalny branch pracy dla wybranego zadania. ```bash ./rvctl series cards tasks switch inf bss 4 ``` Skrót dla domyślnej karty: ```bash ./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: ```text 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/`, 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: ```text 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`.