torben
18ae28f918
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
112 lines
5.6 KiB
Markdown
112 lines
5.6 KiB
Markdown
---
|
|
type: types/concept.md
|
|
concept_type: decision
|
|
tags: [versioning, semver, release, stack]
|
|
created: 2026-08-30
|
|
modified: 2026-08-30
|
|
related: [wikitool, Issue Label Scheme]
|
|
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]
|
|
confidence: 0.70
|
|
confidence_base: 0.70
|
|
provenance: sourced
|
|
summary: 'Semantische Versionierung des Wiki-Stacks: VERSION beschreibt die Maschinerie, Kompatibilitaet ist die linkeste Nicht-Null-Komponente, und drei getrennte Dateien trennen Maschinerie, Herkunft und Content-Form'
|
|
---
|
|
# 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
|
|
Migrationssignal 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].
|
|
- **`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].
|
|
|
|
## 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.
|
|
|
|
## Verwandte Concepts
|
|
|
|
- [[KB Migration]]
|
|
- [[CI Integration]]
|
|
|
|
## Beziehungen
|
|
|
|
- **umgesetzt von:** [[wikitool]]
|
|
- **verwandt mit:** [[Issue Label Scheme]]
|
|
|
|
## Siehe auch
|
|
|
|
- [[wikitool]]
|
|
- [[Issue Label Scheme]]
|
|
- [[Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31]]
|
|
|
|
## 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]]
|