SemVer-Parser & Vergleicher

Was ist ein Semantic-Version-Parser?#

Semantic Versioning (SemVer) ist die major.minor.patch-Konvention, die die meisten Bibliotheken verwenden, um zu signalisieren, welche Art von Änderung ein Release enthält: ein Bugfix erhöht patch, abwärtskompatible Erweiterungen erhöhen minor, und ändernde Änderungen (Breaking Changes) erhöhen major. Fügen Sie ein Vorabversion-Tag (1.0.0-beta.1) oder Build-Metadaten (+exp.sha.1) hinzu, erhalten Sie die vollständige Grammatik, die auf semver.org 2.0.0 definiert ist.

Das Problem ist, dass „zwei Versionen vergleichen“ und „erfüllt diese Version meinen Abhängigkeitsbereich“ beim bloßen Draufschauen schnell falsch laufen. Ist 1.0.0 höher oder niedriger als 1.0.0-beta? (Höher — ein Release rangiert immer über seiner Vorabversion.) Erfüllt 1.2.3 das ^1.2.0? (Ja.) Erfüllt es ~1.2.0? (Ebenfalls ja, aber aus einem engeren Grund.) Diese Seite parst Versionen so, wie die Spezifikation sie definiert, zeigt Ihnen die Bestandteile, vergleicht zwei Versionen nach Präzedenz und beantwortet Bereichsabfragen mit derselben ^ / ~ / >= / || / Bindestrich-Syntax, die eine package.json verwendet — alles lokal, gegen die echten Regeln statt gegen eine Vermutung.

So wird es verwendet#

1. Verwenden Sie die Beispiele-Schaltflächen oben, um häufige Beispiele einzufügen, oder tippen Sie direkt.
2. Geben Sie Version A und Version B in die beiden Eingabefelder ein. Ein führendes v oder = wird akzeptiert und entfernt; 1.2.3-beta.1+build.42 wird in seine Teile zerlegt.
3. Geben Sie einen Bereich-Ausdruck ein, wenn Sie eine Erfüllungsprüfung wollen. Der Standard ist ^1.2.0 || >=2.0.0 <3.0.0 — zwei ODER-Sätze, so wie echte Abhängigkeitsbereiche geschrieben werden. Unterstützte Syntax: ^ (Caret), ~ (Tilde), >= <= > < =, x / X / * Wildcards, partielle Versionen (1.2), - Bindestrichbereiche und || zum ODER-Verknüpfen von Sätzen.
4. Lesen Sie die beiden Parse-Karten. Jede zeigt die kanonische clean-Form und die aufgedröselten Felder major, minor, patch, prerelease und build. Eine ungültige Version wird rot mit einer Meldung.
5. Lesen Sie die Vergleichskarte. Sie stellt A < B, A = B oder A > B nach Präzedenz dar, plus die Änderung — die höchste Komponente, die sich geändert hat (major, minor, patch, prerelease oder build).
6. Lesen Sie die Bereichsprüfungskarte. Sie sagt Ihnen für den eingetippten Bereich, ob A ihn erfüllt und ob B ihn erfüllt.

Die wichtigsten Funktionen#

• Präzedenz nach Spezifikation. Der Vergleich durchläuft major.minor.patch und dann die Vorabversions-Bezeichner, mit der Regel, dass eine Version ohne Vorabversion immer über einer mit Vorabversion rangiert. Numerische Bezeichner werden numerisch verglichen (beta.2 < beta.11); alphanumerische lexikalisch; und numerische rangieren stets unter alphanumerischen. Build-Metadaten werden geparst und angezeigt, beeinflussen aber nie die Präzedenz.
• Caret und Tilde, korrekt aufgelöst. ^1.2.3 wird zu >=1.2.3 <2.0.0; ^0.2.3 wird zu >=0.2.3 <0.3.0; ^0.0.3 wird zu >=0.0.3 <0.0.4 — die „linkste Nicht-Null“-Regel des Carets. Tilde pinnt auf dieselbe Minor-Version: ~1.2.3 ist >=1.2.3 <1.3.0.
• Bereiche mit ||, Bindestrichen und Wildcards. ^1.0.0 || >=2.0.0 <3.0.0 (ODER aus zwei Sätzen), 1.2.0 - 1.5.0 (inklusiver Bindestrichbereich), 1.x / 1.2.* (Wildcard-Bereiche) werden alle geparst und geprüft.
• Die Vorabversion-Einschluss-Schwelle. Eine Vorabversion kann einen Bereich nur erfüllen, wenn ein Komparator im selben Set ein Vorabversions-Tag auf derselben major.minor.patch trägt. Also erfüllt 1.5.0-rc.1 nicht ^1.2.0, aber es erfüllt ^1.5.0-rc.0 — passend zu wie echte Paketmanager zufällige Vorabversionen aus Ihren Release-Builds heraushalten.
• Änderung mit Aussagekraft. Das Änderungs-Feld meldet die höchste Komponente, die sich geändert hat, sodass ein Sprung von 1.2.3 auf 2.0.0 major anzeigt, und 1.0.0 auf 1.0.0 mit geändertem Build zeigt build, selbst wenn die Präzedenz unverändert ist.
• Nachsichtige Eingabe. Führendes v, ein führendes = und umgebende Leerzeichen werden toleriert, sodass Versionen, die aus einem Git-Tag oder einem Changelog kopiert wurden, ohne manuelle Bereinigung geparst werden.

