V čísle verzie vo formáte MAJOR.MINOR.PATCH zväčšujeme číslo:
Značenie predbežných verzií a pridávanie metadát verzií je možné rozšírenímspomínaného formátu MAJOR.MINOR.PATCH o potrebné informácie.
Vo svete softvéru, jeho vývoja a správy existuje hrozné miesto nazývané peklozávislostí(angl. dependency hell). Znamená to, že čím viac váš systém rastiea máte v ňom integrovaných čoraz viac knižníc, tým je väčšia pravdepodobnosť,že sa, kompletne zúfalí, v tomto pekle sami ocitnete.
Ak majú systémy veľa závislostí, raz-dva sa vám stane, že vydávanie novej verzie sastane nočnou morou. Ak je špecifikácia závislostí príliš striktná, hrozí vám, žeostanete na jednej verzii(angl. version lock) a nebudete mať možnosť prejsťna ďalšiu verziu bez toho, aby ste vydali ďalšie verzie všetkých balíčkov, naktorých závisí. Naopak, ak je špecifikácia závislostí príliš voľná, prídete nato, že váš systém je kompatibilný s viac verziami, ako je potrebné. V peklezávislostí sa nachádzate, ak ste zviazaný určitou verziou, prípadne nie je presnešpecifikované, ktorú máte použiť. Jednoducho, bráni vám to v tom, aby ste sa sosvojim projektom pohli bezpečne vpred.
Riešením tohto problému je jednoduchý súbor pravidiel, ktorýurčuje, ako budú čísla verzií priraďované a zväčšované. Tieto pravidlá súzaložené (no nie nevyhnutne obmedzené) na už existujúcich bežne zaužívanýchpraktikách vo vývoji otvoreného, či uzavretého softvéru. Pre fungovanietohto systému si musíte najskôr zadefinovať rozhranie popisujúce spôsob,akým sa bude komunikovať s vaším systémom (ďalej len API). Môže byť zadefinovanéformou dokumentácie, prípadne vynútené samotným kódom. Bez ohľadu na formu akouto bude, jedôležité aby toto API bolo presné a jasné. Akonáhle budete mať zadefinované vašeAPI, jeho zmeny budete oznamovať špecifickým zväčšením čísla verzie vášhosystému. Uvažujme, že číslo verzie bude vo formáte MAJOR.MINOR.PATCH. Opravychýb, ktoré nemenia vaše API, zväčšujú číslo PATCH verzie. Spätne kompatibilnézmeny API zväčšujú číslo MINOR verzie a spätne nekompatibilné zmeny API zväčšujúčíslo MAJOR verzie.
Tento systém je nazývaný Sémantické verziovanie. Čísla verzií v tomto systéme aspôsob, akým sa menia nesú so sebou informáciu o použitom kóde a zmenách medzijednotlivými verziami.
Kľúčové slová “MUSÍ”(angl. MUST, REQUIRED, SHALL), “NESMIE”(angl. MUST NOT,SHALL NOT), “MALO BY”(angl. SHOULD, RECOMMENDED), “NEMALO BY”(angl. SHOULDNOT) a “MÔŽE”(angl. MAY, OPTIONAL) sú interpretovené ako je popísanév dokumenteRFC 2119.
Softvér používajúci Sémentické verziovanie MUSÍ mať zadefinované API. Toto APImôže byť definované priamo v kóde, prípadne môže existovať v dokumentácii. Nechuž to je tak alebo onak, malo by byť presné a komplexné.
Normálne číslo verzie MUSÍ byť vo formáte X.Y.Z, kde X, Y a Z sú nezápornécelé čísla a NESMÚ obsahovať úvodné nuly. X je číslo MAJOR verzie, Y je čísloMINOR verzie a Z je číslo PATCH verzie. Každé z týchto čísel sa musí zväčšovaťštandardne. Napr.: 1.9.0 -> 1.10.0 -> 1.11.0.
Akonáhle je takto očíslovaná verzia vydaná, softvér pod číslom tejto verzieuž NESMIE byť modifikovaný a každá zmena MUSÍ byť vydaná ako nová verzia.
MAJOR verzia s číslom 0 (0.y.z) je pre začiatočný vývoj. Čokoľvek sa môžezmeniť a API takto očíslovanej verzie by nemalo byť považované za stabilné.
Verzia 1.0.0 už presne definuje API. Spôsob, akým sa po vydaní takejto verziemení číslo verzie je závislý na tomto API a jeho zmenách.
Číslo PATCH verzie Z (x.y.Z | x > 0) MUSÍ byť zväčšené len vtedy, akboli implementované spätne kompatibilné opravy chýb. Oprava chyby je definovanáako interná zmena opravujúca nežiadúce chovanie.
Číslo MINOR verzie Y (x.Y.z | x > 0) MUSÍ byť zväčšené, ak bola do APIpridaná nová, spätne kompatibilná funkcionalita a tiež MUSÍ byť zväčšené, akbola nejaká funcionalita označená ako zastaralá. MÔŽE tiež byť zväčšené, ak bolapridaná alebo vylepšená podstatná funkcionalita v rámci kódu, ktorýneovplyvňuje API. MÔŽE zahrnúť aj zmenu v rámci PATCH verzie. Číslo PATCH verzieMUSÍ byť nastavené na 0 vždy, keď sa zmení číslo MINOR verzie.
Číslo MAJOR verzie X (X.y.z | X > 0) MUSÍ byť zväčšené, ak boli pridanézmeny, ktoré spôsobili, že API nie je spätne kompatibilné. MÔŽE zahrnúť aj zmenuv rámci MINOR a PATCH verzie. Číslo MINOR aj PATCH verzie MUSÍ byť nastavené na 0vždy, keď sa zmení číslo MAJOR verzie.
Predbežná verzia(angl. pre-release) MÔŽE byť označená pridaním pomlčkya sériou identifikátorov oddelených bodkou, hneď za číslo PATCH verzie.Identifikátory MUSIA obsahovať len ASCII alfanumerické znaky a pomlčku[0-9A-Za-z-], NESMÚ byť prázdne a číselné identifikátory NESMÚ obsahovať úvodnénuly. Predbežné verzie majú nižšiu prioritu ako súvisiace normálne verzie.Predbežná verzia je nestabilná a nemusí spĺňať požiadavky a závislosti akosúvisiaca normálna verzia. Napr.: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7,1.0.0-x.7.z.92.
Metadáta MÔŽU byť označené vo verzii pridaním znaku plus (+) a sériouidentifikátorov oddelených bodkou, hneď za číslo PATCH alebo predbežnej verzie.Identifikátory MUSIA obsahovať len ASCII alfanumerické znaky a pomlčku[0-9A-Za-z-], NESMÚ byť prázdne a číselné identifikátory NESMÚ obsahovať úvodnénuly. Metadáta by MALI BYŤ ignorované pri rozhodovaní o priorite verzie, a tedadve verzie, ktoré sa líšia len v metadátach majú rovnakú prioritu.Napr.: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
Priorita sa vzťahuje k tomu, ako sú verzie navzájom porovnávané. PrioritaMUSÍ byť určovaná rozdelením verzie na MAJOR, MINOR, PATCH a identifikátorypredbežných verzií ― presne v takomto poradí (s metadátami sa nepočíta).Priorita je daná prvým rozdielom pri porovnávaní zľava doprava pričom číslaMAJOR, MINOR a PATCH sú porovnávané vždy ako čísla. Napr.: 1.0.0 < 2.0.0 <2.1.0 < 2.1.1. Keď sú čísla MAJOR, MINOR a PATCH rovnaké, predbežná verzia mámenšiu prioritu ako normálna. Napr.: 1.0.0-alpha < 1.0.0. Priorita pre dvepredbežné verzie, ktoré sa zhodujú v číslach MAJOR, MINOR a PATCH MUSÍ byťpočítaná z bodkou oddelených identifikátorov zľava doprava a to dovtedy, pokým sa nenájde rozdiel nasledovným spôsobom: (1) Identifikátory obsahujúceiba číslice sú porovnávané číselne a identifikátory s písmenami alebo pomlčkamisú porovnávané lexikálne, zoradené podľa ASCII. (2) Číselné identifikátory majúvždy nižšiu prioritu ako nečíselné. (3) Ak sú všetky predchádzajúceidentifikátory v predbežnej verzii rovnaké, tak väčšie množstvo identifikátorovznačí vyššiu prioritu ako menšie množstvo. Napr.: 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.
Sémantické verziovanie nie je revolučná myšlienka a ak vydávate softvér,pravdepodobne robíte niečo podobné. Problémom je, že “niečo podobné” nestačí.Bez dodržiavania akejsi formálnej špecifikácie sú čísla pre manažment závislostív podstate nanič. Tým, že hore uvedeným myšlienkam dávame presnú a jasnúdefiníciu, je ľahšie komunikovať zámery vášho softvéru jeho používateľom.Akonáhle sú zámery jasné a flexibilné (ale nie príliš), špecifikácia závislostímôže začať.
Jednoduchým príkladom demonštrujeme, že peklo závislostí môže byť pre vás ľahkominulosťou. Predstavte si, že máte knižnicu Hasičské auto. Táto knižnicavyžaduje sémanticky verziovanú knižnicu Rebrík. V čase, kedy je Hasičské autovytvorené, verzia Rebríka je 3.1.0. Keďže Hasičské auto používa funkcie,ktoré boli pridané vo verzii 3.1.0, môžete bezpečne špecifikovať, že potrebujeteverziu Rebríka väčšiu alebo rovnú 3.1.0, no menšiu ako 4.0.0. A potom, keď vyjdenová verzia Rebríka 3.1.1 alebo 3.2.0, môžete ju použiť vo vašom Hasičskom autea budete vedieť, že je s ním kompatibilná.
Ako zodpovední developeri si určite budete chcieť skontrolovať, či všetkofunguje podľa predpokladov. V skutočnosti je však všade neporiadok; tam námpomôže iba dávať si pozor. Čo však môžete spraviť je nechať Sémantickéverziovanie aby vám umožnilo rozumný spôsob ako vydávať a aktualizovaťknižnice tak, aby ste nemuseli riešiť nové verzie závislostí, ušetrili časa vyhli sa zmätkom.
Ak to znie rozumne, všetko čo potrebujete spraviť pre začatie používaniaSémantického verziovania je povedať, že to robíte a následne dodržiavať pravidlá.Odkážte z README vášho softvéru na tieto stránky, nech aj ostatní vedia, aképravidlá používate a majú z nich prospech.
Najjednoduchším spôsobom je začať vývoj na verzii 0.1.0 a potom zväčšovať MINORverziu pri každom ďalšom vydaní softvéru.
Ak sa váš softvér už používa v produkcii, už by pravdepodobne mal mať verziu1.0.0. Ak máte stabilné API, ktoré už používatelia majú medzi svojimizávislosťami, mali by ste mať verziu 1.0.0. Taktiež, ak sa obávate o spätnúkompatibilitu, už by ste mali mať 1.0.0.
MAJOR verzia nula je o rýchlom vývoji. Ak každý deň meníte API, stále by stemali byť niekde vo fáze 0.x.y alebo na separátnej vývojovej vetve, kde sapripravuje nasledujúca MAJOR verzia.
To je otázka zodpovedného vývoja a prognóz. Nekompatibilné zmeny by nemali byťdo softvéru, ktorý má veľa závislostí zavádzané len tak. Náklady vynaložené naaktualizáciu môžu byť dosť veľké. To, že musíte vydať novú MAJOR verziu znamená,že ste si dobre premysleli dopad vašich zmien a zrátali aké to bude mať výhodya následky.
Je vašou zodpovednosťou, ako profesionálnych developerov, správne dokumentovaťsoftvér, ktorý je určený na používanie aj pre ostatných. Spravovanie zložitostisoftvéru je veľmi dôležitá časť, ak chcete projekt udržať efektívny. A to nebudemožné, ak nikto nebude vedieť ako váš softvér používať alebo ktoré metódy jebezpečné volať. Z dlhodobého hľadiska sa Sémantické verziovanie a dôraz na dobredefinované API ukázali ako správna voľba umožňujúca bežať veciam hladko.
Akonáhle zistíte, že ste porušili pravidlá Sémantického verziovania, opravteproblém a vydajte ďalšiu MINOR verziu, ktorá opäť vráti spätnú kompatibilitu.Napriek takejto situácii, je neprípustné aby ste menili už vydanú verziu. A akje to možné a vhodné, informujte používateľov o zlej verzii, aby vedeli, že sajedná o chybu a danej verzii sa vyhli.
Môžeme to považovať za kompatibilné, keďže to nijako neovplyvnilo API. Softvér,ktorý presne závisí na balíčkoch ako váš, by mal mať vlastnú definíciuzávislostí a autor si všimne akékoľvek konflikty. Rozhodnutie, či sa jedná oMINOR alebo PATCH závisí od toho, či ste upravili vaše závislosti kvôli nejakejchybe alebo preto, že ste pridali novú funkcionalitu. Ak sa jedná o druhýprípad, zvyčajne tam bude aj nejaký kód, a tak sa jedná o zväčšenie MINORverzie.
Usúďte, čo je najlepšie. Ak máte veľkú skupinu používateľov, ktorá by bolaovplyvnená zmenou späť, tak asi bude najlepšie vydať MAJOR verziu, napriek tomu,že oprava späť by mala byť súčasťou PATCH verzie. Pamätajte, že Sémantickéverziovanie je o tom, ako sa verzie menia. Ak sú zmeny pre vašich používateľovdôležité, použite také číslo verzie, aby ste ich informovali.
Označenie funcionality ako zastaralej je štandardná časť softvérového vývojaa väčšinou je žiadané ísť vpred, takže k tomu jednoducho dôjde. Keď zastarávatečasť svojho API, mali by ste spraviť dve veci: (1) upraviť dokumentáciu abypoužívatelia vedeli o zmene, (2) vydať ďalšiu MINOR verziu, ktorá funcionalituzastaráva. A teda, predtým ako funkcionalitu kompletne odstránite v ďalšejMAJOR verzii, mali by ste spraviť aspoň jednu MINOR verziu, ktorá obsahujezastaranie a používatelia mohli ľahko prejsť na nové API.
Nie, no použite zdravý rozum. Číslo verzie, ktoré má 255 znakov je už asi moc,no špecifické systémy môžu mať vlastné limity na dĺžku čísla verzie.
Autorom špecifikácie sémantického verziovania jeTom Preston-Werner, autor projektu Gravatar aspoluzakladateľ projektu Github.
Ak chcete zanechať spätnú väzbu, prosímcez GitHub.
Vladimír Kriška (autor),Tibor Soviš (korektor),Peter Dulačka (korektor),Jaroslav Brtiš (korektor)