uttrflow / uttrflow/uttrflow-swift

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

Offen Anfängerfreundlich
#653 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area:general documentation good first issue P2
Vorherrschende Sprache
Swift
Sterne
4
Forks
17
Ø Merge
4 Std. 27 Min.
Gemergte PRs (30 T.)
286

Beschreibung

## 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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Lies CONTRIBUTING.md zuerst, untersuche dann Docs/README.md und Abschnitt 3 von Scripts/docs_audit.sh, das bereits relative Links analysiert. Füge die beiden Dokumentlinks und die fehlende Index-Abdeckungsprüfung hinzu, führe dann make docs-audit und make verify aus; fertig ist es, wenn beide Dateien indexiert sind und das Entfernen einer Indexzeile dazu führt, dass das Audit fehlschlägt und diese Datei nennt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
markdown, shell
Bereich
build-system, documentation
Issue-Typ
Dokumentation
Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Aktivitätsstatus
Aktiv
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
88/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.