Szimmetrikus verzió számozás

1.2.3 Adott egy verziószám, MAJOR.MINOR.PATCH, növeljük

1. a MAJOR verziószámot, ha a változtatásaink eredményeként elveszítjük a kompatibilitást a korábbi verzióval,
2. a MINOR verziószámot, ha olyan funkcionalitást adunk, ami megőrzi a visszafelé kompatibilitást, és
3. a PATCH verziószámot, ha visszafelé kompatibilis hibajavításokat adunk hozzá.

További verziócímkéket és kiadással kapcsolatos metaadatokat a MAJOR.MINOR.PATCH formátum kiegészítéseként lehet még hozzáadni.

A kulcsszavak “MUSZÁJ” vagy “KÖTELEZŐEN” (“MUST”), “NEM LEHET” vagy “NEM SZABAD” (“MUST NOT”), “AJÁNLOTT” (“SHOULD”), “NEM AJÁNLOTT” (“SHOULD NOT”), “VÁLASZTHATÓ(AN)” (“OPTIONAL”) ebben a dokumentumban úgy vannak használva, mint ahogyan itt le vannak írva: RFC 2119.

1. Szemantikus verziószámozást használó szoftvernek MUSZÁJ publikus API-t közzétennie. Ez az felület létezhet kizárólag dokumentáció formájában, vagy akár szoftverben meghatározva, de mindenféleképpen szükséges, hogy precíz és minden részletre kiterjedő legyen.
2. Az általános verziószám formátuma MUSZÁJ, hogy az X.Y.Z legyen, ahol az X, Y és Z a természetes számok halmazába tartoznak, kezdő nullák nélkül. X a “major”, Y a “minor” és Z a “patch” verziószám. Mindhárom MUSZÁJ, hogy számtanilag helyesen növekedjen. Például: 1.9.0 -> 1.10.0 -> 1.11.0.
3. Miután egy új csomagverzió forgalomba lett hozva, a csomag tartalma nem változhat. Bármilyen változás MUSZÁJ, hogy új verzióként legyen hozzáadva.
4. A nulladik “major” verzió (0.Y.Z) korai fejlesztésekre alkalmazható. Bárhol várhatóak változások a szoftverben és a publikus API-tól nem elvárható, hogy tökéletesen stabil legyen.
5. Az első verzió (1.0.0) definiálja a publikus API-t. Ezt követő verziószámok ennek az API-nak a változásától függnek.
6. A “patch”, Z verziószámot (x.y.Z | x > 0) MUSZÁJ növelni, amikor kizárólag hátrafele kompatibilis hibajavításokat adunk a szoftverhez. Ilyen hibajavítás definíciója egy olyan belső változás, ami addig hibás viselkedést korrigál.
7. A “minor”, Y verziószámot (x.Y.z | x > 0) MUSZÁJ növelni, amikor olyan új funkciókat adunk hozzá az API-hoz, ami a hátrafele kompatibilitást nem érinti. MUSZÁJ növelni, amikor korábbi funkciókat elavultként jelölünk meg. Növelni LEHET, amikor a új funkciók kerülnek a belső, privát kódbázisba. VÁLASZTHATÓAN tartalmazhat “patch” szintű változásokat is. A “patch” verziószám MUSZÁJ, hogy nullára csökkenjen amikor a “minor” verziószám növekszik.
8. A “major”, X verziószámot (X.y.z | X > 0) MUSZÁJ növelni, amikor visszafelé inkompatibilis változások vannak hozzáadva a nyilvános API-hoz. VÁLASZTHATÓAN tartalmazhat “patch” és “minor” szintű változásokat is. A “patch” és “minor” verziószámok MUSZÁJ, hogy nullára csökkenjenek amikor a “major” verziószám növekszik.
9. Egy kiadás előtti (“pre-release”) verzió VÁLASZTHATÓAN jelölhető egy kötőjelet követően pontokkal elválasztott azonosítókkal, közvetlenül a “patch” verzió után. Ezek az azonosítók MUSZÁJ, hogy kizárólag ASCII alfanumerikus karakterekből és kötőjelekből álljon. Azonosítók NEM LEHETNEK üresek. Számazonosítók NEM SZABAD, hogy nullával kezdődjenek. A kiadás előtti verziókhoz képest elsőbbséget élveznek a hozzátartozó normál verziók. Egy kiadás előtti verzió arra utal, hogy a verzió instabil és lehet, hogy nem elégíti ki a szándékozott kompatibilitási feltételeket amire a normál verzió utal. Például: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
10. Kiadással (“build”) kapcsolatos metaadatok VÁLASZTHATÓAN egy plusz jel hozzáadásával, majd pontokkal elválasztott azonosítókkal rögzíthetőek, közvetlenül a “patch” vagy kiadás előtti (“pre-release”) verzió után. Ezek az azonosítók MUSZÁJ, hogy kizárólag ASCII alfanumerikus karakterekből és kötőjelekből álljon. Azonosítók NEM LEHETNEK üresek. Számazonosítók NEM SZABAD, hogy nullával kezdődjenek. A kiadással kapcsolatos metaadatokat AJÁNLOTT figyelmen kívül hagyni a verziók elsőbbségének meghatározásakor. Ennélfogva két verzió, ami csupán kiadással kapcsolatos metaadatban különböznek egyenlő elsőbbséget élveznek. Például: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
11. Az elsőbbség arra utal, hogy hogy viszonyulnak egymáshoz a verziók, amikor sorrendbe vannak téve. Az elsőbbséget MUSZÁJ a “major”, “minor”, “patch” és “pre-release” alapján számolni, ebben a sorrendben (kiadással kapcsolatos metaadatok, “build-metadata” nincsenek beleszámítva). Az elsőbbségi sorrendet az első eltérő azonosító határozza meg amikor balról jobbra olvassuk a verziószámot, tehát ebben a sorrendben: “major”, “minor” és “patch”, és a különbség számtanilag értelmezhető. Például: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. Amikor a “major”, “minor” es “patch” verziószámok egyenlőek, a kiadás előtti (“pre-release”) verziónak kisebb elsőbbsége van. Például: 1.0.0-alpha < 1.0.0. Azonos normál verzióhoz tartozó, kiadás előtti (“pre-release”) verziók közötti elsőbbséget MUSZÁJ annak alapján meghatározni, hogy balról jobbra olvasva a ponttal elválasztott azonosítókat összehasonlítjuk karakterről karakterre. Számazonosítók számtanilag, alfanumerikus azonosítók ASCII alapján vannak sorrendbe rakva. Számazonosítóknak kisebb az elsőbbsége, mint a nem numerikus azonosítóknak. Amikor két “pre-release” verzió közötti különbség csak az, hogy az egyiknek az azonosítói pontosan megegyeznek a másikéval, de ezen felül még tartalmaz további azonosítókat is, akkor a több azonosítóval rendelkező verzió elsőbbséget élvez a másik felett. Például: 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 < 1.0.0.

