.. _Thema-SemanticVersioningFuerPublikationsprojekte: ############################################################################# Versionsnummern: *Semantic Versioning* für Publikationsprojekte (SemVersPub) ############################################################################# .. todo:: Versionsnummernschema (Semantic & Descriptive Versioning) .. Ohne Einhaltung irgendeiner Art von Spezifikation sind Versionsnummern nicht besonders hilfreich beim Verwalten von Versionen und Abhängigkeiten. Durch das Benennen und Aufstellen von Regeln wird es einfach, Anwender des Produkts über die Art und den Umfang der Änderungen zu informieren. ****************************************************************************** Die Versionsbezeichnung: Kurzfassung ****************************************************************************** Eine vollständige Versionsbezeichnung setzt sich aus drei bis 5 Teilen zusammen: #. **Hauptversionsnummer** (``MAJOR``, ``X``): Sie wird erhöht, wenn inkompatible Änderungen veröffentlicht werden. #. **Unterversionsnummer** (``MINOR``, ``Y``): Sie wird erhöht, wenn neue Funktionalitäten und Eigenschaften, welche kompatibel zu den bisherigen sind, veröffentlicht werden. #. **Korrekturversionsnummer** (``ERRATUM``, ``Z``): Sie wird erhöht, wenn die Änderungen ausschließlich kompatible Änderungen bzw. Korrekturen umfassen. #. **Vorveröffentlichungsbezeichner** (``PRE``, ``P``; optional): Er zeigt an, dass eine Version noch in Entwicklung ist und gibt den Entwicklungsstand an. #. **Herstellungs-Metadaten** (``META``, ``M``; optional): Sie dienen der Angabe von Informationen zum Produkt innerhalb der *selben* Version, z. B. verschiedene Varianten, Ausgabeformate oder Herstellungsweisen. Die ersten drei Teile (X, Y, Z) werden als *einfache Versionnummer* bezeichnet, die optionalen Bezeichner für Vorveröffentlichungen (``P``) und Herstellungs-Metadaten (``M``) sind als Erweiterungen möglich und ergeben zusammen mit der gewöhnlichen Versionsnummer die *erweiterte Versionsnummer*. .. admonition:: Formatschema ``MAJOR.MINOR.ERRATUM-PRE+META`` bzw. kurz: ``X.Y.Z-P+M`` Beispiele: ``3.2.0-beta+1ae2d`` ``3.2.0+Print``, ``3.2.0+Ebook`` .. _Thema-SemVersPubRegeln: ****************************************************************************** SemVersPub-Regeln ****************************************************************************** Kompatibilität ============================================================================== Der Begriff *Kompatibilität* wurde wesentlich in der Welt der Softwareentwicklung geprägt. Anders als in Softwareprojekten sind die Kriterien für Kompatibilität in Publikationsprojekten jedoch sehr relativ: Für den einen Anwender wäre schon eine Änderung der Seitenzahl, auf der bestimmte Inhalte zu finden sind, bei Druckwerten ein Bruch der Kompatibilität, schließlich würden ja dann Seitenreferenzierungen, z. B. in einem Skriptum, nicht mehr stimmen. Ein anderer Anwender mag vielleicht lediglich auf die Inhalte schauen, wobei auch auch hier nicht ganz klar ist, ob lediglich eine Änderung bestehender Inhalte, oder sogar ein bloßes hinzufügen von neuen Inhalten für ihn einen Kompatibilitätsbruch (Stichwort "Schulungsaufwand") darstellen. Daneben kann ein Projekt noch andere, für den Anwender wesentliche Eigenschaften aufweisen, welche bei Änderung zu einem Kompatibilitätbruch führen können. .. note:: Für Publikationsprojekte können keine allgemeingültigen Kriterien für die Kompatibilität erstellt werden, diese hängen wesentlich von der Art des Projektes, dessen wesentlichen Eigenschaften und dem Zielpublikum und dessen Erwartungen bzw. Anwendungsfällen ab. Es obliegt somit jedem Projekt definierte **Kriterien für die Kompatibilitätseinschätzung** zu erstellen und diese klar den Entwicklern und Anwendern zu kommunizieren. Gewöhnliche Versionsnummer ============================================================================== #. Eine **gewöhnliche Versionsnummer** muss dem Format ``X.Y.Z`` entsprechen, wobei ``X``, ``Y`` und ``Z`` Ganzzahlen größer oder gleich Null sind und eine Zahl größer als Null keine führenden Nullen enthalten darf (MUST). #. ``X`` ist die **Hauptversionsnummer** (**Major**\ -Version, ``MAJOR``) #. ``X`` ist die **Unterversionsnummer** (**Minor**\ -Version, ``MINOR``), #. ``Y`` ist die **Korrekturversionsnummer** (**Erratum**\ -Version, ``ERRATUM``). Jedes Element muss auf numerische Art und Weise erhöht werden (MUST). Zum Beispiel: ``1.9.0`` → ``1.10.0`` → ``1.11.0``. #. **Veröffentlichte Versionen sind unberührbar**: Sobald eine Version eines Projektes veröffentlicht wurde, darf der Inhalt dieser Version nicht mehr verändert werden (MUST NOT). Eine Änderung am Inhalt muss als eine neue Version veröffentlicht werden (MUST). #. Die **Hauptversionsnummer** (*Major-Version*, ``X``) muss immer dann erhöht werden, wenn *inkompatible* Änderungen eingeführt werden (MUST). Die Änderungen dürfen auch Änderungen umfassen, die ansonsten die Minor Version oder die Patch Version erhöht hätten (MAY). Wenn diese Versionsnummer erhöht wird, muss sowohl die Minor-Version als auch die Erratum-Version auf Null zurückgesetzt werden (MUST). #. Die **Unterversionsnummer** (*Minor-Version*, ``Y``) muss erhöht werden, wenn Änderungen, welche *kompatibel* sind, veröffentlicht werden (MUST). Sie muss außerdem erhöht werden, wenn ein Inhalt als veraltet oder obsolet markiert wird (MUST). Wenn umfangreiche Änderungen eingeführt werden, darf die Minor-Version ebenfalls erhöht werden (MAY). Wenn diese Versionsnummer erhöht wird, muss die Erratum-Version auf Null zurückgesetzt werden (MUST). #. Die **Korrekturversionsnummer** (*Erratum-Version*, ``Z``) muss erhöht werden, wenn ausschließlich *kompatible Fehlerbereinigungen* ("Bugfixes") eingeführt werden (MUST). Ein Korrektur ist als eine interne Änderung, welche einen Fehler korrigiert, definiert. #. Versionsnummern mit einer **Hauptversionsnummer von 0** (``0.y.z``) sind für die *initiale Entwicklungsphase* gedacht. Änderungen können in jeder denkbaren Form und zu jeder Zeit auftreten. Die Inhalte und Eigenschaften sollen nicht als stabil betrachtet werden. Die sonst gültigen Änderungskriterien für X, Y und Z gelten während der initialen Entwicklungsphase *nicht*. #. Die **Version 1.0.0** definiert die erste öffentliche, stabile Veröffentlichung. Ab dieser Veröffentlichung hängt die Art und Weise, wie die Versionsnummer erhöht und verändert wird, von den Inhalten oder wesentlichen Eigenschaften des Werkes und den Änderungen, die daran vollzogen werden, ab. .. index:: single: Vorveröffentlichungsbezeichner Vorveröffentlichungsbezeichner ============================================================================== Eine **Vorveröffentlichung** kann gekennzeichnet werden, indem ein Bindestrich, gefolgt von dem :index:`\ ` :dfn:`Vorveröffentlichungs-Bezeichner`, an die Patch Version angehängt wird (MAY). Der Vorveröffentlichungsbezeichner kann aus mehreren Elementen bestehen (MAY), welche durch Punkte (``.``) voneinander getrennt werden. Die Elemente des Bezeichners dürfen nur aus alphanumerischen *ASCII*\ -Zeichen und dem Bindestrich (``[0-9A-Za-z-]``) bestehen (MUST). Sie dürfen außerdem nicht leer sein (MUST NOT). Wenn ein Element ausschließlich aus Ziffern besteht, darf es keine führenden Nullen enthalten (MUST NOT). Eine Vorveröffentlichungs-Version hat einen niedrigeren Rang als die entsprechende reguläre Version. Ein Vorveröffentlichungs-Bezeichner kennzeichnet, dass die Version als *instabil* zu betrachten ist und dass sie unter Umständen nicht den Kompatibilitätsanforderungen, die für die entsprechende regulären Version bestimmt wurden, entspricht. Beispiele: ``1.0.0-alpha``, ``1.0.0-alpha.23``, ``1.0.0-0.3.7``, ``1.0.0-x.7.z.92`` .. index:: single: Herstellungs-Metadaten Herstellungs-Metadaten ============================================================================== **Herstellungs-Metadaten** können ausgezeichnet werden (MAY), indem ein **Plus-Symbol** (``+``), gefolgt von den Metadaten, an die Patch Version oder den Vorveröffentlichungs-Bezeichner angehängt wird (Herstellungs-Metadaten-Bezeichner). Die Herstellungs-Metadaten können mehrere Elemente enthalten (MAY), welche durch Punkte voneinander getrennt werden (MUST). Die Elemente der Metadaten dürfen nur aus alphanumerischen ASCII Zeichen und dem Bindestrich (``[0-9A-Za-z-]``) bestehen (MUST). Sie dürfen außerdem nicht leer sein (MUST NOT). Die Herstellungs-Metadaten haben keinerlei Einfluss auf den Rang einer Version, sodass zwei Versionen, deren Versionsnummern sich nur in den Build-Metadaten unterscheiden, denselben Rang einnehmen. Sie dienen der Angabe von Informationen zum Produkt innerhalb der *selben* Version, z. B. verschiedene Varianten, Kompilationen, Ausgabeformate oder Herstellungsweisen. Beispiele: ``1.0.0-alpha+Printausgabe``, ``1.0.0+OnlineEditition``, ``1.0.0-beta+exp.sha.5114f85`` Versionsvergleiche ============================================================================== #. Der *Rang* einer Version bestimmt, welche Versionsnummer einer anderen übergeordnet ist, wenn diese bei einer Sortierung miteinander verglichen werden. #. Der Rang wird aus der Major, Minor und Patch Version sowie dem Vorveröffentlichungs-Bezeichner berechnet (MUST). Etwaige Herstellungs-Metadaten haben dabei keinerlei Einfluss auf den Rang einer Version. Er wird bestimmt, indem der erste Unterschied zwischen dem oben aufgeführten Elementen ermittelt wird. Dabei wird *von links nach rechts*, in der oben genannten Reihenfolge, vorgegangen. #. Die Major, Minor und Patch Versionen werden numerisch miteinander verglichen. Beispiel: ``1.0.0`` < ``2.0.0`` < ``2.1.0`` < ``2.1.1`` #. Beim Vergleich von zwei Versionsnummern, deren Major-, Minor- und Erratum-Versionen gleich sind, nimmt eine Vorveröffentlichung einen niedrigeren Rang als die reguläre Version ein. Beispiel: ``1.0.0-alpha`` < ``1.0.0`` #. Sind beide dieser Versionen Vorveröffentlichungen, wird (MUST) der Rang ermittelt, indem jedes Element eines Vorveröffentlichungs-Bezeichners (durch Punkte voneinander getrennt) mit dem der anderen Version verglichen wird bis ein Unterschied festgestellt wird. Auch hierbei wird von links nach rechts vorgegangen. #. Elemente, welche ausschließlich aus Ziffern bestehen, werden *numerisch* miteinander verglichen. Der Vergleich aller anderen Elemente erfolgt auf Basis der *ASCII-Stellenwerte* ihrer Zeichen. #. Numerische Elemente haben immer einen niedrigeren Rang als solche, die auch andere Zeichen enthalten. #. Falls alle Elemente identisch sind, nimmt der Bezeichner mit den meisten Elementen den höheren Rang ein. Beispiel: ``1.0.0-alpha`` < ``1.0.0-alpha.1`` < ``1.0.0-alpha.beta`` < ``1.0.0-beta`` < ``1.0.0-beta.2`` < ``1.0.0-beta.11`` < ``1.0.0-rc.`` < ``1.0.0`` ****************************************************************************** FAQ ****************************************************************************** .. rubric:: Wie soll ich bei der Versionierung in der initialen Development Phase (0.y.z) verfahren? Das Einfachste ist, die Versionierung bei 0.1.0 zu beginnen und dann bei jedem folgender Veröffentlichung die Minor Version zu erhöhen. .. rubric:: Woher weiß ich, wann es Zeit ist Version 1.0.0 zu veröffentlichen? Wenn das Projekt schon in der Produktion verwendet wird, sollte sie bereits in Version 1.0.0 vorliegen. Falls ein stabiler Inhalt existiert, auf den sich Nutzer bereits verlassen, sollte es ebenfalls die Version 1.0.0 sein. Auch wenn Kompatibilität zu vorherigen Versionen bereits eine wichtige Rolle spielt, ist Version 1.0.0 angebracht. .. rubric:: Hält das nicht von Rapid Development und Fast Iteration ab? In Versionen mit einer Major Version von Null dreht sich alles um Rapid Development. Wenn sich der Inhalt tagtäglich verändert, sollte sich das Projekt entweder noch in Version 0.y.z befinden oder es sollte auf einem separate Entwicklungszweig an der nächsten Major-Version/Veröffentlichung gearbeitet werden. .. rubric:: Wenn schon die kleinsten Inhalts-inkompatible Änderung eine Anhebung der Major Version erfordern, wird eine Version wie 42.0.0 nicht sehr schnell erreicht werden? Das ist eine Frage von verantwortungsbewusster Entwicklung und Weitsicht. Inhalts-inkompatible Änderungen sollten nicht leichtfertig eingeführt werden, da das Aktualisieren in Konzepten von Dritten mit drastischem Aufwand verbunden sein kann. Die Tatsache, dass die Major Version beim Einführen von Inhalts-inkompatiblen Änderungen angehoben werden muss, drängt einen dazu, die Auswirkungen der Änderungen und deren Zeitpunkt der Einführung, noch einmal zu überdenken und das Kosten-Nutzen-Verhältnis abzuwägen. .. rubric:: Was soll ich tun wenn ich versehentlich eine Inhalts-inkompatible Änderung in einer Minor Version veröffentlicht habe? Sobald du feststellst, dass du die Semantic Versioning Spezifikation nicht befolgt hast, korrigiere den Fehler, indem du eine neue Minor Version veröffentlichst, welche das Problem behebt und die Kompatibilität zum Inhalt wiederherstellt. Selbst unter diesen Umständen ist es nicht erlaubt, eine bereits veröffentlichte Version zu verändern. Falls es angemessen ist, *dokumentiere* welche Version problematisch ist, sodass die *Nutzer* über diese Version *Bescheid* wissen. .. rubric:: Ist die Länge einer Versionsbezeichnung limitiert? Nein, aber sei vernünftig. Zum Beispiel, wäre ein 255 Zeichen langer Version String wahrscheinlich ein wenig übertrieben. Außerdem könnten bestimmte Systeme ihre eigenen Limits definieren. ****************************************************************************** Credits ****************************************************************************** Diese Spezifikation basiert auf `Semantic Versioning 2.0.0 `_ von `Tom Preston-Werner `_\ , , Erfinder von Gravatars und Mitbegründer von GitHub (`Creative Commons - CC BY 3.0 `_\; modifiziert). Die Terme “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, und “OPTIONAL” in diesem Dokument sind, wie in :rfc:`2119` beschrieben, zu interpretieren.