torben/chemenu
1
1
Fork 0
Code Issues 26 Pull Requests Actions Packages Releases 32 Activity

MAJOR ist in der Doku als Inhaltsmigration definiert, nicht als Kompatibilitätsbruch #26

New Issue
Closed
opened 2026-09-01 10:00:50 +00:00 by torben · 1 comment
torben commented 2026-09-01 10:00:50 +00:00
Owner
Copy Link
Copy Source

Beobachtung aus der Umsetzung von #3 (Stack 2.0.0).

Die Doku des Stacks führt für die Wahl der Versionsstelle zwei Fragen zusammen, die nicht dasselbe sind:

  • Muss der Korpus migriert werden?
  • Ist der Wechsel rückwärtskompatibel?

An allen Stellen, die einer Session bei der Entscheidung begegnen, steht nur die erste:

Ort Wortlaut
instructions/dev/stack-dev/SKILL.md, Schritt 3 Tabelle: --major ⇔ „Existing content must be migrated"
tools/chemenu/version.py, Modul-Docstring „from 1.0.0 on the same rule reads as the familiar 'MAJOR means migration'"
INSTALL.md § Version und Updates „ab 1.0.0 liest sich dieselbe Regel als das gewohnte 'MAJOR heißt Migration'"

Nur version bump --help formuliert es korrekt („A bump that crosses the compatibility boundary additionally requires a migration document … or --no-migration") — also ausgerechnet die Stelle, die man erst liest, wenn die Entscheidung schon gefallen ist.

Warum das zählt

Bei #3 hat genau diese Lücke zu einer falschen Einschätzung geführt. Der Rebranding-Wechsel migriert keinen Inhalt, brach aber drei Dinge:

  1. .wikitool-release.json jeder bestehenden Instanz zeigt auf den alten Repo-Pfad — version check erfährt dort nichts mehr, und die Instanz kann den Stempel nicht reparieren (Invariante 1).
  2. Der Release-Artefaktname änderte sich (llm-wiki-stack-* → chemenu-stack-*).
  3. Der Import-Name des Pakets änderte sich (wiki_tools → chemenu).

Nach der Tabelle im Skill war das --minor. Nach der tatsächlichen Regel ist es --major --no-migration. Der Fehler wurde vom Nutzer gefangen, nicht von der Doku — und die Existenz von --no-migration beweist, dass das Werkzeug den Fall längst kennt: es gibt boundary-crossing Bumps ohne Inhaltsmigration. Die Prosa kennt ihn nicht.

Was „fertig" heißt

  • instructions/dev/stack-dev/SKILL.md: Tabellenzeile für --major formuliert die Kompatibilitätsfrage, nicht die Migrationsfrage. Die Inhaltsmigration wird als Folge genannt („und dann zusätzlich: Migrationsdokument oder --no-migration"), nicht als Auslöser.
  • tools/chemenu/version.py: Docstring trennt beides ausdrücklich — die leftmost-non-zero-Regel beschreibt Kompatibilität; ob Inhalt migriert werden muss, ist eine zweite, unabhängige Frage.
  • INSTALL.md § Version und Updates: dieselbe Trennung, aus Leserperspektive („ein MAJOR-Sprung kann eine leere Migrationskette haben und trotzdem Handarbeit verlangen" — genau der Fall, den der neue Abschnitt „Sonderfall: Update von 1.x auf 2.0.0" beschreibt).
  • Eine Entscheidungshilfe, die eine Session vor dem Bump erreicht: welche Arten von Bruch MAJOR erzwingen, auch wenn kb/ unangetastet bleibt — Update-Pfad, Artefaktnamen, Import-/Kommandonamen, Envvars, Stempeldateien.
  • Invariante 8 prüfen: die drei Stellen dürfen sich danach nicht widersprechen. Ob eine davon zur einzigen Quelle wird und die anderen verlinken, ist Teil der Umsetzung.

Nicht Teil dieses Issues

docs verify maschinell prüfen zu lassen, ob eine Versionsstelle richtig gewählt wurde — das ist eine Urteilsfrage und kein hartes Orakel. Hier geht es um die Prosa, die dieses Urteil anleitet.

Kontext

  • Auslöser: #3, Stack 2.0.0 (Commit 9a7abe6)
  • Der CHANGES.md-Eintrag zu 2.0.0 enthält unter „Warum das trotzdem MAJOR ist" die Begründung im Volltext und kann als Fallbeispiel dienen.
**Beobachtung aus der Umsetzung von #3 (Stack 2.0.0).** Die Doku des Stacks führt für die Wahl der Versionsstelle zwei Fragen zusammen, die nicht dasselbe sind: - *Muss der Korpus migriert werden?* - *Ist der Wechsel rückwärtskompatibel?* An allen Stellen, die einer Session bei der Entscheidung begegnen, steht nur die erste: | Ort | Wortlaut | |---|---| | `instructions/dev/stack-dev/SKILL.md`, Schritt 3 | Tabelle: `--major` ⇔ „**Existing content must be migrated**" | | `tools/chemenu/version.py`, Modul-Docstring | „from `1.0.0` on the same rule reads as the familiar '**MAJOR means migration**'" | | `INSTALL.md` § Version und Updates | „ab `1.0.0` liest sich dieselbe Regel als das gewohnte '**MAJOR heißt Migration**'" | Nur `version bump --help` formuliert es korrekt („A bump that **crosses the compatibility boundary** additionally requires a migration document … or `--no-migration`") — also ausgerechnet die Stelle, die man erst liest, wenn die Entscheidung schon gefallen ist. ## Warum das zählt Bei #3 hat genau diese Lücke zu einer falschen Einschätzung geführt. Der Rebranding-Wechsel migriert keinen Inhalt, brach aber drei Dinge: 1. `.wikitool-release.json` jeder bestehenden Instanz zeigt auf den alten Repo-Pfad — `version check` erfährt dort nichts mehr, und die Instanz kann den Stempel nicht reparieren (Invariante 1). 2. Der Release-Artefaktname änderte sich (`llm-wiki-stack-*` → `chemenu-stack-*`). 3. Der Import-Name des Pakets änderte sich (`wiki_tools` → `chemenu`). Nach der Tabelle im Skill war das `--minor`. Nach der tatsächlichen Regel ist es `--major --no-migration`. Der Fehler wurde vom Nutzer gefangen, nicht von der Doku — und die Existenz von `--no-migration` beweist, dass das Werkzeug den Fall längst kennt: es gibt boundary-crossing Bumps ohne Inhaltsmigration. Die Prosa kennt ihn nicht. ## Was „fertig" heißt - [ ] `instructions/dev/stack-dev/SKILL.md`: Tabellenzeile für `--major` formuliert die Kompatibilitätsfrage, nicht die Migrationsfrage. Die Inhaltsmigration wird als *Folge* genannt („und dann zusätzlich: Migrationsdokument oder `--no-migration`"), nicht als Auslöser. - [ ] `tools/chemenu/version.py`: Docstring trennt beides ausdrücklich — die leftmost-non-zero-Regel beschreibt Kompatibilität; ob Inhalt migriert werden muss, ist eine zweite, unabhängige Frage. - [ ] `INSTALL.md` § Version und Updates: dieselbe Trennung, aus Leserperspektive („ein MAJOR-Sprung kann eine leere Migrationskette haben und trotzdem Handarbeit verlangen" — genau der Fall, den der neue Abschnitt „Sonderfall: Update von 1.x auf 2.0.0" beschreibt). - [ ] Eine Entscheidungshilfe, die eine Session vor dem Bump erreicht: welche Arten von Bruch MAJOR erzwingen, auch wenn `kb/` unangetastet bleibt — Update-Pfad, Artefaktnamen, Import-/Kommandonamen, Envvars, Stempeldateien. - [ ] Invariante 8 prüfen: die drei Stellen dürfen sich danach nicht widersprechen. Ob eine davon zur einzigen Quelle wird und die anderen verlinken, ist Teil der Umsetzung. ## Nicht Teil dieses Issues `docs verify` maschinell prüfen zu lassen, ob eine Versionsstelle richtig gewählt wurde — das ist eine Urteilsfrage und kein hartes Orakel. Hier geht es um die Prosa, die dieses Urteil anleitet. ## Kontext - Auslöser: #3, Stack 2.0.0 (Commit `9a7abe6`) - Der `CHANGES.md`-Eintrag zu 2.0.0 enthält unter „Warum das trotzdem MAJOR ist" die Begründung im Volltext und kann als Fallbeispiel dienen.
torben added the prio/plannedsize/S labels 2026-09-01 10:00:50 +00:00
torben commented 2026-09-02 07:20:07 +00:00
Author
Owner
Copy Link
Copy Source

Umgesetzt in 2.5.0 (Commit 31662dc).

Neu: instructions/dev/version-parts.md - einzige Quelle der Regel. Trennt die
Kompatibilitätsfrage (ist die neue Version ein Drop-in-Ersatz - vorwärts ohne Handarbeit,
rückwärts noch downgradebar?) von der Migrationsfrage (muss kb/ sich bewegen?). Enthält den
Katalog der Brüche, die die Grenze bei unangetastetem kb/ überschreiten (Update-Pfad,
Artefaktname, Import-Name, Flags, Envvars, Shape maschinengelesener Dateien) und den 2.0.0-Fall
als Fallbeispiel. Liegt unter instructions/dev/, also nicht in einer verteilten Instanz - die
ausgelieferten Artefakte (stack-dev, version.py-Docstring, INSTALL.md) tragen die Kurzform
der Regel, aber keinen Verweis auf die Datei, sonst hätte instructions verify einen
dangelnden Verweis nach dist export gemeldet.

Über die vier "fertig heißt"-Punkte hinaus, weil beim Schreiben klar wurde, dass reine Prosa
wieder drifted:

  • version bump --breaking "<was aufhört zu funktionieren>" ist bei jedem Grenzübertritt
    Pflicht (verweigert auf jedem anderen Bump), schreibt **Breaking Change:** vor die
    Migrationszeile in den CHANGES.md-Eintrag.
  • docs verify bekommt eine zweite, unabhängige Prüfung
    (check_breaking_change_for_boundary) neben der bestehenden Migrationsprüfung - ein
    Rebranding wie 2.0.0 besteht die eine und fällt ohne --breaking durch die andere.
  • stack-dev bekommt einen Entscheidungspunkt: stellt sich eine Änderung als nicht drop-in
    heraus, wird nicht aus eigener Initiative gebumpt. Vorzulegen sind der konkrete Bruch, die
    Handarbeit je Instanz und drei Alternativen (Shim, aufschieben/bündeln, kompatibel/brechend
    aufspalten mit Deprecation-Fenster), dazu eine Empfehlung - erst dann Freigabe.

Sechs neue Tests, volle Suite grün (806), docs verify/instructions verify sauber.

docs verify prüft weiterhin nicht, ob die Stelle richtig gewählt wurde - das bleibt
ausdrücklich Urteil, wie im Issue verlangt ("Nicht Teil dieses Issues").

Umgesetzt in `2.5.0` (Commit `31662dc`). **Neu:** `instructions/dev/version-parts.md` - einzige Quelle der Regel. Trennt die Kompatibilitätsfrage (ist die neue Version ein Drop-in-Ersatz - vorwärts ohne Handarbeit, rückwärts noch downgradebar?) von der Migrationsfrage (muss `kb/` sich bewegen?). Enthält den Katalog der Brüche, die die Grenze bei unangetastetem `kb/` überschreiten (Update-Pfad, Artefaktname, Import-Name, Flags, Envvars, Shape maschinengelesener Dateien) und den `2.0.0`-Fall als Fallbeispiel. Liegt unter `instructions/dev/`, also nicht in einer verteilten Instanz - die ausgelieferten Artefakte (`stack-dev`, `version.py`-Docstring, `INSTALL.md`) tragen die Kurzform der Regel, aber keinen Verweis auf die Datei, sonst hätte `instructions verify` einen dangelnden Verweis nach `dist export` gemeldet. **Über die vier "fertig heißt"-Punkte hinaus, weil beim Schreiben klar wurde, dass reine Prosa wieder drifted:** - `version bump --breaking "<was aufhört zu funktionieren>"` ist bei jedem Grenzübertritt Pflicht (verweigert auf jedem anderen Bump), schreibt `**Breaking Change:**` vor die Migrationszeile in den `CHANGES.md`-Eintrag. - `docs verify` bekommt eine zweite, unabhängige Prüfung (`check_breaking_change_for_boundary`) neben der bestehenden Migrationsprüfung - ein Rebranding wie `2.0.0` besteht die eine und fällt ohne `--breaking` durch die andere. - `stack-dev` bekommt einen Entscheidungspunkt: stellt sich eine Änderung als nicht drop-in heraus, wird nicht aus eigener Initiative gebumpt. Vorzulegen sind der konkrete Bruch, die Handarbeit je Instanz und drei Alternativen (Shim, aufschieben/bündeln, kompatibel/brechend aufspalten mit Deprecation-Fenster), dazu eine Empfehlung - erst dann Freigabe. Sechs neue Tests, volle Suite grün (806), `docs verify`/`instructions verify` sauber. `docs verify` prüft weiterhin nicht, *ob* die Stelle richtig gewählt wurde - das bleibt ausdrücklich Urteil, wie im Issue verlangt ("Nicht Teil dieses Issues").
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/corpus
Betrifft Demo-/Testbett-Frage, Inhalt und Umfang von kb/
 area/distribution
Betrifft Auslieferung, Upgrade, Versionierung einer Instanz
 area/kb
Betrifft kb/-Schema, Contract, Confidence, Lint, Wissensbasis
 area/process
Betrifft den Entwicklungsprozess selbst, nicht den Stack als Artefakt
 area/workflow
Betrifft Git, Merge, Branching, Publish, PRs
 kind/build
Spezifiziert, wartet nur noch auf Umsetzungszeit
 kind/decision
Wartet auf eine Betreiberentscheidung
 kind/defect
Befund: Doku und Realitaet, oder zwei Dokus, widersprechen sich
 prio/blocking
Blockiert oder beschaedigt laufende Arbeit - als naechstes
 prio/planned
Traegt bald Zinsen - eingeplant
 prio/waiting
Sinnvoll, wartet auf einen Ausloeser
 size/L
Mehrere Sitzungen oder offene Designfragen vor dem ersten Commit
 size/M
Mehrere Dateien, Contract- oder Instruction-Aenderung, eigener Testaufwand
 size/S
Eine Sitzung, ein Publish, klar umrissener Schnitt
 status/blocked
Wartet auf ein anderes, noch offenes Issue - nicht eigenstaendig bearbeitbar
 status/incoming
Vom Menschen angelegte Anforderung, unvollständig, muss durch den Stack komplettiert werden.
 status/unconfirmed
Gemeldeter Verdacht, noch nicht gegen tatsaechliches Verhalten geprueft - size/prio vorlaeufig
No Label prio/planned size/S
Milestone
No items
No Milestone
Assignees
Clear assignees
torben
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#26
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?