Document series command namespace

doc/series.md

@@ -0,0 +1,190 @@
+# Series
+
+Ten dokument opisuje docelowy model komend `rvctl` do pracy z seriami i
+kartami pracy.
+
+## Zasada
+
+Komendy kart pracy dzielimy na dwa poziomy:
+
+- `series` - operacje na serii jako calosci
+- `series cards` - operacje na kartach w ramach serii
+
+Uzywamy `cards`, a nie `card`, bo namespace opisuje kolekcje kart i jest
+spojny z pluralnym `tokens`.
+
+## Szybki Flow
+
+Typowy przeplyw pracy:
+
+```bash
+./rvctl tokens compare
+./rvctl series list
+./rvctl series show inf
+./rvctl series fetch inf
+./rvctl series cards list inf
+./rvctl series cards show inf 03
+./rvctl series cards tasks list inf 03
+./rvctl series cards tasks show inf 03 task1
+./rvctl series cards fetch inf 03
+./rvctl series cards submission inf 03 --class 4i --nick u1
+```
+
+## Serie
+
+### `series list`
+
+Listuje dostepne serie w workspace.
+
+```bash
+./rvctl series list
+```
+
+Przykladowy wynik:
+
+```text
+series  cards  workspace
+------  -----  -------------------------------
+inf     12     ~/dev/workspace/rv/series/inf
+```
+
+### `series show SERIES`
+
+Pokazuje informacje o serii jako calosci.
+
+```bash
+./rvctl series show inf
+```
+
+Typowe pola:
+
+```text
+series          inf
+workspace_path  ~/dev/workspace/rv/series/inf
+source_path     ~/dev/edu/repos/rv/series/inf
+cards_count     12
+cards           01 02 03 ...
+```
+
+### `series fetch SERIES`
+
+Pobiera albo aktualizuje cala serie w workspace.
+
+```bash
+./rvctl series fetch inf
+```
+
+Ta komenda pracuje na wszystkich kartach w serii. Do pobrania jednej karty
+sluzy `series cards fetch`.
+
+## Karty
+
+### `series cards list SERIES`
+
+Listuje karty w wybranej serii.
+
+```bash
+./rvctl series cards list inf
+```
+
+Przykladowy wynik:
+
+```text
+series  card  repo
+------  ----  ------------------------------------
+inf     03    lab-rv32i-strlen-bss-data-stack
+```
+
+### `series cards show SERIES CARD`
+
+Pokazuje informacje o konkretnej karcie.
+
+```bash
+./rvctl series cards show inf 03
+```
+
+Typowe pola:
+
+```text
+series          inf
+card            03
+workspace_path  ~/dev/workspace/rv/series/inf/03
+source_path     ~/dev/edu/repos/rv/series/inf/03
+source_repo     edu-inf/lab-rv32i-strlen-bss-data-stack
+source_remote   r1
+answer_remote   a1
+```
+
+### `series cards fetch SERIES CARD`
+
+Pobiera albo aktualizuje jedna karte w workspace.
+
+```bash
+./rvctl series cards fetch inf 03
+```
+
+### `series cards submission SERIES CARD`
+
+Pokazuje albo stosuje konfiguracje repo odpowiedzi dla karty.
+
+```bash
+./rvctl series cards submission inf 03 --class 4i --nick u1
+./rvctl series cards submission inf 03 --class 4i --nick u1 --apply
+```
+
+Bez `--apply` komenda tylko pokazuje plan. Z `--apply` ustawia remotes potrzebne
+do pracy z repo odpowiedzi.
+
+## Zadania W Karcie
+
+Zadania sa czescia karty, dlatego trzymamy je pod `series cards tasks`.
+
+### `series cards tasks list SERIES CARD`
+
+Listuje zadania dostepne w konkretnej karcie.
+
+```bash
+./rvctl series cards tasks list inf 03
+```
+
+Przykladowy wynik:
+
+```text
+series  card  task   path
+------  ----  -----  --------------------------------------
+inf     03    task1  ~/dev/workspace/rv/series/inf/03/task1
+inf     03    task2  ~/dev/workspace/rv/series/inf/03/task2
+```
+
+### `series cards tasks show SERIES CARD TASK`
+
+Pokazuje informacje o konkretnym zadaniu w karcie.
+
+```bash
+./rvctl series cards tasks show inf 03 task1
+```
+
+Typowe pola:
+
+```text
+series          inf
+card            03
+task            task1
+workspace_path  ~/dev/workspace/rv/series/inf/03/task1
+card_path       ~/dev/workspace/rv/series/inf/03
+```
+
+Na tym poziomie nie wprowadzamy osobnego `fetch`: zadania sa pobierane razem z
+karta przez `series cards fetch` albo razem z cala seria przez `series fetch`.
+
+## Aliasowanie Starych Komend
+
+Stare komendy mozna zostawic jako aliasy kompatybilnosci:
+
+```text
+list-series                         -> series list
+list-cards inf                      -> series cards list inf
+submission inf 03 --class K --nick N -> series cards submission inf 03 --class K --nick N
+```
+
+Dokumentacja i nowe przyklady powinny promowac namespace `series`.