chemenu/kb/concepts/KB Stack Versioning.md

type, concept_type, tags, created, modified, related, sources, confidence, confidence_base, provenance, summary

type	concept_type	tags	created	modified	related	sources	confidence	confidence_base	provenance	summary
types/concept.md	decision	versioning semver release stack	2026-08-30	2026-09-02	mechanism wikitool see-also Issue Label Scheme see-also CI Integration	Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30 Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31 Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02	0.70	0.70	sourced	Semantische Versionierung des Wiki-Stacks: VERSION beschreibt die Maschinerie, Kompatibilitaet (Drop-in-Ersatz) und Inhaltsmigration sind seit 2.5.0 getrennte, unabhaengig geprueft Fragen

KB Stack Versioning

Typ: Decision

Definition

KB Stack Versioning ist die Entscheidung, den Wiki-Stack semantisch zu versionieren und diese Version strikt von der Form des Inhalts zu trennen. Die Stack-Version steht in der Wurzeldatei VERSION und wird ausschließlich von wikitool version bump geschrieben¹ . Sie beantwortet genau eine Frage: welche Maschinerie installiert ist.

Ein automatischer Bump aus Commit-Nachrichten wurde verworfen. wikitool publish --message "ingest: ..." schreibt Content-Commits in dasselbe Repository, sodass eine Conventional-Commit-Auswertung jeden Ingest zu einem Release machte¹ . Der Bump ist deshalb eine ausdrückliche Handlung.

Kernpunkte

• Drei Fakten, drei Dateien. VERSION trägt die Stack-Version und wird von version bump geschrieben; .wikitool-release.json ist der Release-Stempel, den dist export in jeden Export legt und der beantwortet, woher die Maschinerie stammt; .wikitool-kb.json trägt die KB-Version und wird von migrate done geschrieben¹ . Die Trennung ist keine Aufteilung aus Bequemlichkeit: Der Stempel ist erzeugt und darf nie von Hand geändert werden, der KB-Zustand dagegen ist veränderlicher Instanzzustand.
• Kompatibilität ist die linkeste Nicht-Null-Komponente - dieselbe Regel, die Cargos Caret-Ranges verwenden¹ . Sie gilt einheitlich für 0.x und 1.x, sodass unter 0.x der Schritt 0.1.x -> 0.2.0 dasselbe Signal trägt wie MAJOR ab 1.0.0. Der Code für den compat_key ist deshalb einheitlich formuliert und musste beim Wechsel auf 1.0.0 nicht angefasst werden¹ .
• Kompatibilität und Inhaltsmigration sind zwei unabhängige Fragen, seit 2.5.0 auch zwei getrennte Marker. Kompatibilität fragt, ob die neue Version ein Drop-in-Ersatz ist - vorwärts ohne Handarbeit, rückwärts noch downgradebar; Inhaltsmigration fragt, ob kb/ sich bewegen muss. Ein Grenzübertritt kann kb/ unangetastet lassen und trotzdem MAJOR sein - der 2.0.0-Rebranding-Bump ist das Beispiel: Update-Pfad, Release-Artefaktname und Paket-Import-Name brachen, keine Seite tat es. version bump verlangt deshalb bei jedem Grenzübertritt --breaking "<was aufhört zu funktionieren>", unabhängig von --no-migration/einem Migrationsdokument; beide Zeilen landen getrennt im CHANGES.md-Eintrag² .
• x.y.z ist die maximale Granularität. Keine Pre-Release-Suffixe. Eine zweite Ordnungsregel müsste vom Release-Feed, von der Migrationskette und von der Kompatibilitätsprüfung gleichermaßen befolgt werden¹ .
• Der Einstieg bei 1.0.0 statt 0.1.0 beseitigte einen Selbstwiderspruch: Die Anleitung in stack-dev/SKILL.md wies --minor sowohl „neue Fähigkeit" als auch „erfordert Migration" zu, was unter 0.x nicht beides zugleich stimmen kann¹ .
• Aktualisierungserkennung über einen Stempel, nicht über eine Prüfsumme. wikitool version check darf als einziger Befehl einen Netzaufruf machen: eigener Befehl, kein Schlüssel, Timeout, injizierbarer Fetch, damit Tests nie ein Netz berühren¹ . Der Aktualisierungspfad selbst (dist upgrade) wurde bewusst zurückgestellt: erst Erkennung, dann Ausführung.
• CI wird nicht mitgeliefert. runs-on: linux-docker ist ein standortspezifisches Runner-Label und gehört nicht in eine verteilte Instanz¹ .
• Die Grenze wird an zwei Stellen erzwungen: in version bump und in docs verify, ergänzt um einen kb-version-Check in doctor¹ . Seit 2.5.0 prüft docs verify dort zwei unabhängige Dinge - check_migration_for_boundary (hat der Korpus sich bewegt) und check_breaking_change_for_boundary (wurde der Bruch benannt) -, weil ein Grenzübertritt die eine Prüfung bestehen und an der anderen scheitern kann² .

Beispiele

• Chemenu - erste Instanz; 1.0.0 ist die Migrationsbasis, 1.0.1 das erste über die Pipeline veröffentlichte Release.
• wikitool - trägt die Befehlsgruppen version und migrate, die die drei Dateien schreiben und lesen.

Wann zu verwenden

Sobald eine Wissensbasis als installierbares Artefakt an mehr als eine Stelle geht und Aktualisierungen erkennbar sein müssen. Die Trennung von Stack- und Content-Version lohnt sich ab dem Moment, in dem eine Instanz existiert, deren Inhalt hinter der Maschinerie zurückbleiben kann.

Wann NICHT zu verwenden

• Nicht für den Inhalt. Eine Version, die Stack und Content zugleich beschreibt, macht den Zustand „Maschinerie 1.4.0, Inhalt in 1.2.0-Form" unabbildbar - und das ist der Zustand, den jedes Upgrade durchläuft¹ . Dafür ist KB Migration zuständig.
• Nicht als automatischer Bump aus Commit-Nachrichten, solange Content-Commits und Stack-Commits im selben Repository liegen.

Beziehungen

Siehe auch

• Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31
• Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02

Fußnoten

Beziehungen

• mechanism: wikitool
• see-also: Issue Label Scheme
• see-also: CI Integration

---

1. Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30 ↩︎

2. Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02 ↩︎