Givet ett versionsnummer på formen MAJOR.MINOR.PATCH, räkna upp varje del enligt följande:
Ibland kan det även förekomma ytterligare delar i versionsnumret för att markerat.ex. en test- eller betaversion.
I mjukvaruutvecklingens värld finns det en obehaglig plats, det så kallade “beroendeträsket”.Ju större ditt system blir och ju fler paket du integrerar i ditt program, destostörre är risken att du en dag finner dig själv i förtvivlans grepp.
I system med många beroenden kan nya versioner av paket snabbt bli en mardröm. Omde specificerade beroendena är för hårt satta är risken stor att du hamnar i ettversionslås (oförmågan att uppgradera ett paket utan att släppa nya versioner avalla paket det finns beroende till). Om beroendena är specificerade för löst kommerdu oundvikligen hamna i en versionsnaivitet (övertro på kompabilitet med nyareversioner). Du är i ett beroendeträsk om versionslås och/eller versionsnaivitetförhindrar dig att enkelt och säkert ta ditt projekt framåt.
Som en lösning på detta problem föreslår jag en enkel samling regler och krav sombeskriver hur versionsnummer ska tilldelas och räknas upp. Dessa regler är baseradepå, men inte nödvändigt begränsade till, redan existerande välkänd och vanlig praxissom används både för sluten och öppen källkod. För att detta system ska fungera måstedu deklarera ett publikt API. Detta kan bestå av dokumentation eller vara en del avsjälva källkoden. Oavsett vilket är det viktigt att detta API är klart och tydligt.När du har identifierat ditt publika API kommunicerar du ändringar i det medspecifik ökning av versionsnumret. Överväg X.Y.Z (Major.Minor.Patch) som format påversionsnumret. Buggfixar som ej påverkar API:t ökar patch-versionen, bakåtkompatiblaAPI-ändringar/tillägg ökar minor-versionen och icke bakåtkompatibla API-ändringarökar major-versionen.
Jag kallar detta system “Semantisk versionshantering”. Under detta schema förmedlarversionsnumret och dess förändringar mening till den underliggande koden och hur denhar förändrats från en version till en annan.
Nyckelorden “MÅSTE”/”FÅR ENBART” (MUST/SHALL/REQUIRED), “FÅR INTE” (MUST NOT/SHALL NOT),“BÖR” (SHOULD/RECOMMENDED), “BÖR INTE” (SHOULD NOT) och “KAN” (MAY/OPTIONAL) i dettadokument skall tolkas enligt beskrivning iRFC 2119.
Program som använder Semantisk versionshantering MÅSTE deklarera ett publikt API.Detta API kan deklareras i själva koden eller enbart existera i dokumentationen.Oavsett hur det görs BÖR det vara precist och heltäckande.
Ett normalt versionsnummer MÅSTE ha formen X.Y.Z där X, Y och Z ärpositiva heltal och FÅR INTE innehålla inledande nollor. X är major-versionen,Y är minor-versionen och Z är patch-versionen. Varje element MÅSTE ökas numeriskt,t.ex. 1.9.0 -> 1.10.0 -> 1.11.0.
När ett versionshanterat paket har släppts FÅR INTE innehållet i den versionenförändras. Alla modifieringar MÅSTE släppas som en ny version.
Major-versionen noll (0.y.z) är för inledande utveckling. Vad som helst KAN förändras när som helst.Publikt API BÖR ej ses som stabilt.
Version 1.0.0 definierar det publika API:t. Hur versionsnumret ökar efter detta släppär beroende på detta publika API och hur det förändras.
Patch-version Z (x.y.Z | x > 0) FÅR ENBART ökas om bakåtkompatibla buggfixar ärintroducerade. En buggfix definieras som en intern förändring som åtgärdar ett felaktigt beteende.
Minor-version Y (x.Y.z | x > 0) MÅSTE ökas om ny bakåtkompatibel funktionalitet introducerasi det publika API:t. Det MÅSTE ökas om någon funktion i det publika API:t markeras somföråldrad (deprecated). Det KAN ökas om väsentlig ny funktionalitet eller förbättringarinförs i den privata koden. Även förändringar på patch-nivå KAN ingå. Patch-versionen MÅSTEåterställas till 0 när minor-versionen ökar.
Major-versionen X (X.y.z | X > 0) MÅSTE ökas om någon icke bakåtkompatibel förändringintroduceras i det publika API:t. Även förändringar på minor- och patch-nivå KAN ingå. Patch-och minor-versionerna MÅSTE återställas till 0 när major-versionen ökar.
En förhandsversion KAN markeras genom att lägga till ett bindestreck och en serie avpunktseparerade identifierare direkt efter patch-versionen. Identifierare FÅR ENBART innehållaalfanumeriska ASCII-tecken och bindestreck [0-9A-Za-z-]. Identifierare FÅR INTE vara tomma.Numeriska identifierare FÅR INTE ha inledande nollor. En förhandsversion har en lägre prioritetän tillhörande normal version. En förhandsversion indikerar att versionen är instabil ochkanske inte uppfyller avsedda kompabilitetskrav som utmärker dess tillhörande normala version.Exempel: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
Metadata för byggen KAN markeras genom att lägga till ett plustecken och en seriepunktseparerade identifierare direkt efter patch-versionen eller information om förhandsversion.Identifierare FÅR ENBART innehålla alfanumeriska ASCII-tecken och bindestreck [0-9A-Za-z-].Identifierare FÅR INTE vara tomma. Bygg-metadata MÅSTE ignoreras när versionsprioritet skallfastställas. Således har två versioner som enbart skiljer i bygg-metadata samma prioritet.Exempel: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
Versionsprioritet syftar på hur versioner jämförs när de sorteras. Prioritet MÅSTE beräknasgenom att separera versionen i major, minor, patch och identifierare för förhandsversion i givenordning (bygg-metadata påverkar ej rangordningen). Prioritet bestäms av första skillnadennär var och en av dessa identifierare jämförs i tur och ordning från vänster till höger enligt:Major-, minor- och patch-version jämförs alltid numeriskt.Exempel: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. När major, minor och patch är lika har en förhandsversionlägre prioritet än en normal version. Exempel: 1.0.0-alpha < 1.0.0. Prioritet för tvåförhandsversioner med samma major-, minor- och patch-version MÅSTE bestämmas genom att jämföravarje punktseparerad identifierare från vänster till höger till dess att en skillnad hittas enligtföljande: identifierare som enbart består av siffror jämförs numeriskt och identifierare medbokstäver och bindestreck jämförs lexikalt enligt sorteringsordningen i ASCII. Numeriskaidentifierare har alltid lägre prioritet än icke numeriska identifierare. En större uppsättningförhandsversionsidentifierare har en högre prioritet än en med färre antal ifall alla inledandeidentifierare är lika. Exempel: 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.
Detta är inte en ny eller revolutionerande idé. Faktum är att du förmodligen redan gör det pånästan samma sätt. Problemet är att ”nästan” inte är tillräckligt bra. Utan någon form av formellspecifikation att följa är versionsnummer så gott som värdelösa när det gäller beroendehantering.Genom att ge ett namn och tydlig definition till ovanstående idéer blir det enkelt att kommuniceradina avsikter till användarna av din mjukvara. När dessa avsikter är tydliga kan flexibla(men inte för flexibla) beroendespecifikationer göras.
Ett enkelt exempel kommer här demonstrera hur Semantisk versionshantering kan göra beroendeträskettill ett minne blott. Tänk dig ett bibliotek kallat ”Brandbil”. Det kräver ett semantisktversionshanterat paket kallat ”Stege”. När Brandbil skapas finns Stege i version 3.1.0. Då Brandbilanvänder funktionalitet som introducerades i version 3.1.0 av Stege, kan du med säkerhet specificeraett beroende till versioner högre eller lika med 3.1.0 men lägre än 4.0.0. När sedan version 3.1.1och 3.2.0 av Stege blir tillgängliga kan du släppa dem till ditt pakethanteringssystem och varasäker på att de kommer vara kompatibla med existerande programvara.
Som en ansvarsfull utvecklare vill du förstås verifiera att varje paketuppgradering fungerar som väntat.Verkligheten är en rörig plats, det finns inget vi kan göra åt det mer än att vara vaksamma. Vad dukan göra är att låta Semantisk versionshantering ge dig ett sunt sätt att släppa och uppgradera paketutan att behöva rulla ut nya versioner av paket beroende av det första, vilket kommer att bespara digtid och problem.
Låter detta attraktivt? Allt du behöver göra för att börja använda Semantisk versionshantering äratt ange att du gör det och börja följa reglerna. Länka till denna hemsida i din README så att andrakänner till reglerna och kan dra nytta av dem.
Enklast är att sätta versionsnummer 0.1.0 på den första utvecklingsversionen och sedan ökaminor-versionen för varje efterföljande version.
Om din mjukvara används i produktion borde det förmodligen redan heta 1.0.0. Om du har ett stabiltAPI som användare redan har beroende till borde du använda 1.0.0. Om du oroar dig för bakåtkompabilitetborde du sannolikt redan vara på 1.0.0.
Major-version noll handlar helt om snabb utveckling. Om du ändrar API:t varje dag bör du antingenvara kvar i version 0.y.z eller jobba med nästa stora version på en separat utvecklingsgren.
Detta är en fråga om ansvarsfull utveckling och planering. Inkompatibla förändringar bör inteintroduceras lättvindigt i mjukvara som många har beroende till. Kostnaden man drar på sig föratt uppgradera kan bli betydande. Att öka major-versionen för att släppa inkompatibla ändringarinnebär att du också måste tänka genom konsekvenserna av dina ändringar och utvärdera kostnadkontra nytta.
Det är ditt ansvar som en professionell utvecklare att korrekt dokumentera mjukvara som äravsedd att användas av andra. Att hantera mjukvarukomplexitet är en stor och viktig del i atthålla ett projekt effektivt, och det blir svårt om ingen vet hur mjukvaran ska användas ellervilka metoder som är säkra att anropa. I långa loppet gör Semantisk versionshantering och kravpå väl dokumenterat publikt API att allt flyter på smidigt.
Så fort du inser att du har brutit specifikationen i Semantisk versionshantering, fixa problemetoch släpp en ny minor-version som korrigerar problemet och återställer bakåtkompabiliteten.Även under dessa omständigheter är det helt oacceptabelt att modifiera den släppta versionen.Om lämpligt, dokumentera den felande versionen och informera dina användare om problemet såatt de är medvetna om den felande versionen.
Det skulle kunna ses som kompatibelt då det inte påverka det publika API:t. Programvara somuttryckligen är beroende av samma sak som ditt paket bör ha sin egen beroendespecifikation ochskaparen kommer att märka eventuella konflikter. Att avgöra om förändringen är på patch- ellerminor-nivå beror på om du uppdaterade beroendet för att fixa en bugg eller för att introducerany funktionalitet. För det senare fallet hade jag förväntat mig att ny kod hade skrivits dådet naturligtvis är på minor-nivå.
Använd ditt omdöme. Om du har en stor publik som kommer att påverkas stort av att beteendetförändras mot vad som förväntas av det, då är det bäst att skapa en major-version även omändringen strikt borde ses som en patch-version. Kom ihåg att Semantisk versionshanteringhandlar om att förmedla innebörden av hur versionsnummer förändras. Om dessa förändringarär viktiga för dina användare, använd versionsnumret för att informera dem.
Att markera existerande funktionalitet som föråldrad är en normal del av mjukvaruutvecklingoch krävs oftast för att komma framåt. När du markera delar av ditt publika API som föråldratbör du göra två saker: (1) uppdatera din dokumentation så att användarna blir medvetna omändringen, (2) skapa en ny minor-version med funktionaliteten markerad som föråldrad. Innandu helt tar bort funktionaliteten i en ny major-version bör det vara minst en minor-versioninnehållandes markering om föråldrad kod så att användarna smidigt kan gå över till detnya API:t.
Nej, men använd sunt förnuft. En versionssträng på t.ex. 255 tecken är förmodligen överdrivet.Dessutom kan vissa system ha egna begränsningar på hur lång den får vara.
Nej, “v1.2.3” är inte en semantisk version. Å andra sidan är det vanligt att (på engelska)använda prefixet “v” på semantiska versionsnummer för att förtydliga att det är ett versionsnummer.Förkortningen “v” för “version” syns ofta i samband med versionshantering.Exempel:git tag v1.2.3 -m "Release version 1.2.3", i detta fallet är “v1.2.3” ett tagg-namnoch “1.2.3” den semantiska versionen.
Specifikationen för Semantisk versionshantering är skriven avTomPreston-Werner, skapare av Gravatars och medgrundare avGitHub.
Om du vill lämna feedback,öppna en fråga på GitHub.