258 lines
6.4 KiB
Markdown
258 lines
6.4 KiB
Markdown
# 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
|
|
|
|
```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/<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:
|
|
|
|
```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`.
|