Dane številke verzij GLAVNA.MANJŠA.POPRAVEK povečajte:
Dodatne oznake za pred-izdaje in metapodatki gradnje so na voljo kot razširitve v obliki GLAVNA.MANJŠA.POPRAVEK.
V svetu programske opreme obstaja grozen prostor imenovan“pekel odvisnosti”. Večji kot sistem zraste in več je paketov,ki jih integrirate v vašo programsko opremo, bolj možno se boste našli nekegadne v tem obupu.
V sistemih z veliko odvisnostmi lahko izdaja nove verzije paketa hitropostane nočna mora. Če so specifikacije odvisnosti preveč ozke, ste vnevarnosti zaklenjenih verzij (nezmožnost nadgradnje paketa brez, daizdajate nove verzije za vsak odvisni paket). Če so odvisnostidoločene preveč ohlapno, boste neizogibno ugriznjeni s strani promiskuitete verzije(ob predpostavki, da je združljivost z večimi prihodnjimi verzijami razumna).Pekel odvisnosti je, kjer ste vi, ko je verzija zaklenjena in/ali vam promiskuiteta verzijepreprečuje, da enostavno in varno prestavite vaš projekt naprej.
Kot rešitev tega problema, predlagam enostaven skupek pravil inzahtev, ki diktirajo, kako naj bodo številke verzij določene in povečane.Ta pravila so osnovana na in ne nujno omejena na pred obstoječeširoko skupne prakse v uporabi tako v programski opremi zaprte kode kot odprte kode.Da ta sistem deluje, morate najprej določiti javni API. To lahko sestojiiz dokumentacije ali je izvršeno s strani same kode. Ne glede na to,pomembno je, da je ta API jasen in točen. Ko enkrat identificirate vaš javniAPI, lahko komunicirate spremembe na njem z določenimi povečanji na vaši številkiverzije. Smatrajte obliko verzije X.Y.Z (Glavna.Manjša.Popravek). Popravki hroščev nevplivajo na API a povečujejo številko popravka, nazaj združljivi APIdodatki/spremembe povečujejo manjšo verzijo in nazaj nezdružljive APIspremembe povečujejo glavno verzijo.
Ta sistem se imenuje “Semantične verzije.” Pod to shemo, številke verzijin način, kako spreminjajo poslani pomen o podležeči kodi in kaj je bilospremenjeno iz ene verzije v naslednji.
Ključne besede “MORA”, “NE SME”, “ZAHTEVANO”, “BO”, “NE BO”, “BI MORALO”,“NE BI SMELO”, “PRIPOROČLJIVO”, “LAHKO” in “OPCIJSKO” se v tem dokumentuinterpretira, kot so opisane vRFC 2119.
Programska oprema, ki uporablja semantične verzije MORA določiti javni API. Ta APIje lahko določen v sami kodi ali obstaja striktno v dokumentaciji.Kakorkoli je končan, bi moral biti točen in celovit.
Običajna številka verzije MORA biti oblike X.Y.Z, kjer so X, Y, in Zpozitivna cena števila in NE SMEJO vsebovati vodilnih ničel. X jeglavna verzija, Y je manjša verzija in Z je verzija popravka.Vsak element se MORA povečati numerično. Na primer: 1.9.0 -> 1.10.0 -> 1.11.0.
Ko je enkrat paket verzije izdan, se vsebina te verzijaNE SME spremeniti. Kakršnekoli spremembe MORAJO biti izdane kot nova verzija.
Glavna verzija nič (0.y.z) je za začetni razvoj. Karkoli se lahko spremenikadarkoli. Javni API ne bi smel biti smatran za stabilnega.
Verzija 1.0.0 definira javni API. Način, kako je številka verzijapovečana za to izdajo je odvisno od tega javnega API-ja in kako sespremeni.
Verzija popravka Z (x.y.Z | x > 0) MORA biti povečana, če so predstavljeni samo nazajzdružljivi popravki hroščev. Popravek hrošča je definiran kot notranjasprememba, ki popravi nepravilno obnašanje.
Manjša verzija Y (x.Y.z | x > 0) MORA biti povečana, če so nove nazajzdružljive funkcionalnosti predstavljene javnemu API-ju. MORA bitipovečana, če je katerakoli funkcionalnost javnega API-ja označena za opuščeno. LAHKOje povečana, če so znatna nova funkcionalnost ali izboljšave predstavljeneznotraj privatne kode. LAHKO vključuje spremembe nivoja popravka. Verzija popravkaMORA biti ponastavljena na nič, ko je manjša verzija povečana.
Glavna verzija X (X.y.z | X > 0) MORA biti povečevana, če je kakršnakoli nazajnezdružljiva sprememba predstavljena javnemu API-ju. LAHKO vključuje spremembemanjše verzije in verzije popravka. Manjša verzija in popravek MORATA biti ponastavljena na 0, ko jeglavna verzija povečana.
Verzija pred-izdaje je LAHKO označena z dodajanjem vezaja inserije s pikami ločenih identifikatorjev, ki jim takoj sledi verzijapopravka. Identifikatorji MORAJO biti sestavljeni iz samo alfanumeričnih ASCII-jev in vezaja[0-9A-Za-z-]. Identifikatorji NE SMEJO biti prazni. Numerični identifikatorji NESMEJO vključevati vodilnih ničel. Verzije pred-izdaj imajo manjšivrstni red, ko povezana običajna verzija. Verzija pred-izdajeoznačuje, da je verzija nestabilna in lahko ne zadostinamenjenim zahtevam združljivosti, kot je označeno z njihovimi povezaniminormalnimi verzijami. Na primer: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7,1.0.0-x.7.z.92.
Metapodatki gradnje so LAHKO označeni z dodajanjem znaka plus in serije pikločenih identifikatorjev, ki jim takoj sledi popravek ali verzija pred-izdaje.Identifikatorji MORAJO biti sestavljeni iz samo alfanumeričnih ASCII-jev in vezajev [0-9A-Za-z-].Identifikatorji NE SMEJO biti prazni. Podatki metagradnje BI MORALI biti ignorirani, ko se določavrstni red verzij. Zato dve verziji, ki se razlikujeta samo v metapodatkih gradnje,imata enak vrstni red. Na primer: 1.0.0-alpha+001, 1.0.0+20130313144700,1.0.0-beta+exp.sha.5114f85.
Vrstni red se sklicuje na to, kako so verzije primerjane druga z drugo, ko so urejene.Vrstni red MORA biti izračunan z ločitvijo verzije v glavno, manjšo, popravekin identifikator pred-izdaje v tem vrstnem redu (metapodatki gradnje ne pašejov vrstni red). Vrstni red je določen s prvo razliko, koprimerjate vsako od teh identifikatorjev iz leve proti desni kot sledi: Verzije glavna, manjšain popravek so vedno primerjane s številkami. Na primer: 1.0.0 < 2.0.0 <2.1.0 < 2.1.1. Ko so glavna, manjša in popravek enake, ima verzija pred-izdajemanjši vrstni red kot običajne izdaje. Na primer 1.0.0-alpha < 1.0.0. Vrstni redza dve verziji pred-izdaje z enako verzijo glavne, manjše in popravka MORATAbiti določeli s primerjanjem vsake pike ločenega identifikatorja iz leve proti desnidokler ni razlika najdena kot sledi: identifikatorji sestavljeni iz samo številkso primerjani numerično in identifikatorji s črkami ali vezaji so primerjanibesedno v ASCII vrstnem redu. Numerični identifikatorji imajo vedno manjši vrstni redkot ne-numerični identifikatorji. Večji skupek polj pred-izdaje imajo večjivrstni red kot manjši skupek, če vsi prejšnji identifikatorji so enaki.Na primer: 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.
To ni nova ali revolucionarna ideja. V bistvu delate nekaj podobnegatemu že sedaj. Problem je, da “nekaj podobnega” ni dovolj dobro. Brezskladnosti z nekakšno uradno specifikacijo, so številke verzijv bistvu neuporabne za upravljanje odvisnosti. Z dodajanjem imena in jasnedefinicije zgornjim idejam, postane enostavno za komunicirati vaše namereuporabnikom vaše programske opreme. Ko enkrat postanejo te namere jasne, fleksibilne (vendarne preveč fleksibilne), se lahko končno naredi specifikacija odvisnosti.
Enostaven primer bo demonstriral, kako semantične verzije lahko naredijo pekelodvisnosti stvar preteklosti. Premislite o knjižnici imenovani “Firetruck”. Zahtevapaket s semantično verzijo in se imenuje “Ladder”. Ko je Firetrucknarejen, je Ladder pri verziji 3.1.0, lahko varno določite verzijo odvisnosti Ladderkot večjo ali enako 3.1.0, vendar manjšo kot 4.0.0. Sedaj ko postaneLadder verzija 3.1.1 in 3.2.0 postane na voljo, jih lahko izdate v vašemsistemu paketnega upravljanja in veste, da bodo postale kompatibilne z obstoječoodvisno programsko opremo.
Kot odgovoren razvijalec boste seveda želeli preveriti, da katerikolipaket nadgradnje funkcionira, kot je oglaševano. Realni svet je grdo mesto;ničesar ni, kar bi lahko naredili o tem, razen da smo pazljivi. Kar lahko naredite jeomogočiti semantičnim verzijam, da vam ponudijo pameten način izdaje in nadgradnjepaketov brez, da morate kotaliti nove verzije odvisnih paketov, kar vam prihraničas in težave.
Če to vse zveni zaželjeno, je vse kar morate storiti, da začnete uporabljati semantičneverzije, razglasitev, da to tako delate in nato slediti pravilom. Povežitena to spletno stran iz vaše datoteke README, da ostali vedo pravila in jih lahkokoristijo.
Najenostavnejše narediti je začeti vašo začetno razvojno izdajo pri 0.1.0in nato povečevati manjše verzije za vsako naknadno izdajo.
Če je vaša programska oprema uporabljena v produkciji, bi morala verjeno že biti1.0.0. Če imate stabilni API od katerega so postali uporabniki odvisni, bi moraliimeti 1.0.0. Če vas skrbi veliko o združljivosti za nazaj, bi morali verjetnože biti na 1.0.0.
Glavna verzija nič je vse o hitrem razvoju. Če spreminjate APIvsak dan, bi morali ali biti še vedno na verziji 0.y.z ali na ločenirazvojni veji delati na naslednji glavni verziji.
To je vprašanje odgovornega razvoja in vpogleda vnaprej. Nezdružljivespremembe ne bi smele biti predstavljene ohlapno v programsko opremo, ki imaveliko odvisne kode. Cena, ki mora nastati za nadgradnjo, je lahko pomembna.Povečanje glavnih verzij za izdajo nekompatibilnih sprememb pomeni, da bostepremislili skozi vpliv vaših sprememb in ocenili vpleteno razmerjecena/korist.
Vaša odgovornost kot profesionalnega razvijalca je, da ustrezno dokumentirateprogramsko opremo, ki je nameravana za uporabo s strani drugih. Upravljanje kompleksnosti programske opreme jezelo pomemben del, da obdržite projekt učinkovit in to narediti je težko, čenihče ne ve, kako uporabiti vašo programsko opremo ali katere metode so varne za klicanje. Nadolgi rok semantične verzije in vztrajanje na dobro definiranem javnemAPI-ju lahko obdrži poganjanje vsakogar in vsega gladko.
Kakor hitro se zaveste, da ste prelomili specifikacijo semantičnih verzij, popraviteproblem in izdajte novo manjšo verzijo, ki popravi problem inpovrne združljivost za nazaj. Tudi pod temi okoliščinami, nisprejemljivo spreminjati verzij izdaj. Če je primerno,dokumentirajte kršeno izdajo in obvestite vaše uporabnike o problemu, da soseznanjeni o kršeni izdaji.
To bi moralo biti smatrano kompatibilno, ker ne vpliva na javni API.Programska oprema, ki je eksplicitno odvisna od istih odvistnosti, bi vaš paketmoral imeti svoje lastne specifikacije odvisnosti in avtor bo opazil kakršnekolikonflikte. Določanje ali je sprememba modifikacije nivoja popravka ali manjšega nivojazavisi na tem ali posodabljate vaše odvisnosti z namenom popraviti hrošč ali dodati novofunkcionalnost. Običajno bi pričakoval dodatno kodoza slednjo instanco, v katerem primeru je očitno povečanje manjšega nivoja.
Uporabite vašo najboljšo presojo. Če imate veliko občinstvo, ki bo močnovplivano s spreminjanjem obnašanja nazaj k čemur je bil javni API namenjen, potemje lahko najboljše opraviti glavno verzijo izdaje, četudi bi popravekstriktno bil smatran za izdajo popravka. Spomnimo se, semantične verzije so samotransportiranje, kar pomeni za koliko se številka verzije spremeni. Če so teverzije pomembne za vaše uporabnike, uporabite številko verzije, da jih obvestite.
Opuščanje obstoječe funkcionalnosti je običajen del razvoja programske opreme inje pogosto zahtevano za narediti, da se naredi nadaljnji razvoj. Ko opuščate del vašegajavnega API-ja, bi morali narediti dve stvari: (1) posodobiti vašo dokumentacijo, daobvestite uporabnike o spremembi, (2) izdati novo manjšo verzijo z opuščenostjona mestu. Preden v celoti odstranite funkcionalnost v novi glavni izdajibi morala biti vsaj ena manjša izdaja, ki vsebuje opuščenost, dalahko uporabniki gladko preidejo na nov API.
Ne, vendar uporabite dobro presojo. Na primer verzija z 255 dolgim nizom je verjetno pretiravanje.Tudi določeni sistemi lahko nalagajo njihove lastne omejitve na velikostiniza.
Specifikacija sementičnih verzij je avtorizirana s straniTomaPreston-Werner-ja, izumitelja Gravatarjev insoustanovitelja GitHub-a.
Slovenski prevod so prispevali:
Če želite pustiti povratne informacije, prosimo, daodprete vprašanje naGitHub-u.