torben
d29d400dd3
Files changed: - .gitea/workflows/release.yml - AGENTS.md - CHANGES.md - DEVELOPMENT.md - README.md - VERSION - docs/version-model.md - instructions/dev/version-parts.md - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/migrate_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/kb_state.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_migrate_cmd.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/version.py
100 lines
5.1 KiB
Markdown
100 lines
5.1 KiB
Markdown
# Entwicklung dieses Stacks
|
|
|
|
Dieses Dokument richtet sich an Menschen, die an `tools/wikitool`, dem Type-Schema oder der
|
|
Instruction-/Skill-Schicht selbst arbeiten - nicht an den Konsumenten einer Instanz. Für die
|
|
Gegenseite (eine Instanz installieren, aktualisieren, betreiben) siehe [INSTALL.md](INSTALL.md).
|
|
|
|
**Diese Datei wird nicht ausgeliefert.** Sie ist das menschliche Gegenstück zu
|
|
`instructions/dev/`, das `tools/wikitool dist export` vollständig ausschließt: eine
|
|
ausgelieferte Instanz hat keinen Release-Workflow, keine CI und kein Issue-Board, also braucht
|
|
sie auch keine Anleitung dafür. `dist_cmd.ROOT_FILES` listet sie deshalb bewusst nicht - der
|
|
Grund steht dort als Kommentar, damit eine spätere Sitzung die vermeintliche Lücke nicht
|
|
"repariert". Und weil sie nicht ausgeliefert wird, darf sie - anders als `README.md`,
|
|
`INSTALL.md` oder `EVALS.md`, die `instructions verify` auf genau diesen Punkt prüft - nach
|
|
`instructions/dev/` verlinken.
|
|
|
|
## Der Release-Ablauf
|
|
|
|
Zwischen zwei Releases führt der Stack **einen** laufenden Versionskandidaten statt einer neuen
|
|
Nummer pro Bump. Das volle Modell - Zustandsort, Eskalationslogik, warum eine Nummer erst durch
|
|
ein Release verbraucht wird - steht in
|
|
[instructions/dev/version-parts.md](instructions/dev/version-parts.md) und
|
|
[docs/version-model.md](docs/version-model.md). Hier nur der Ablauf, in der Reihenfolge, in der
|
|
eine Sitzung ihn tatsächlich durchläuft:
|
|
|
|
1. **Bump eröffnet oder eskaliert den Kandidaten.**
|
|
|
|
```bash
|
|
tools/wikitool version bump --minor --title "Was sich geändert hat"
|
|
```
|
|
|
|
Schreibt `VERSION` als `X.Y.Z-beta.N` und öffnet (oder aktualisiert) den passenden
|
|
`CHANGES.md`-Eintrag. Mehrere Bumps für dieselbe Änderung sind normal - jeder aktualisiert
|
|
denselben Eintrag, statt einen neuen zu eröffnen.
|
|
|
|
2. **Der Eintrag bekommt seine Prosa.** `bump` schreibt nur das Skelett (Heading, Datum, Autor,
|
|
die maschinenverwaltete Bump-Titel-Liste, ggf. Breaking-/Migration-Zeile). Der Fließtext
|
|
darunter ist Autorenarbeit, wie bei `new` und der Seiten-Prosa.
|
|
|
|
3. **Verify laufen lassen, bevor irgendetwas gepublished wird:**
|
|
|
|
```bash
|
|
cd tools && .venv/bin/python -m pytest -q
|
|
tools/wikitool docs verify
|
|
tools/wikitool instructions verify
|
|
```
|
|
|
|
4. **`version release` fixiert den Kandidaten**, sobald er ausgeliefert werden soll:
|
|
|
|
```bash
|
|
tools/wikitool version release --title "Zusammenfassender Titel"
|
|
```
|
|
|
|
Streicht den `-beta.N`-Suffix aus `VERSION` und schließt den Changelog-Eintrag. `--title` ist
|
|
optional - ohne ihn bleibt der Titel des letzten Bumps stehen; mit ihm bekommt ein Kandidat,
|
|
der mehrere Bump-Titel gesammelt hat, eine zusammenfassende Überschrift. Committet und pusht
|
|
nichts (Invariante 5 in [AGENTS.md](AGENTS.md)).
|
|
|
|
5. **Publish bewegt `VERSION` auf `main`.**
|
|
|
|
```bash
|
|
tools/wikitool publish --message "..."
|
|
```
|
|
|
|
Das Mass-Update-Gate und das Publish-Remote-Gate gelten wie bei jedem anderen Publish -
|
|
siehe [instructions/gates.md](instructions/gates.md).
|
|
|
|
6. **CI übernimmt den Rest.** `.gitea/workflows/release.yml` reagiert auf jeden Push, der
|
|
`VERSION` bewegt: Eine suffixbehaftete `VERSION` (ein Kandidat) lässt den Job sauber
|
|
überspringen, bevor er die Releases-API überhaupt anfragt - Betas werden nie veröffentlicht.
|
|
Eine suffixfreie `VERSION` baut die Distribution (`dist export`), erzeugt Tag und Release und
|
|
lädt Tarball plus Prüfsumme hoch. **CI setzt den Tag, nie eine Sitzung** - das hält
|
|
Invariante 5 intakt.
|
|
|
|
## Verify-Befehle im Überblick
|
|
|
|
| Befehl | Prüft |
|
|
|---|---|
|
|
| `cd tools && .venv/bin/python -m pytest -q` | Die gesamte Testsuite, hermetisch gegen eine leere Maschine (siehe `instructions/dev/testing-conventions.md`) |
|
|
| `tools/wikitool docs verify` | CLI-Kommandotabelle, Contract-Präsenz, Type-Drift, `.gitignore`-Kanarienvögel, `VERSION`/`CHANGES.md`-Übereinstimmung, Grenzübertritts-Dokumentation |
|
|
| `tools/wikitool instructions verify` | Jede Instruction und jeder Skill unter `instructions/`, verwaiste Dateien, `instructions/dev/`-Referenzen von außerhalb |
|
|
|
|
Die volle Kommandoreferenz inklusive Fehlerkontrakt: [tools/CONTRACT.md](tools/CONTRACT.md).
|
|
|
|
## Die CI-Hälfte
|
|
|
|
`.gitea/workflows/ci.yml` läuft auf jeden Push/PR gegen `main` (Content-Pfade ausgenommen) und
|
|
führt Testsuite, `docs verify`, `instructions verify` sowie einen vollständigen
|
|
`setup-instance.md`-Replay gegen einen frischen `dist export` aus - derselbe Pfad, den ein neuer
|
|
Nutzer tatsächlich geht. `.gitea/workflows/nightly.yml` ist der Drift-Check gegen die Zeit statt
|
|
gegen einen Commit. `.gitea/workflows/release.yml` ist Schritt 6 oben.
|
|
|
|
## Stack-Entwicklung als eigener Sitzungstyp
|
|
|
|
Der `stack-dev`-Skill (`instructions/dev/`, nur in diesem Ursprungs-Repo vorhanden) fasst die
|
|
Regeln für eine Sitzung, die den Stack selbst statt Wiki-Inhalt bearbeitet: wann
|
|
Quellenbindung nicht gilt, wo Design endet und die mechanische Phase beginnt (mit dem
|
|
Modellwechsel-Hinweis), und dass Issue-Abschluss ein Body-Rewrite ist, kein Kommentar. Siehe
|
|
[instructions/dev/issue-tracking.md](instructions/dev/issue-tracking.md) für den
|
|
Issue-Tracker selbst.
|