chemenu/kb/concepts/KB Stack Versioning.md

---
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]
confidence: 0.70
confidence_base: 0.70
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 "<was aufhört zu funktionieren>"`, 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]]

<!-- wikitool:links -->
## Beziehungen

- **mechanism:** [[wikitool]]
- **see-also:** [[Issue Label Scheme]]
- **see-also:** [[CI Integration]]
<!-- /wikitool:links -->