Semantische Versionierung

Semantische Versionierung

1) Was ist SemVer und warum wird es benötigt

• MAJOR - inkompatible Änderungen (Breaking Changes).
• MINOR ist eine neue API-kompatible Funktionalität.
• PATCH - Reversibel kompatible Fehlerbehebungen.

Das Ziel: die Stabilität der Verträge auszuhandeln und die Kosten für Updates zu senken.

2) Versionsformat

• `MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD]`

`1. 4. 7 'ist eine stabile Freigabe.
`1. 5. 0-rc. 2'- Vorveröffentlichung (Veröffentlichungskandidat Nr. 2).
`2. 0. 0+linux. arm64'- build-Metadaten (haben keinen Einfluss auf den Versionsvergleich).

1. Zuerst werden 'MAJOR', dann 'MINOR' und dann 'PATCH' verglichen.

2. Pre-Releases sind kleiner als die entsprechende stabile Version: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Build-Metadaten ('+...') haben keinen Einfluss auf die Reihenfolge: '1. 2. 0+001 == 1. 2. 0`.

3) Was als Breaking Change gilt

• Löschen/Umbenennen/Ändern der Signatur von öffentlichen Methoden/Endpunkten.
• Änderung des Ein-/Ausgabeformats (JSON-Schema, Typen).
• Änderung von Fehlerverträgen (Codes/Strukturen).
• Änderung der Seiteneffekte/SLAs (z.B. strenge Limits oder neue Pflichtfelder).

Nicht brechen (bei korrekter Implementierung): optionale Felder hinzufügen, enum mit neuen Werten erweitern (wenn der Client sie ignoriert), neue Endpunkte, neue Flags mit Standardwerten, die die aktuellen Anrufe nicht beeinflussen.

4) Pre-Releases und Channel-Strategien

• Stichworte: 'alpha', 'beta', 'rc'. Beispiel: '2. 3. 0-beta. 3`.
• Kanäle: nightly → alpha → beta → rc → stable.
• Richtlinie: Pre-Releases sollten nicht als transitive Abhängigkeiten für Standard-Prod-Builds fallen.

5) Versionsbereiche und Abhängigkeitsgenauigkeit

5. 1 Knoten/npm (Standard-SemVer)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0'(erlaubt MINOR/PATCH, fixiert MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0'(erlaubt PATCH innerhalb von MINOR).
`1. 4. x' ist ein beliebiger Patch in 1. 4.
Genaue PIN: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 'sind explizite Grenzen.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0)'- einschließlich/ausschließlich.
Für prodkritische Artefakte wird strenges Kicken empfohlen.

5. 4 Go modules

Immer vollständige' vMAJOR-Tags. MINOR. PATCH'; 'v2 +' erfordert das Modul-Suffix '/v2'.

Empfehlung: für Anwendungen - präzise Pins (reproducible builds). Für Bibliotheken - Caret-Bereiche (um Updates ohne Brüche zu erleichtern).

6) CHANGELOG и Conventional Commits

Ein strukturiertes Changelog erhöht die Transparenz.

feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

Типы: `feat`, `fix`, `perf`, `docs`, `refactor`, `chore` и т. д.
Ein Ausrufezeichen oder Block 'BREAKING CHANGE' kündigt eine MAJOR-Erhöhung an.
CHANGELOG wird aus der Historie von Commits (Release-Notes durch Bots) generiert.

7) Versionsrichtlinie für APIs

Öffentliche APIs: strenge SemVer; breaking → MAJOR.
HTTP/REST: Versionierung nach URL/Header: '/v1/...', '/v2/... 'oder' Accept: application/vnd. org. service. v2+json`.
JSON-Schemata: Moll-Erweiterungen - neue optionale Felder; major - Löschen/Ändern erforderlich.
gRPC/Protobuf: neue Felder mit neuen Zahlen hinzufügen; Verwenden Sie die Feldnummern nicht übermäßig. Entfernen Sie → deprecate, anstatt zu „brechen“ die bestehenden.

8) Daten- und Migrationsschemata

DB-Migrationen werden mit den App-Versionen synchronisiert: 'app @ 1. 8. 0 'erfordert' schema @ 1. 8. x`.
Für das Durchbrechen von Schemaänderungen - Phasen: expand (hinzufügen), migrate, contract (entfernen). Upgrade auf MAJOR nur, wenn Sie den alten Vertrag löschen.
Unterstützung von Dual Writing/Read für die Dauer der Migration.