Anwendungsbeispiel#

Mit den Standardwerten — A 1.2.3, B 2.0.0, Bereich ^1.2.0 || >=2.0.0 <3.0.0 — meldet die Seite:

A clean    1.2.3        (major 1, minor 2, patch 3)
B clean    2.0.0        (major 2, minor 0, patch 0)
Vergleich  1.2.3  <  2.0.0
Änderung   major
Bereich    A erfüllt    B erfüllt

Beide Versionen erfüllen den Bereich, aber aus unterschiedlichen Gründen: A fällt in den ersten ODER-Satz (^1.2.0 → >=1.2.0 <2.0.0), B fällt in den zweiten (>=2.0.0 <3.0.0). Ändern Sie B auf 3.0.0 und sein Badge kippt auf erfüllt nicht — die obere Grenze <3.0.0 schließt es aus.

Um die Vorabversions-Regel in Aktion zu sehen, setzen Sie A auf 1.5.0-rc.1 und B auf 1.5.0, und belassen Sie den Bereich bei ^1.5.0-rc.0. Nun erfüllt A (dieselbe 1.5.0, der Bereich trägt ein passendes Vorabversions-Tag), während ein simples ^1.5.0 1.5.0-rc.1 nicht durchließe — die Schwelle existiert genau, um Release Candidates aus der Release-Abhängigkeitsauflösung herauszuhalten, bis Sie sich aktiv dafür entscheiden.

FAQ#

Ist 1.0.0 höher als 1.0.0-beta?#

Ja. Eine Version ohne Vorabversions-Tag hat immer höhere Präzedenz als eine mit Vorabversions-Tag, selbst bei identischem major.minor.patch. Also gilt 1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.11 > 1.0.0-alpha. Deshalb ist ein Release, das „gold geht“, ein echter Präzedenzsprung, nicht nur eine Etikettenänderung.

Was ist der Unterschied zwischen ^ und ~?#

Das Caret erlaubt Updates, die die am weitesten links stehende Nicht-Null-Komponente nicht verändern: ^1.2.3 erlaubt jedes 1.x.x ab 1.2.3 bis (aber nicht einschließlich) 2.0.0. Die Tilde ist strenger — sie pinnt die Minor-Version, wenn sie eine vollständige Version bekommt: ~1.2.3 erlaubt nur 1.2.x. Bei nur einer Major-Version (~1) erlauben Tilde und Caret beide den gesamten Major-Bereich. Die meisten Bibliotheken pinnen mit ^; Patches an eigenen veröffentlichten Paketen verwenden oft ~.

Warum erfüllt meine Vorabversion nicht ^1.0.0?#

Absichtlich. Eine Vorabversion wie 1.5.0-rc.1 erfüllt einen Bereich nur, wenn ein Komparator im selben UND-Satz ein Vorabversions-Tag auf derselben 1.5.0 trägt. ^1.0.0 löst sich zu >=1.0.0 <2.0.0-0 ohne Vorabversion auf 1.5.0 auf, sodass die Schwelle Ihren Release-Build davon abhält, irgendjemandes zufälligen Release Candidate hineinzuziehen. Wenn Sie sich einschalten wollen, schreiben Sie explizit ^1.5.0-rc.0.

Beeinflussen Build-Metadaten den Vergleich?#

Nein. 1.0.0+exp.sha.5 und 1.0.0+exp.sha.6 haben gleiche Präzedenz — Build-Metadaten dienen nur der Identifikation. Der Parser zeigt sie dennoch an (und die Änderung meldet ein build, wenn nur die Metadaten abweichen), aber sie entscheiden nie eine Reihenfolge.