torben
1b0158fc8d
Files changed: - CHANGES.md - DEVELOPMENT.md - VERSION - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/commands/run_budget.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_run_budget.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/version.py
108 lines
6.0 KiB
Markdown
108 lines
6.0 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, gewichtet mit `--impact`.**
|
|
|
|
```bash
|
|
tools/wikitool version bump --minor --title "Was sich geändert hat" --impact medium
|
|
```
|
|
|
|
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. `--impact high|medium|low` (Default
|
|
`medium`) gruppiert den Eintrag; `tools/wikitool version regrade` korrigiert eine Note später,
|
|
wenn der Gesamteindruck des Kandidaten den Blick auf einen früheren Bump ändert.
|
|
|
|
2. **Der Eintrag bekommt seine Prosa - zweigeteilt.** `bump` schreibt nur das Skelett (Heading,
|
|
Datum, Autor, die maschinenverwaltete, gruppierte Bump-Titel-Liste, ggf.
|
|
Breaking-/Migration-Zeile). Darunter kommen zwei Autorenanteile: eine kurze Zusammenfassung
|
|
(ein paar Sätze, worum es in diesem Release geht) direkt unter der Liste, und darunter je Bump
|
|
ein eigener `### <Bump-Titel>`-Changeset-Absatz. Details dazu in
|
|
[instructions/dev/version-parts.md](instructions/dev/version-parts.md) § The candidate model.
|
|
|
|
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. Verweigert, wenn der
|
|
Kandidat zwei oder mehr Bumps gesammelt hat und die Zusammenfassung aus Schritt 2 noch fehlt -
|
|
ein Kandidat mit genau einem Bump ist davon ausgenommen. 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.
|
|
|
|
Die drei Verify-Befehle stehen oben in Schritt 3; was jeder von ihnen prüft, steht in
|
|
[tools/CONTRACT.md](tools/CONTRACT.md) und wird dort von `docs verify` gegen die tatsächliche
|
|
CLI gehalten. Hier steht es bewusst **nicht** noch einmal: eine zweite Beschreibung derselben
|
|
Befehle ist genau die Kopie, die driftet (AGENTS.md Invariante 8), und dieses Dokument liegt
|
|
außerhalb der Dateien, die der Kommandotabellen-Check von `docs verify` abdeckt - hier fällt eine
|
|
Drift also niemandem auf. Was `pytest` an dieser Stelle vom Entwickler erwartet, steht in
|
|
[instructions/dev/testing-conventions.md](instructions/dev/testing-conventions.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 endet mit dem Publish. Die Schlussphase - Issue-Body als Rewrite
|
|
statt Kommentar, `docs/`-Veralterung, die Modell-Handover-Zeile über die ganze Sitzung - liegt
|
|
seit `4.6.0` in einem eigenen Folge-Skill, `stack-close`, den `stack-dev` an dieser Stelle
|
|
übergibt statt sie als weiteren eigenen Schritt zu führen. Siehe
|
|
[instructions/dev/issue-tracking.md](instructions/dev/issue-tracking.md) für den
|
|
Issue-Tracker selbst.
|