# Series

Ten dokument opisuje docelowy model komend `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

Używamy pluralnych namespace'ów `cards` i `tasks`, bo opisują kolekcje zasobów
i są spójne z pluralnym `tokens`.

## Szybki przepływ

Typowy przepływ 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 dostępne serie w workspace.

```bash
./rvctl series list
```

Przykładowy wynik:

```text
series  cards  workspace
------  -----  -------------------------------
inf     12     ~/dev/workspace/rv/series/inf
```

### `series show SERIES`

Pokazuje informacje o serii jako całości.

```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 całą serię w workspace.

```bash
./rvctl series fetch inf
```

Ta komenda pracuje na wszystkich kartach w serii. Do pobrania jednej karty
służy `series cards fetch`.

## Karty

### `series cards list SERIES`

Listuje karty w wybranej serii.

```bash
./rvctl series cards list inf
```

Przykładowy 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
tasks           task1 task2 ...
```

### `series cards fetch SERIES CARD`

Pobiera albo aktualizuje jedną kartę w workspace.

```bash
./rvctl series cards fetch inf 03
```

### `series cards submission SERIES CARD`

Pokazuje albo stosuje konfigurację 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 są częścią karty, dlatego trzymamy je pod `series cards tasks`.

### `series cards tasks list SERIES CARD`

Listuje zadania dostępne w konkretnej karcie.

```bash
./rvctl series cards tasks list inf 03
```

Przykładowy 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 są pobierane razem z
kartą przez `series cards fetch` albo razem z całą serią przez `series fetch`.

## Aliasowanie Starych Komend

Stare komendy można zostawić jako aliasy kompatybilności:

```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
```

Komendy `series cards tasks ...` nie mają starego odpowiednika i powinny być
wprowadzane tylko w nowym namespace.

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