Files

T

AndreasTharangandClaude Sonnet 5 ab416fb34c Projektwissen: Git-Vorgaben, Ticketzugriff, Tests und Einstieg

Erster Stand des Repositories AG_QGIS/Projektwissen (bisher Arbeitstitel
"Workspace", ADR 0006). Der lokale Ordner heisst weiter AG_QGIS, weil darin
auch die Plugin-Klone liegen.

Git verbindlich (ADR 0007), aus dem bisherigen Wiki-Konzept entwickelt:
- docs/leitfaden/05_git_arbeitsweise.md mit Kanal-Kette, Branch-Namen und
  Gitea-Branch-Schutz.
- Der Einstiegspunkt eines Fixes richtet sich nach dem Kanal, in dem der
  Fehler sitzt; ein Fix an testing oder stable ist erst mit der
  Rueckfuehrung nach unten abgeschlossen. Das fehlte bisher.
- Der stabile Kanal heisst stable, nicht main: der Release-Workflow in
  Repository:hidden/workflows fuehrt git checkout "$CHANNEL" aus, der
  Branchname muss also dem Kanalnamen entsprechen. Er existiert in keinem
  Plugin-Repo und ist vom Maintainer anzulegen.
- Der Mensch drueckt ab: .claude/settings.json sperrt push, merge, tag.
- scripts/hallo.py und /hallo holen den Stand aller Klone, per
  Fast-Forward wo gefahrlos; nie mergen, stashen oder verwerfen.

Ticketzugriff:
- scripts/gitea.py liest Issues, Kommentare und PRs ueber die oeffentliche
  API, ohne Token, nur GET. Schreibendes nur als Entwurf in entwuerfe/.
- Skill sn-ticket.

Tests (ADR 0009):
- docs/leitfaden/06_tests.md: Testebenen, Testpflicht, und wie eine
  Fachperson beurteilt, ob Tests fachlich sinnvoll sind.
- scripts/testkatalog.py erzeugt docs/tests/testkatalog.md per ast-Parsing,
  ohne Import und ohne QGIS. Befund: nur 100 von 332 Tests haben einen
  Docstring, sn_basis keinen einzigen von 87.
- Vorlage und erste Testkonzept-Seite mit Mermaid. Dabei gefunden und gegen
  origin geprueft: _ermittle_gebietstyp_aus_fbschl hat keinen Test, obwohl
  PR #44/#45 genau diese Funktion tolerant gemacht hat.
- docs/konzept/07_qgis_tests_plan.md: Stufenplan fuer Tests gegen echtes
  QGIS. Dabei aufgefallen: QGIS 3.40 ist seit Januar 2026 End of Life,
  qgis_min steht aber noch darauf.

Werkzeuge (ADR 0008):
- 04_werkzeuge_einrichten.md nur noch Claude Code als CLI und in VS Code.
- .vscode/ entfernt, brauchbare Einstellungen als persoenliche Vorlage.

Ausserdem: README als Einstieg neu aufgebaut, Mermaid-Diagramm in
schnittstellen.md repariert (unmaskierte Klammern, rendert seither nicht).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-09-04 11:57:26 +02:00

3.0 KiB

Raw Blame History

0009 – Tests sind Teil der Definition of Done, und sie werden für Menschen dokumentiert

Status: vorgeschlagen · Datum: 2026-09-04 · Beteiligte: AG QGIS · Ergänzt 0003

Kontext

Entscheidung 0003 machte den Baseline-Lauf vor jedem Pull Request zur Pflicht. Sie verhindert Rückschritte, verlangt aber keine neuen Tests. Bei überwiegend KI-erzeugtem Code ist das zu wenig: Ein Agent kann überzeugend erklären, dass etwas funktioniert, ohne dass es funktioniert.

Der am 04.09.2026 erstmals erzeugte Testkatalog zeigt dazu einen zweiten Befund: Von 332 Testfällen haben nur 100 (30 %) eine Beschreibung — sn_basis null von 87, sn_plan41 einen von 44. Ohne Beschreibung ist von außen nicht erkennbar, was ein Test prüft. Damit kann niemand beurteilen, ob die Abdeckung fachlich sinnvoll ist, und genau das ist bei einer Fachanwendung die entscheidende Frage. Ein grüner Testlauf, dessen Inhalt niemand kennt, ist ein Gefühl, kein Nachweis.

Entscheidung

Neue Funktionalität ohne Test wird nicht gemergt. Mindestens ein Test je neuem beobachtbarem Verhalten. Bei einer Fehlerbehebung zuerst der Test, der den Fehler zeigt.
Jeder Test hat einen deutschen Docstring, dessen erste Zeile mit Prüft, dass … beginnt. Diese Zeile ist für die meisten Leser der einzige Kontakt mit dem Test.
Der Testkatalog wird erzeugt, nicht gepflegt. scripts/testkatalog.py liest die Testdateien per ast (ohne Import, ohne QGIS, ohne Abhängigkeiten) und schreibt docs/tests/testkatalog.md. Er wird mitcommittet; --pruefen meldet, wenn er veraltet ist.
Fachlich wichtige Abläufe bekommen eine Testkonzept-Seite in docs/tests/ nach docs/vorlagen/testkonzept.md: ein Mermaid-Diagramm des fachlichen Ablaufs, eine Tabelle Schritt → deckender Test → bewusst nicht getestet mit Begründung, und die bekannten Lücken. Damit kann eine Fachperson ohne Programmierkenntnisse prüfen, ob die Tests das Richtige prüfen.

Die Docstring-Pflicht gilt für neue und geänderte Tests. Die 232 bestehenden Tests ohne Beschreibung werden nicht auf einen Schlag nachgezogen; der Abschnitt „Lücken" des Katalogs ist die Arbeitsliste, die nebenbei abgearbeitet wird.

Folgen

Pull Requests werden etwas größer und etwas langsamer. Dafür wird zum ersten Mal überprüfbar, ob die Testsuite fachlich das Richtige abdeckt — bisher war nur bekannt, wie viele Tests grün sind. Der Katalog macht Lücken sichtbar, statt sie in Testdateien zu verstecken. Die Testkonzept-Seiten sind zusätzlicher Pflegeaufwand und lohnen nur für Abläufe, die fachlich wirklich wichtig sind — nicht für jede Funktion.

Verworfene Alternativen

Nur den generierten Katalog (zeigt was getestet wird, aber nicht ob es genügt — genau die Prüfung, um die es geht, fiele weg); nur handgeschriebene Testkonzepte (laufen dem Code hinterher, dieselbe Drift, die die Wissensbasis sonst vermeidet); Testabdeckung in Prozent als Ziel (misst durchlaufene Zeilen, nicht fachliche Vollständigkeit, und verleitet zu Tests ohne Aussage).

3.0 KiB Raw Blame History Unescape Escape