Webentwicklung

Semantic Versioning: Versionsnummern als Vertrag

Semantic Versioning (SemVer) ist eine Vereinbarung über Versionsnummern: MAJOR.MINOR.PATCH. Sie ist klein, aber ihre konsequente Anwendung erspart Abhängigkeitsverwaltung sehr viel Ärger.

\n

Die Regeln

\n
MAJOR.MINOR.PATCH  z. B.  2.14.3\n\nPATCH  erhoehen bei Fehlerkorrekturen ohne Verhaltensaenderung\n       -> 2.14.3 -> 2.14.4\n       Ein Nutzer kann gefahrlos aktualisieren.\n\nMINOR  erhoehen bei neuer Funktionalitaet, abwaertskompatibel\n       -> 2.14.4 -> 2.15.0\n       Ein Nutzer kann gefahrlos aktualisieren, bekommt aber\n       Neues dazu. PATCH wird auf 0 gesetzt.\n\nMAJOR  erhoehen bei inkompatiblen Aenderungen\n       -> 2.15.0 -> 3.0.0\n       Ein Nutzer MUSS pruefen, ob sein Code noch funktioniert.\n       MINOR und PATCH werden auf 0 gesetzt.\n\nVorabversionen und Zusatzangaben:\n  1.0.0-alpha.1        Vorabversion (nicht fuer Produktion)\n  1.0.0-beta.3\n  1.0.0-rc.1           Freigabekandidat\n  1.0.0+build.20260926 Bauangabe (zaehlt NICHT fuer die Rangfolge!)\n  1.0.0-rc.1 < 1.0.0   Vorabversionen sind NIEDRIGER als die Freigabe\n\nRangfolge:\n  1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0\n  < 1.0.1 < 1.1.0 < 2.0.0\n\nVor 1.0.0: Alles darf sich aendern. Eine MINOR-Erhoehung darf\n  inkompatibel sein. Wer Stabilitaet braucht, sollte auf\n  1.0.0 oder hoeher warten.
\n

Was als inkompatibel gilt

\n
INKOMPATIBEL (MAJOR):\n  - Entfernen oder Umbenennen einer oeffentlichen Funktion\n  - Aenderung eines Rueckgabetyps\n  - Ein Parameter wird erforderlich statt optional\n  - Aenderung des Standardverhaltens\n  - Neue erforderliche Konfiguration\n  - Aenderung der Fehlersemantik (Ausnahme statt Rueckgabewert)\n  - Anheben der Mindestversion einer Abhaengigkeit\n  - Entfernen einer veralteten Schnittstelle\n\nKOMPATIBEL (MINOR):\n  - Neue Funktion oder neuer Parameter mit Standardwert\n  - Neue optionale Konfiguration\n  - Veraltung (Deprecation) einer Schnittstelle\n    -> Die Schnittstelle bleibt funktionsfaehig!\n\nKOMPATIBEL (PATCH):\n  - Fehlerkorrektur ohne Verhaltensaenderung\n  - Leistungsverbesserung\n  - Dokumentation, Kommentare\n  - Sicherheitskorrektur (siehe unten)\n\nWARNUNG: Ein Patch kann sicherheitsrelevant sein. Wenn eine\nAnwendung sich auf fehlerhaftes Verhalten verlassen hat,\nist die Korrektur faktisch inkompatibel. Dann ist ein\nHinweis in den Release Notes Pflicht - und in Zweifelsfaellen\neine MAJOR-Erhoehung die ehrliche Wahl.
\n

Abhängigkeiten richtig festlegen

\n
# Die Wahl der Versionsspanne entscheidet ueber Ueberraschungen.\n\n# npm (package.json)\n"^1.2.3"    >=1.2.3 <2.0.0    MINOR-Updates erlaubt  (ueblich)\n"~1.2.3"    >=1.2.3 <1.3.0    nur PATCH-Updates\n"1.2.3"     exakt             keine Updates\n">=1.2.3 <2"  Spanne\n"*"         alles             NIEMALS in Produktion\n#   package-lock.json ist Pflicht und wird eingecheckt!\n\n# Python (requirements.txt)\npaket==1.2.3                  exakt, empfohlen fuer Anwendungen\npaket>=1.2.3                  zu offen\npaket~=1.2.3                  >=1.2.3, ==1.*  (nur PATCH)\npaket~=1.2                    >=1.2, <2.0\n#   Fuer Anwendungen: exakte Angaben + Sperrdatei.\n#   Fuer Bibliotheken: moeglichst offene Spannen - die Anwendung\n#   entscheidet ueber die genaue Version.\n\n# Go (go.mod)\nrequire example.org/lib v1.2.3\n#   Go-Module folgen SemVer; v2+ erfordert einen neuen Pfad\n#   (/v2). Damit ist die Inkompatibilitaet im Import sichtbar -\n#   das ist der Vorteil des Systems.\n\n# Rust (Cargo.toml)\nlib = "1.2.3"                 >=1.2.3, <2.0.0\nlib = "=1.2.3"                exakt\n#   Cargo.lock einchecken bei Anwendungen.\n\n# Fuer Anwendungen gilt immer:\n#   Sperrdatei (lock file) erzeugen, einchecken, im Bau\n#   verwenden (npm ci, pip install -r, cargo build --locked).\n#   Ohne Sperrdatei sind zwei Baue am selben Tag verschieden.
\n

