uttrflow / uttrflow/uttrflow-swift

Docs/README.md does not list soak.md or ui-tests.md, and no document links to either

Aperta Adatta ai principianti
#653 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
area:general documentation good first issue P2
Lingua principale
Swift
Stelle
4
Fork
17
Merge medio
3h 32m
PR unite (30g)
277

Descrizione

## What happens

`Docs/README.md` indexes 88 of the 90 files in `Docs/`. The two it leaves out, `Docs/soak.md` (how to run `make soak`) and `Docs/ui-tests.md` (how to run `make uitest`), are not linked from any other Markdown file in the repository (`git grep -l 'soak.md\|ui-tests.md' -- '*.md'` finds nothing), so the only way to find them is to list the directory.

`Scripts/docs_audit.sh` checks that links resolve, but not that every document is reachable from the index.

## Why it matters

`make soak` and `make uitest` are in `make help`, and these are the pages that explain what they need (hours of running, a windowing session) before somebody starts one.

## Acceptance criteria

- Both documents are listed in `Docs/README.md` under a fitting heading.
- `Scripts/docs_audit.sh` gains a check that every `Docs/*.md` other than `Docs/README.md` is linked from `Docs/README.md`, and fails naming the file when one is not.
- `make docs-audit` passes; say in the pull request that removing one of the new index lines makes it fail.

## Where to start

- `Docs/README.md`, `Scripts/docs_audit.sh` section 3 (relative links), which already parses links.
- Read [CONTRIBUTING.md](https://github.com/uttrflow/uttrflow-swift/blob/main/CONTRIBUTING.md) first, and say on this issue that you are taking it.
- Before pushing, run `make verify` (with `DEVELOPER_DIR` pointing at Xcode 26.6 or later). It is the same command CI runs.

**Size:** S, about 1 hour.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Leggi prima CONTRIBUTING.md, poi esamina Docs/README.md e la sezione 3 di Scripts/docs_audit.sh, che analizza già i link relativi. Aggiungi i due link ai documenti e il controllo mancante della copertura dell’indice, quindi esegui make docs-audit e make verify; il lavoro è completato quando entrambi i file sono indicizzati e la rimozione di una riga dell’indice fa fallire l’audit indicando quel file.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
markdown, shell
Ambito
build-system, documentation
Tipo di issue
Documentazione
Difficoltà
2/5
Tempo stimato
1-3 ore
Stato di attività
Attiva
Chiarezza
Specificata chiaramente
Idoneità per principianti
88/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.