--- type: types/concept.md concept_type: decision tags: [versioning, semver, release, stack] created: 2026-08-30 modified: 2026-09-02 related: - mechanism: wikitool - see-also: Issue Label Scheme - see-also: CI Integration sources: [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] provenance: sourced summary: '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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. 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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. 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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. 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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. 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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **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 ""`, unabhängig von `--no-migration`/einem Migrationsdokument; beide Zeilen landen getrennt im `CHANGES.md`-Eintrag[^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02]. - **`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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. 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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **Die Grenze wird an zwei Stellen erzwungen:** in `version bump` und in `docs verify`, ergänzt um einen `kb-version`-Check in `doctor`[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. 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[^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02]. ## 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[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. 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 [^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]: [[Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30]] [^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02]: [[Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]] ## Beziehungen - **mechanism:** [[wikitool]] - **see-also:** [[Issue Label Scheme]] - **see-also:** [[CI Integration]]