Semantic Versioning SemVer
Semantic Versioning: Versionsnummern richtig vergeben
Semantic Versioning (SemVer) bringt Ordnung in Versionsnummern. Jeder versteht sofort, ob ein Update Breaking Changes enthält oder nur Bugfixes.
Das Format: MAJOR.MINOR.PATCH
Version: 2.4.1
│ │ │
│ │ └── PATCH: Bugfixes (abwärtskompatibel)
│ └──── MINOR: Neue Features (abwärtskompatibel)
└────── MAJOR: Breaking Changes (inkompatibel)
Wann erhöhen?
| Änderung | Erhöhe | Beispiel |
|---|---|---|
| Breaking Change (API-Änderung) | MAJOR | 1.4.2 → 2.0.0 |
| Neues Feature (abwärtskompatibel) | MINOR | 1.4.2 → 1.5.0 |
| Bugfix | PATCH | 1.4.2 → 1.4.3 |
Wichtig
- Bei MAJOR-Erhöhung: MINOR und PATCH auf 0 setzen
- Bei MINOR-Erhöhung: PATCH auf 0 setzen
- Version 0.x.y: Entwicklungsphase, alles kann sich ändern
- Version 1.0.0: Erste stabile öffentliche API
Pre-Release Versionen
# Alpha (frühe Entwicklung) 1.0.0-alpha 1.0.0-alpha.1 1.0.0-alpha.2 # Beta (Feature-complete, aber Bugs) 1.0.0-beta 1.0.0-beta.1 # Release Candidate (fast fertig) 1.0.0-rc.1 1.0.0-rc.2 # Sortierung (aufsteigend) 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0
Build Metadata
# Build-Informationen (wird bei Vergleich ignoriert) 1.0.0+build.123 1.0.0+20240115 1.0.0-beta+exp.sha.5114f85 # Diese sind gleich: 1.0.0+build.1 1.0.0+build.2
Version Ranges (npm/Composer)
npm/Node.js
// package.json
{
"dependencies": {
// Exakte Version
"lodash": "4.17.21",
// Patch-Updates erlaubt (4.17.x)
"express": "~4.17.1",
// Minor-Updates erlaubt (4.x.x)
"react": "^17.0.2",
// Jede Version
"debug": "*",
// Bereich
"axios": ">=0.21.0 <1.0.0"
}
}
| Symbol | Bedeutung | Beispiel für ^1.2.3 |
|---|---|---|
^ (Caret) |
Kompatibel mit Version | >=1.2.3 <2.0.0 |
~ (Tilde) |
Ungefähr gleich | >=1.2.3 <1.3.0 |
> < = |
Vergleichsoperatoren | Wie angegeben |
x oder * |
Wildcard | 1.x = >=1.0.0 <2.0.0 |
Composer (PHP)
{
"require": {
"monolog/monolog": "^2.0",
"symfony/console": "~5.4.0",
"guzzle/guzzle": ">=7.0 <8.0"
}
}
Praktische Beispiele
Breaking Change
// Version 1.x
function getUser(id) {
return { name: "Max", age: 30 };
}
// Version 2.0.0 - Breaking Change!
// Rückgabeformat geändert
function getUser(id) {
return { data: { name: "Max", age: 30 }, meta: {} };
}
Neues Feature (Minor)
// Version 1.4.0
function getUser(id) { ... }
// Version 1.5.0 - Neue Funktion
function getUser(id) { ... }
function getUserByEmail(email) { ... } // NEU
Bugfix (Patch)
// Version 1.4.2
function getUser(id) {
// Fix: Handle null ID
if (!id) return null;
...
}
CalVer als Alternative
Calendar Versioning basiert auf Datum:
# Formate 2024.01.15 # YYYY.MM.DD 2024.1 # YYYY.MINOR 24.1.0 # YY.MINOR.PATCH # Beispiele Ubuntu: 24.04 (April 2024) PyPI: 2024.1
Automatisierung
npm version
# Version erhöhen npm version patch # 1.0.0 → 1.0.1 npm version minor # 1.0.0 → 1.1.0 npm version major # 1.0.0 → 2.0.0 # Pre-Release npm version prerelease --preid=beta # 1.0.0 → 1.0.1-beta.0
Conventional Commits + Release
# Mit semantic-release automatisch versionieren npx semantic-release # Basiert auf Commit Messages: # fix: → PATCH # feat: → MINOR # feat!: oder BREAKING CHANGE: → MAJOR
💡 Tipp:
Nutzen Sie Conventional Commits und Tools wie semantic-release, um Versionierung zu automatisieren. Das eliminiert menschliche Fehler.
Checkliste: Breaking Changes erkennen
- ☐ Funktion/Methode entfernt oder umbenannt?
- ☐ Parameter geändert (Reihenfolge, Typ, erforderlich)?
- ☐ Rückgabeformat geändert?
- ☐ Verhalten geändert (gleicher Input, anderer Output)?
- ☐ Mindestanforderungen erhöht (PHP 7 → PHP 8)?
- ☐ Konfigurationsformat geändert?