docs: Migrationsdokument haelt das Vorher fest und verweist auf die .template-Form, Rest-Abschnitt aus types/source.md entfernt (#107)
Files changed: - CHANGES.md - VERSION - instructions/migrate-corpus.md - instructions/migrations/6.0.0-type-guidance-split.md - types/source.md
This commit is contained in:
+53
-1
@@ -59,12 +59,13 @@ concern - readable here, never shipped as something to parse.
|
||||
|
||||
---
|
||||
|
||||
## 6.1.0-beta.1 - 2026-09-16 - Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
|
||||
## 6.1.0-beta.2 - 2026-09-16 - Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
<!-- wikitool:bumps -->
|
||||
- Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
|
||||
- Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form
|
||||
<!-- /wikitool:bumps -->
|
||||
|
||||
### Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
|
||||
@@ -121,6 +122,57 @@ Kein Grenzuebertritt: eine neue Instruktionsdatei und ein geaenderter Meldungste
|
||||
Richtungen ein Drop-in. Eine Instanz, die zurueckgeht, behaelt die Datei als ueberzaehlige Datei,
|
||||
und nichts liest sie automatisch - `manual: true` heisst genau das.
|
||||
|
||||
### Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form
|
||||
|
||||
`instructions/migrations/6.0.0-type-guidance-split.md` verlangte in seinem Verifikationsschritt,
|
||||
die Ausgabe von `types describe <name>` muesse *"read the same as it did before this migration"* -
|
||||
ohne dass ein Schritt davor dieses Vorher festhielt. Eine Pruefung gegen einen Zustand, den
|
||||
niemand aufgeschrieben hat, faellt auf das Gedaechtnis des Ausfuehrenden zurueck, und bei ueber
|
||||
150 Zeilen Ausgabe je Typ ist das keins. Der getracete 6.0.0-Lauf hat entsprechend durch
|
||||
`| head -250` und `| tail -80` geprueft und *"structurally identical to before"* geurteilt; was
|
||||
das uebersah, lag in der Mitte der `source`-Ausgabe. Das Dokument schreibt die Ausgabe jetzt in
|
||||
einem eigenen Schritt **vor** der Aenderung in eine Datei und diffed hinterher, mit
|
||||
`grep -c '^## Authoring guidance'` als Ein-Zahl-Probe: zwei Koepfe sind richtig - einen setzt
|
||||
`types describe` selbst, einen bringt die Guidance-Datei mit.
|
||||
|
||||
Als generisches Muster steht dasselbe jetzt in `instructions/migrate-corpus.md` § "Writing the
|
||||
migration document", weil es nicht an diesem einen Dokument haengt: `migrate verify` traegt seine
|
||||
Baseline im letzten Commit, ob jemand daran denkt oder nicht - eine Migration an der Maschinerie
|
||||
statt an `kb/` hat gar keine, und genau dort entsteht die Behauptung, die sich nicht widerlegen
|
||||
laesst.
|
||||
|
||||
Zweiter Fehler im selben Dokument: der Beispielverweis auf `types/entity.md` zeigt in einer
|
||||
ausgelieferten Instanz auf die beim Setup adoptierte Kopie - also auf genau den Vorher-Zustand,
|
||||
den der Schritt entfernen laesst. Der Nachher-Zustand liegt dort unter
|
||||
`types/entity.md.template`, und im Ursprungs-Repo existiert diese Datei ueberhaupt nicht:
|
||||
`dist export` re-keyt `types/<name>.md` erst beim Export. Der Satz konnte in einer Instanz also
|
||||
nicht bloss unguenstig sein, er konnte dort nie stimmen. Dazu sagt der Schritt jetzt die Sprache
|
||||
des Pointer-Absatzes - englisch, weil Anleitungsprosa an einen Agenten Control Plane ist,
|
||||
unabhaengig davon, wem die Datei gehoert - und dass das auch fuer behaltene lokale Prosa gilt:
|
||||
die wird uebersetzt, nicht umbenannt. Die Tabelle dazu wird verlinkt statt kopiert
|
||||
(`types/type-spec.md` § "Who owns a type-spec"), und ein behaltener Abschnitt bekommt einen
|
||||
eigenen Namen statt der Ueberschrift, die `types describe` schon selbst setzt.
|
||||
|
||||
Derselbe Defekt eine Ebene hoeher, gefunden beim Nachmessen: `types/source.md` trug hier im
|
||||
Ursprungs-Repo noch einen Rest-Abschnitt `## Authoring guidance` mit einem einzigen Bullet, der
|
||||
die `title_prefix`-Frontmatter wiederholte - `types describe source` gab drei Koepfe aus, die
|
||||
anderen drei Typen zwei. Die Sprachzentralisierung hat den Abschnitt uebersetzt, der
|
||||
Guidance-Split den Rest der Prosa ausgelagert und diesen Bullet stehenlassen. Die Datei wird beim
|
||||
Export zu `types/source.md.template`, also haette ihn jede neu aufgesetzte Instanz mit adoptiert.
|
||||
Entfernt, geprueft mit genau dem Muster, das der Schritt oben jetzt vorschreibt: Vorher-Datei,
|
||||
Diff, vier entfernte Zeilen und sonst nichts, alle vier Typen komponieren jetzt mit zwei Koepfen.
|
||||
|
||||
Verifiziert: `docs verify` (73 ausgelieferte Dokumente, 58 Referenzdateien),
|
||||
`instructions verify` (23 Instruktionen, 7 Skills) und 1276 Tests gruen. Kein neuer Test: die
|
||||
Aenderung ist Prosa in zwei Instruktionen und ein entfernter Abschnitt aus einem Type-Spec -
|
||||
was hier mechanisch pruefbar waere, prueft `docs verify` bereits als Type-Spec gegen sein Schema.
|
||||
|
||||
Kein Grenzuebertritt: in beide Richtungen ein Drop-in. Die Korrektur gilt denen, die noch
|
||||
upgraden - eine Instanz, die das Angebot bereits genommen hat, liest das Dokument nicht noch
|
||||
einmal. Fuer sie lohnt der eine Befehl, mit dem der Schaden hier gefunden wurde:
|
||||
`grep -c '^## Authoring guidance'` ueber `types describe <name>` fuer alle vier Typen, drei
|
||||
bedeutet einen Rest-Abschnitt im eigenen Type-Spec.
|
||||
|
||||
---
|
||||
|
||||
## 6.0.1 - 2026-09-16 - docs toc/verify erreichen die .template-Form einer Referenzdatei
|
||||
|
||||
Reference in New Issue
Block a user