Prüfen und pflegen

\n
# Welche Versionen sind installiert?\nnpm ls --depth=0\npip list --outdated\ngo list -m -u all\ncargo outdated\n\n# Sicherheitsluecken in Abhaengigkeiten\nnpm audit --omit=dev\npip-audit\ngovulncheck ./...\ncargo audit\ntrivy fs --scanners vuln .\n#   In die CI aufnehmen! Eine Luecke in einer Abhaengigkeit\n#   ist die haeufigste Ursache fuer einen Vorfall.\n\n# Veraltete Abhaengigkeiten finden\nnpx npm-check-updates --interactive\n\n# Automatisierte Aktualisierungen\n#   Dependabot / Renovate konfigurieren:\n#     - PATCH/MINOR: automatisch als PR\n#     - MAJOR: PR mit Kennzeichnung, manuelle Pruefung\n#     - Gruppierung nach Oekosystem (weniger PRs)\n#     - Zeitfenster fuer die Zusammenfuehrung\n#   Ohne Automatisierung bleibt die Aktualisierung\n#   liegen - und irgendwann ist es ein Grossprojekt.\n\n# Nach jeder Aktualisierung\n#   1. Tests laufen lassen\n#   2. Release Notes der Abhaengigkeit lesen (nicht nur die\n#      Versionsnummer pruefen!)\n#   3. Bei MAJOR: alle inkompatiblen Aenderungen durchgehen
\n

Prüfliste

\n
    \n
  1. Folgen die eigenen Veröffentlichungen SemVer – inklusive ehrlicher MAJOR-Erhöhungen?
    2. \n
  2. Sind inkompatible Änderungen in den Release Notes benannt?
    3. \n
  3. Sind Sperrdateien vorhanden und eingecheckt?
    4. \n
  4. Sind Versionsspannen bewusst gewählt (nicht *, nicht pauschal >=)?
    5. \n
  5. Werden veraltete Abhängigkeiten regelmäßig aktualisiert (nicht erst im Notfall)?
    6. \n
  6. Läuft eine Prüfung auf Sicherheitslücken in der CI?
    7. \n
  7. Werden Abhängigkeiten vor dem Aktualisieren auf Vertrauenswürdigkeit geprüft (Tippfehler-Angriffe, übernommene Pakete)?
    8. \n
  8. Ist deprecated markiert, bevor eine Schnittstelle entfernt wird?
    9. \n
\n

Häufige Fehler

\n
    \n
  1. „Wir machen kein SemVer.“ Dann muss jede Aktualisierung manuell geprüft werden und niemand traut Updates. Das kostet mehr als die Regel.
    2. \n
  2. Neue Funktionalität im PATCH. Wer überrascht wird, wird vorsichtig – und aktualisiert dann gar nicht mehr.
    3. \n
  3. 0.x als stabil behandelt. Vor 1.0.0 ist jederzeit alles möglich. Wer das vergisst, baut auf Sand.
    4. \n
  4. Keine Sperrdatei. Derselbe Quellstand baut zu unterschiedlichen Zeiten unterschiedliche Ergebnisse.
    5. \n
  5. Sicherheitskorrektur ohne Hinweis. Ein Patch, der eine Lücke schließt, ist unter Umständen inkompatibel. Immer benennen.
    6. \n
  6. Alle Abhängigkeiten auf exakt. Dann bekommt man keine Sicherheitskorrekturen – auch nicht für Unterabhängigkeiten. Bei Anwendungen: exakte Versionen plus regelmäßige Aktualisierung.
    7. \n
  7. Zu offene Spannen für Bibliotheken. >=1.0.0 ohne Obergrenze bricht beim nächsten MAJOR.
    8. \n
  8. Vertrauensfrage ignoriert. Die Aktualisierung einer beliebten Bibliothek ist ein beliebtes Angriffsziel. Prüfen, wer veröffentlicht, und Pakete mit Unterstrich oder Bindestrich im Namen nicht verwechseln.
    9. \n
\n

Verwandte Grundlagen: Semantic Versioning, Paketmanager, Dockerfile-Best-Practices, Software-Lieferkette.