Koncepció

Ez nem egy új vagy forradalmi koncepció. Sőt, valószínűleg valami ehhez hasonló rendszert alkalmazol. A gond az az, hogy a ‘hasonló’ az nem elég. Egy hivatalos előíráshoz való szigorú ragaszkodás nélkül a verziószámok gyakorlatilag teljesen hasztalanná válnak a függőségek számontartásában. Másrészről viszont, megfelelő előírások és szabályok közlése mellett jelentősen egyszerűbb kommunikálni a szándékaidat a szoftvered felhasználóinak. Ha ezek a törekvések egyértelműek, rugalmasak (de nem túl rugalmasak), a függőségi előírások megfogalmazhatóvá válnak.
Egy egyszerű példa bemutatja, hogy a Szemantikus Verziószámozás hogyan tüntetheti el az Függőségek Számontartásának Poklát. Vegyünk egy “Tűzoltóautó” nevű csomagot. Szüksége van egy szemantikusan verziózott csomagra: a “Létrá”-ra. Amikor a Tűzoltóautót létrehozták, a Létra verziója 3.1.0. Mivel a Tűzoltóautó olyan funkcionalitást használ, ami a 3.1.0-ban lett bevezetve, nyugodtan meg lehet nevezni a függőséget: egy verziószám, ami nagyobb vagy egyenlő mint 3.1.0, de kisebb mint 4.0.0. Amikor a Létranak a 3.1.1-es, illetve 3.2.0-ás verziói elérhetővé válnak, bevezethetőek a Tűzoltóautó csomag menedzsment rendszerébe is anélkül, hogy a kompatibilitást veszélyeztetné.
Felelős szoftverfejlesztőként természetesen igazolni akarod majd, hogy a csomagfrissítések megegyeznek az elvártakkal. A világ egy kaotikus hely és ezzel szemben csak óvatosak lehetünk. Amit tehetsz az az, hogy legalább a saját szoftverfejlesztésed és kiadásodat szabályozza a Szemantikus Verziószámozás úgy, hogy az attól függő csomagok minimálisan legyenek érintve, időt és erőfeszítést spórolva.
Ha ez kívánatosnak hangzik, mindössze annyit kell tenned, hogy kijelentsd, hogy használod a Szemantikus Verziószámozást és kövesd a szabályait. Linkeld ezt a honlapot a csomagod README-jébe, hogy mások is megismerjék a szabályokat és részesülhessenek az előnyeiben.