Uzevši oznake verzije VEĆA.MANJA.ZAKRPA, inkrementirajte:
Dodatne oznake za pred-izdanja i metapodatkebuilda mogu se koristiti kao proširenje na VEĆA.MANJA.ZAKRPA format.
U svijetu upravljanja softverom postoji strašno mjesto koje zovemo“pakao ovisnosti.” Što više vaš sustav raste i što više paketaintegrirate u vaš softver, vjerojatnije je da ćete se, jednoga dana,naći u toj jami očaja.
U sustavima s više ovisnosti, izdavanje novih verzija paketa, može se vrlo brzopretvoriti u noćnu moru. Ako su specifikacije ovisnosti previše stroge, postojiopasnost zaključavanja verzije (nemogućnosti nadogradnje paketa bez potrebeizdavanja nove verzije svakog ovisnog paketa). Ako su pak ovisnosti specificiranepreviše slobodno, sigurno ćete osjetiti posljedice verzijskog promiskuiteta(pretpostavke kompatibilnosti s više budućih verzija nego što je razumno).Pakao ovisnosti je slučaj gdje zaključavanje verzije i/ili verzijski promiskuitetsprječavaju lagano i sigurno napredovanje projekta.
Kao rješenje tog problema predlažem jednostavan set pravila i zahtjevakoji će nalagati kako se dodjeljuju i inkrementiraju oznake verzija.Ova se pravila temelje, no nisu nužno i ograničena, na već postojećoji raširenoj uobičajenoj praksi u projektima otvorenog i zatvorenog koda.Kako bi ovaj sustav funkcionirao, potrebno je prvo objaviti javni API. Možemoto primijeniti u dokumentaciji ili u samom kodu. U svakom slučaju, važno je daAPI bude jasan i precizan. Jednom kad identificiramo javni API, komuniciramopromjene u njemu kroz specificirane inkrementacije u oznake/broja verzije.Uzmimo format verzije X.Y.Z (VEĆA.MANJA.ZAKRPA). Ispravcibugova koji ne utječuna API inkrementiraju oznaku zakrpe, unatrag-kompatibilni dodaci/promjene uAPIju inkrementiraju manju verziju, a unatrag inkompatibilne promjene u APIjuinkrementiraju veću verziju.
Ovaj sam sustav nazvao “Semantičko verzioniranje”. Unutar ove sheme, oznakeverzije i način na koji se mijenjaju prenose određene informacije o kodu kojise nalazi ispod i što se mijenjalo od jedne do druge verzije.
Ključne riječi “MORA”, “NE SMIJE”, “POTREBNO”, “BITI ĆE”, “NEĆE BITI”, “TREBALO BI”,“NE BI TREBALO”, “PREPORUČENO”, “MOŽE”, i “OPCIONALNO” (“MUST”, “MUST NOT”,“REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”,“OPTIONAL”) u ovom dokumentu treba interpretirati kao što je opisano uRFC 2119.
Softver koji koristi Semantičko verzioniranje MORA objaviti javni API. APImože biti deklariran u samom kodu ili postojati samo unutar dokumentacije.U svakom slučaju, mora biti precizan i jasan.
Normalna oznaka verzije MORA biti u formatu X.Y.Z gdje su X, Y i Z ne-negativnicijeli brojevi i ne smiju počinjati s nulom. X označava veću verziju, Y manjuverziju, a Z zakrpu. Svaki se element MORA numerički povećavati.Na primjer: 1.9.0 -> 1.10.0 -> 1.11.0.
Jednom kad je verzionirani paket izdan, sadržaj te verzije NE SMIJE semijenjati. Sve promjene MORAJU se izdavati s novom verzijom.
Veća verzija nula (0.y.z) je za inicijalni razvoj. Bilo što se može mijenjatiu tom stadiju. Javni API se ne smatra stabilnim.
Verzija 1.0.0 definira javni API. Način na koji će se oznaka verzijeinkrementirati ovisi o tom javnom APIju i načinu na koji se on mijenja.
Oznaka verzije zakrpe Z (x.y.Z | x > 0) MORA se inkrementirati samo ako sedodaju unatrag kompatibilni ispravcibugova. Ispravcibugova definiraju se kaopromjene unutar koda koje ispravljaju nepravilno ponašanje.
Oznaka manje verzije Y (x.Y.z | x > 0) MORA se inkrementirati ako se javnomAPIju dodaju nove unatrag kompatibilne funkcionalnosti. Također se MORAinkrementirati ako se neke funkcionalnosti označe kao zastarjele (deprecated).MOŽE se inkrementirati ako se uvode značajne nove funkcionalnosti ili poboljšanjaunutar koda. MOŽE se inkrementirati ako se uvode promjene na razini zakrpe. Kadase oznaka manje verzije inkrementira, oznaka verzije zakrpe mora se vratiti na 0.
Oznaka veće verzije X (X.y.z | X > 0) MORA se inkrementirati ako se javnomAPIju dodaju unatrag inkompatibilne funkcionalnosti. MOŽE sadržavati promjene narazini manje verzije i zakrpe. Kada se oznaka veće verzije inkrementira, oznakemanje verzije i zakrpe moraju se vratiti na 0.
Verzija predizdanja MOŽE se označiti dodavanjem crtice i niza identifikatoraodvojenih točkom, koji se odmah nastavljaju na oznaku verzije zakrpe. Ti seidentifikatori MORAJU sastojati samo od ASCII alfanumeričkih znakova i crtica[0-9A-Za-z-]. Identifikatori NE SMIJU biti prazni. Numerički identifikatori NESMIJU počinjati nulom. Normalne verzije imaju prednost nad vezanim verzijamapredizdanja. Oznaka verzije predizdanja označava nestabilnu verziju koja nezadovoljava nužno predviđene zahtjeve kompatibilnosti navedene u vezanojnormalnoj verziji. Primjeri: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7,1.0.0-x.7.z.92.
Metapodacibuilda MOGU se označiti dodavanjem znaka plus i niza identifikatoraodvojenih točkom, koji se odmah nastavljaju na oznaku verzije zakrpe ilipredizdanja. Ti se identifikatori MORAJU sastojati samo od ASCII alfanumeričkihznakova i crtica [0-9A-Za-z-]. Identifikatori NE SMIJU biti prazni. Metapodacibuilda se ignoriraju kod procjene prednosti verzije. Dakle, dvije verzije kojese razlikuju samo u metapodacimabuilda imaju jednaku prednost. Primjeri:1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
Pojam prednosti odnosi se na to kako uspoređujemo verzije u poretku.Prednost se MORA procjenjivati tako da zasebno promatramo oznaku verzije kaoveću, manju, zakrpu i identifikatore predizdanja tim redom. (Metapodacibuildane utječu na prednost). Prednost određuje prva razlika u usporedbi svakeoznake s lijeva na desno na sljedeći način: Oznake veće verzije, manje verzije iverzije zakrpe uvijek se uspoređuju numerički. Na primjer: 1.0.0 < 2.0.0 <2.1.0 < 2.1.1. Kad su oznake veće, manje i verzije zakrpe jednake, normalnaverzija ima prednost nad verzijom predizdanja. Primjer: 1.0.0-alpha < 1.0.0.Prednost između dvije verzije predizdanja s istim oznakama veće, manje i verzijezakrpe MORAJU se odrediti usporedbom svake oznake odvojene točkom s lijeva nadesno, dok ne dođemo do razlike na sljedeći način: identifikatori koji sesastoje samo od broja uspoređuju se numerički, dok se slova i crtice uspoređujuleksički u ASCII poretku. Nebrojčane oznake uvijek imaju prednost nad brojčanim.Veći niz oznaka predizdanja ima prednost nad manjim nizom, ako su prethodneoznake jednake. Primjer: 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.
Ovo nije nova, niti revolucionarna ideja. Štoviše, vjerojatno već koristitenešto vrlo slično. Problem je u tome što “slično” nije dovoljno dobro. Bezpoštivanja neke formalne specifikacije, oznake verzije su u suštini beskorisneza upravljanje ovisnostima. Ako damo ime i jasnu definiciju gore navedenimidejama, postaje lakše iskomunicirati svoje namjere korisnicima softvera.Jednom kada su te namjere jasne i fleksibilne (ali ne previše fleksibilne)možemo definirati specifikacije ovisnosti.
Možemo jednostavnim primjerom pokazati kako Semantičko verzioniranje možeostaviti pakao ovisnosti u prošlosti. Zamislitelibrary “Vatrogasno_vozilo.”Potreban joj je Semantički verzionirani paket “Ljestve”. U trenutku kad je“Vatrogasno_vozilo” kreirano, “Ljestve” su na verziji 3.1.0. Budući da“Vatrogasno_vozilo” koristi određene funkcionalnosti koje su uvedene u verziji3.1.0, možete bez straha navesti ovisnost o paketu “Ljestve” verzije veće ilijednake 3.1.0, ali manje od 4.0.0. Tako, kada “Ljestve” verzije 3.1.1 i 3.2.0budu dostupne, možete ih dodati u svoj sustav upravljanja paketima i bitisigurni da će biti kompatibilne s postojećim ovisnim softverom.
Kao odgovoran programer htjet ćete se, naravno, uvjeriti da će svaka nadogradnjapaketa funkcionirati kao što je navedeno. Stvarni je svijet zbrka i ne možemoništa poduzeti po tom pitanju osim biti oprezni. Ono što možete napraviti jeprihvatiti Semantičko verzioniranje kao siguran način za izdavanje i nadogradnjupaketa bez potrebe za izgradnjom novih verzija ovisnih paketa te tako sačuvativrijeme i živce.
Ako vam ovo sve dobro zvuči, sve što vam je potrebno da bi ste počeli koristitiSemantičko verzioniranje je da navedete da ga koristite i slijedite pravila.Stavite poveznicu na ovu stranicu u svoju README datoteku, kako bi i ostali bilisvjesni pravila i mogli imati koristi od njih.
Najjednostavniji je način da započnete inicijalni razvoj izdavanjem verzije0.1.0 te inkrementirate oznaku manje verzije za svako sljedeće izdanje.
Ako se softver koristi u produkciji, već bi vjerojatno trebao biti na verziji1.0.0. Ako već imamo stabilni API, na koji korisnici mogu računati, trebao bibiti na verziji 1.0.0. Ako ste zabrinuti zbog kompatibilnosti unatrag, softverbi već trebao biti izdan pod verzijom 1.0.0.
Veća verzija nula se svodi na brzi razvoj. Ako mijenjate API svaki dan, trebalibi ostati na verziji 0.y.z ili na posebnoj grani raditi na sljedećoj većojverziji.
Ovo je pitanje odgovornog razvoja i predviđanja. U softver koji ima punoovisnog koda, inkompatibilne promjene potrebno je uvoditi postupno. Cijenanadogradnje može biti značajna. Ako morate povećati veću verziju, kako bisteizdali verziju s inkompatibilnim promjenama, morate razmisliti o posljedicamatih promjenama i procijeniti odnos cijene i koristi.
Vaša je odgovornost kao profesionalnih programera da ispravno dokumentiratesoftver koji je namijenjen korisnicima. Upravljanje složenosti softvera vrloje važno kako biste projekt održali efikasnim, što je teško ako korisnici neznaju kako koristiti vaš softver ili koje metode mogu zvati. Semantičkoverzioniranje i kvalitetno definirani Semantički verzionirani javni API osiguratće da sve funkcionira kako treba.
Čim primijetite da ste prekršili specifikaciju Semantičkog verzioniranja,potrebno je ispraviti pogrešku te izdati manju verziju koja će ispraviti problemi vratiti kompatibilnost. Čak i u takvim uvjetima, nije prihvatljivo mijenjativerzionirana izdanja. Ako je prikladno, dokumentirajte verziju koja kršispecifikaciju te informirajte korisnike kako bi je bili svjesni.
Takve promjene smatramo kompatibilnima jer ne utječu na javni API. Softver kojieksplicitno ovisi o istim ovisnostima kao i vaš paket treba imati vlastitespecifikacije ovisnosti, a autor će se brinuti o konfliktima. Je li promjenana razini zakrpe ili manje verzije, ovisi o tome jeste li dodali ovisnostikako bi ispravilibug ili dodali nove funkcionalnosti. U posljednjem slučajumožemo očekivati i dodatni kod, pri čemu se očito radi o novoj manjoj verziji.
Pokušajte najbolje prosuditi sami. Ako imate velik broj korisnika, na koje ćeznačajno utjecati promjena unatrag, najbolje je da objavite veću verziju, iakobi takav ispravak mogli smatrati izdanjem zakrpe. Upamtite, poanta Semantičkogverzioniranja je dodavanje značenja promjenama oznake verzije. Ako su takvepromjene bitne korisnicima koristite oznake verzije kako biste ih informirali.
Postojeće funkcionalnosti koje zastarijevaju, uobičajeni su dio razvoja softverai često su potrebne kako bi razvoj napredovao. Kad označavate dio javnog APIjakao zastarjeli (deprecated), potrebno je učiniti dvije stvari: (1) ažuriratidokumentaciju kako bismo informirali korisnika, (2) izdati novu manju verzijus definiranim zastarjelim (deprecated) dijelovima softvera. Prije nego potpunouklonite zastarjele funkcionalnost u novoj većoj verziji, potrebno je izdatibarem jednu manju verziju koja sadrži zastarjele (deprecated) dijelove, kakobi korisnici glatko prešli na novu verziju APIja.
Ne, ali budite razumni. Oznaka verzije od 255 znakova je vjerojatno pretjerana,na primjer. Također, neki sustavi mogu imati svoja ograničenja veličine oznake.
Autor specifikacije Semantičkog Verzioniranja jeTomPreston-Werner, izumitelj Gravatara i suosnivačGitHuba.
Ako želite ostaviti povratne informacije, molimootvorite issue naGitHubu.