9) Monorepos und Microservices

Multi-Paket: jedes Paket hat seinen eigenen 'MAJOR. MINOR. PATCH`; Allgemeiner Veröffentlichungsstammzyklus nur für Meta-Artefakte.

• Unabhängige Versionen (Lerna/Changesets) - verstärkt die Isolation.
• Lock-step - einfachere Kommunikation, aber mehr falsche MAJOR-s.
• Bei Microservices erfassen Sie die Verträge (OpenAPI/Protobuf) mit einer separaten Version: 'contract @ 2. 1. 0', der Dienst folgt ihr.

10) Automatisierung von Releases in CI/CD

• `fix` → `PATCH`, `feat` → `MINOR`, `!`/`BREAKING` → `MAJOR`.

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

CHANGELOG-Generierung, Release-Nodes veröffentlichen, Abhängigkeiten in GitOps-Repos aktualisieren, überprüfen, dass' main 'immer auf das letzte stabile Tag zeigt.

11) Deprivationspolitik (Deprivationspolitik)

Ankündigung: Markieren Sie die Funktionalität als deprecated in der MINOR-Veröffentlichung, geben Sie eine EOL-Frist ein (z. B. 90 Tage).
Beobachtbarkeit: Loggen Sie die Verwendung veralteter Endpunkte mit dem User/Tenant-Kontext.
Löschung: im nächsten MAJOR. Dokumentieren Sie den Migrationspfad.

12) Beispiele und Vorlagen

12. 1 Regulärer Ausdruck der SemVer-Validierung

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12. 2 Beispiele für Vergleiche

`1. 2. 3` < `1. 10. 0'(Vergleich nach MINOR).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Abhängigkeitsrichtlinie (Beispiel YAML)

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13) Anti-Muster

Verwendung von 'neuesten '/Floating-Tags im Produkt.
MAJOR-Boost ohne echte Entlassungen („Marketing-Versionen“).
Versteckte Breaking-Änderungen unter dem Deckmantel 'PATCH'.
Pre-Releases in transitiven Abhängigkeiten von Prod-Anwendungen.
Artefakt ohne neues Tag ändern (mutable Versionen).
Inkonsistente Versionen des OBD-Codes und -Schemas.

14) Implementierung Checkliste (0-45 Tage)

0-10 Tage

SemVer als verbindlichen Standard übernehmen, Abbruchkriterien genehmigen.
Aktivieren Sie Conventional Commits und die PR-Vorlage mit dem Feld 'BREAKING CHANGE'.

11-25 Tage

Anschluss semantic-release/changesets, autogenerierung CHANGELOG.
Passen Sie die Signatur und Veröffentlichung von Artefakten mit dem 'vX-Tag an. Y.Z`.

26-45 Tage

Geben Sie deprecation policy und Telemetrie für die Verwendung veralteter APIs ein.
Synchronisieren Sie die Versionen von Verträgen (OpenAPI/Proto) und Diensten.
Verbieten Sie „neueste“ und mutierbare Tags auf politischer Ebene (OPA/CI-Verordnungen).

15) Reifegradkennzahlen

% der Artefakte, die nur mit dem SemVer-Tag veröffentlicht werden.
Durchschnittliche Migrationszeit zwischen MINOR-Versionen.
Anzahl der Vorfälle aufgrund versteckter Breaking-Änderungen.
Abdeckung konventioneller Commits in Repositories (> 95%).
Anteil der Abhängigkeiten ohne schwebende Bereiche im Produkt (> 90%).

16) Wenn SemVer nicht benötigt wird

Interne Rapid-Prototypen ohne externe Verbraucher (datierte Versionierung geeignet).
Daten/Modelle mit experimentellen Fiches (besser Model/Schema Versioning mit Kompatibilität auf Konverterebene).
Content-Pakete ohne stabile öffentliche API.

17) Fazit

SemVer ist ein Vertrauensvertrag zwischen Hersteller und Verbraucher. Definieren Sie klar, was die Kompatibilität bricht, automatisieren Sie die Erkennung von Freigabetypen und die Veröffentlichung von Artefakten, führen Sie ein transparentes CHANGELOG und befolgen Sie die Deprivations-Richtlinie. Dann werden Updates routinemäßig, vorhersehbar und sicher - und die Infrastruktur und APIs entwickeln sich ohne Schocks für Unternehmen.