Givet et versionsnummer MAJOR.MINOR.PATCH, skal du øge:
Yderligere etiketter til pre-release og build-metadata er tilgængelige som udvidelsertil MAJOR.MINOR.PATCH-formatet.
I verden af software management findes der et frygtet sted kaldet“afhængighedshelvede.” Jo større dit system vokser, og jo flere pakker duintegreres i din software, jo større sandsynlighed er der for, at du finder dig selv, endag, i denne fortvivlelses hule.
I systemer med mange afhængigheder kan frigivelse af nye pakkeversioner hurtigtblive et mareridt. Hvis afhængighedsspecifikationerne er for stramme, er du medfare for versionslås (manglende evne til at opgradere en pakke uden at skullefrigive nye versioner af hver afhængig pakke). Hvis afhængigheder erspecificeret for løst, vil du uundgåeligt blive bidt af versionspromiskuitet(forudsat kompatibilitet med flere fremtidige versioner end rimeligt).Afhængighedshelvede er, når versionslås og/eller versionspromiskuitetforhindrer dig i nemt og sikkert at komme videre med dit projekt.
Som en løsning på dette problem foreslår vi et simpelt sæt regler ogkrav, der dikterer, hvordan versionsnumre tildeles og øges.Disse regler er baseret på, men ikke nødvendigvis begrænset til, allerede eksisterendeudbredt almindelig praksis i brug i både lukket og open source-software.For at dette system skal fungere, skal du først erklære en offentlig API. Dette kan evtbestå af dokumentation eller håndhæves af selve koden. Uanset hvad er detvigtigt, at dette API er klar og præcis. Når du identificerer dit offentligeAPI, kommunikerer du ændringer til det med specifikke ændringer til dit versionsnummer.Overvej et versionsformat af X.Y.Z (Major.Minor.Patch). Fejlrettelser der ikkepåvirker API’et øger patchversionen (Z), bagudkompatibelt APImed tilføjelser/ændringer øger den mindre version (Y) og bagud inkompatible APIændringer øger hovedversionen (X).
Vi kalder dette system “Semantisk versionering.” Under denne ordning, formidler versionsnumrene mening om den underliggende kode og hvad der har blevet ændret fra den ene version til den næste.
Nøgleordene “MÅ”, “MÅ IKKE”, “PÅKRÆVET”, “SKAL”, “MÅ IKKE”, “BØR”,“BØR IKKE”, “ANBEFALET”, “KAN” og “VALGFRI” i dette dokument skal værefortolket som beskrevet iRFC 2119.
Software, der bruger semantisk versionering SKAL erklære et offentlig API. Dette APIkan være erklæret i selve koden eller udelukkende eksistere i dokumentationen.Uanset hvordan det gøres, SKAL det være præcist og omfattende.
Et normalt versionsnummer SKAL have formen X.Y.Z, hvor X, Y og Z erikke-negative heltal og MÅ IKKE indeholde indledende nuller. X erstørre version, Y er den mindre version, og Z er patch-versionen.Hvert element SKAL øges numerisk. For eksempel: 1.9.0 -> 1.10.0 -> 1.11.0.
Når en versioneret pakke er blevet frigivet, MÅ indholdet IKKE ændres i den version.Eventuelle ændringer SKAL frigives som en ny version.
Større version nul (0.y.z) er til indledende udvikling. Alt KAN ændre signår som helst. Det offentlige API BØR IKKE betragtes som stabilt.
Version 1.0.0 definerer det offentlige API. Den måde, hvorpå versionsnummeretøges efter denne udgivelse er afhængig af dette offentlige API og hvordan denændrer sig.
Patchversion Z (x.y.Z | x > 0) SKAL øges, hvis kun baglænskompatible fejlrettelser introduceres. En fejlrettelse er defineret som en internændring, der retter ukorrekt adfærd.
Mindre version Y (x.Y.z | x > 0) SKAL øges, hvis ny, baglænskompatibel funktionalitet introduceres til det offentlige API. Det må øges, hvis noget offentlig API-funktionalitet er markeret som forældet. Det BØR øges,hvis der indføres væsentlig ny funktionalitet eller forbedringer inden for den private kode. Det KAN omfatte ændringer af patch-niveau. Patch version SKAL nulstilles til 0, når mindre version øges.
Større version X (X.y.z | X > 0) SKAL øges, hvis der er nogen baglænsinkompatible ændringer der introduceres til det offentlige API. Det MÅ også omfatte mindre ændringer i patch-niveau. Patch og mindre versioner SKAL nulstilles til 0, når de er størreversion er øget.
En pre-release version KAN angives ved at tilføje en bindestreg og enserie af punktseparerede identifikatorer umiddelbart efter patchenversion. Identifikatorer SKAL kun omfatte ASCII alfanumeriske tegn og bindestreger[0-9A-Za-z-]. Identifikatorer MÅ IKKE være tomme. Numeriske identifikatorer SKALInkluder IKKE foranstillede nuller. Pre-release versioner har en lavereforrang end den tilhørende normale version. En pre-release versionangiver, at versionen er ustabil og muligvis ikke opfyldertilsigtede kompatibilitetskrav som angivet af dets tilknyttedenormal version. Eksempler: 1.0.0-alfa, 1.0.0-alfa.1, 1.0.0-0.3.7,1.0.0-x.7.z.92, 1.0.0-x-y-z.–.
Byggemetadata KAN angives ved at tilføje et plustegn og en række prikkeradskilte identifikatorer umiddelbart efter patchen eller pre-release-versionen.Identifikatorer SKAL kun omfatte ASCII alfanumeriske tegn og bindestreger [0-9A-Za-z-].Identifikatorer MÅ IKKE være tomme. Byggemetadata SKAL ignoreres ved bestemmelseversions forrang. Således to versioner, der kun adskiller sig i byggemetadataene,har samme forrang. Eksempler: 1.0.0-alfa+001, 1.0.0+20130313144700,1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3—-117B344092BD.
Forrang henviser til, hvordan versioner sammenlignes med hinanden, når de bestilles.
Forrang SKAL beregnes ved at adskille versionen i større,mindre, patch og pre-release identifikatorer i den rækkefølge (Byggemetadatahar ikke forrang).
Forrang bestemmes af den første forskel, når man sammenligner hver afdisse identifikatorer fra venstre mod højre som følger: Større, mindre og patchversioner sammenlignes altid numerisk.
Eksempel: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.
Når større, mindre og patch er ens, har en pre-release version lavereforrang end en normal version:
Eksempel: 1.0.0-alfa < 1.0.0.
Forrang for to pre-release versioner med samme større, mindre ogpatch-version SKAL bestemmes ved at sammenligne hver punktsepareret identifikatorfra venstre mod højre, indtil en forskel er fundet som følger:
Identifikatorer, der kun består af cifre, sammenlignes numerisk.
Identifikatorer med bogstaver eller bindestreger sammenlignes leksikalsk i ASCIIsorteringsrækkefølge.
Numeriske identifikatorer har altid lavere forrang end ikke-numeriskeidentifikatorer.
Et større sæt præ-udgivelsesfelter har en højere prioritet end enmindre sæt, hvis alle de foregående identifikatorer er ens.
Eksempel: 1.0.0-alfa < 1.0.0-alfa.1 < 1.0.0-alfa.beta < 1.0.0-beta <1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.
Dette er ikke en ny eller revolutionær idé. Faktisk gør du sikkert nogettæt på dette allerede. Problemet er, at “tæt” ikke er godt nok. Udenoverensstemmelse med en form for formel specifikation, versionsnumre eri det væsentlige ubrugelig til afhængighedsstyring. Ved at give et navn og klartdefinition til ovenstående ideer, bliver det nemt at kommunikere dine hensigtertil brugerne af din software. Når først disse intentioner er klare, fleksible (menikke for fleksible) kan der endelig laves afhængighedsspecifikationer.
Et simpelt eksempel vil vise, hvordan semantisk versionering kan gøre afhængighedhelvede hører fortiden til. Overvej et bibliotek kaldet “Brandbil.” Det kræver enSemantisk versioneret pakke med navnet “Ladder.” På det tidspunkt, hvor Firetruck eroprettet, er Ladder i version 3.1.0. Da Firetruck bruger nogle funktionersom først blev introduceret i 3.1.0, kan du roligt angive stigenafhængighed som større end eller lig med 3.1.0, men mindre end 4.0.0. Nu, hvornårLadder version 3.1.1 og 3.2.0 bliver tilgængelige, du kan frigive dem til dinpakkestyringssystem og ved, at de vil være kompatible med eksisterendeafhængig software.
Som ansvarlig udvikler vil du naturligvis gerne verificere, at evtpakkeopgraderinger fungerer som annonceret. Den virkelige verden er et rodet sted;der er ikke noget, vi kan gøre ved det, end at være årvågne. Hvad du kan gøre er at ladeSemantisk versionering giver dig en fornuftig måde at frigive og opgraderepakker uden at skulle rulle nye versioner af afhængige pakker, hvilket sparer digtid og bøvl.
Hvis alt dette lyder ønskeligt, er alt hvad du skal gøre for at begynde at bruge SemanticVersionering er at erklære, at du gør det og derefter følge reglerne. Linktil denne hjemmeside fra din README, så andre kender reglerne og kan drage fordel afdem.
Den enkleste ting at gøre er at starte din første udviklingsudgivelse på 0.1.0og øg derefter den mindre version for hver efterfølgende udgivelse.
Hvis din software bliver brugt i produktionen, burde den sandsynligvis allerede være det1.0.0. Hvis du har et stabilt API, som brugerne er blevet afhængige af, bør duvære 1.0.0. Hvis du bekymrer dig meget om bagudkompatibilitet, bør dusandsynligvis allerede være 1.0.0.
Større version nul handler om hurtig udvikling. Hvis du ændrer APIhver dag bør du enten stadig være i version 0.y.z eller på en separatudviklingsgren arbejder på den næste store version.
Dette er et spørgsmål om ansvarlig udvikling og fremsyn. Uforeneligændringer bør ikke introduceres let til software, der har en masseafhængig kode. De omkostninger, der skal afholdes for at opgradere, kan være betydelige.At skulle bumpe større versioner for at frigive inkompatible ændringer betyder, at du vilgennemtænk virkningen af dine ændringer, og evaluer cost/benefit-forholdetinvolveret.
Det er dit ansvar som professionel udvikler at dokumentere ordentligtsoftware, der er beregnet til brug af andre. Håndtering af softwarekompleksitet er enenormt vigtig del af at holde et projekt effektivt, og det er svært at gøre hvisingen ved, hvordan man bruger din software, eller hvilke metoder der er sikre at kalde. Ipå lang sigt, semantisk versionering og insisteren på en veldefineret offentlighedAPI kan holde alle og alt kørende.
Så snart du indser, at du har brudt Semantic Versioning-specifikationen, skal du rette detproblemet og frigive en ny mindre version, der retter problemet oggenopretter bagudkompatibilitet. Selv under denne omstændighed er detuacceptabelt at ændre versionerede udgivelser. Hvis det er passende,dokumentere den krænkende version og informere dine brugere om problemet, således atde er opmærksomme på den krænkende version.
Det ville blive betragtet som kompatibelt, da det ikke påvirker der offentlige API.Software, der eksplicit afhænger af de samme afhængigheder som din pakkebør have deres egne afhængighedsspecifikationer, og forfatteren vil bemærke evtkonflikter. Afgør, om ændringen er et patch-niveau eller et mindre niveauændring afhænger af, om du har opdateret dine afhængigheder for at retteen fejl eller introducere ny funktionalitet. Vi ville normalt forvente yderligere kodei sidstnævnte tilfælde, i hvilket tilfælde det åbenbart er en mindre niveaustigning.
Brug din bedste dømmekraft. Hvis du har et stort publikum, vil det være drastiskpåvirket af at ændre adfærden tilbage til, hvad den offentlige API havde til hensigtdet kan være bedst at udføre en større versionsudgivelse, selvom rettelsen kunnestrengt taget betragtes som en patch-udgivelse. Husk, Semantisk versionering er altom at formidle mening ved, hvordan versionsnummeret ændres. Hvis disse ændringerer vigtige for dine brugere, skal du bruge versionsnummeret til at informere dem.
Forringelse af eksisterende funktionalitet er en normal del af softwareudvikling oger ofte påkrævet for at gøre fremskridt. Når du fraskriver en del af dinoffentlige API, bør du gøre to ting: (1) opdatere din dokumentation for at ladebrugere kender til ændringen, (2) udsteder en ny mindre udgivelse med afskrivningenpå plads. Før du helt fjerner funktionaliteten i en ny større udgivelseder bør være mindst én mindre udgivelse, der indeholder udfasningen såat brugerne problemfrit kan skifte til den nye API.
Nej, men brug god dømmekraft. En version på 255 tegn er sandsynligvis overkill,for eksempel. Også specifikke systemer kan pålægge deres egne grænser for størrelsen afstrengen.
Nej, “v1.2.3” er ikke en semantisk version. Dog foran en semantisk versionmed et “v” er en almindelig måde (på engelsk) at angive, at det er et versionsnummer.At forkorte “version” som “v” ses ofte med versionskontrol. Eksempel:git tag v1.2.3 -m "Release version 1.2.3", i hvilket tilfælde “v1.2.3” er et tagnavn og den semantiske version er “1.2.3”.
Der er to. En med navngivne grupper for de systemer, der understøtter dem(PCRE [Perl-kompatible regulære udtryk, dvs. Perl, PHP og R], Pythonog gå).
Se:https://regex101.com/r/Ly7O1x/3/
^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))$Og en med nummererede optagelsesgrupper i stedet (så cg1 = større, cg2 = mindre,cg3 = patch, cg4 = prerelease og cg5 = byggemetadata), der er kompatibelmed ECMA Script (JavaScript), PCRE (Perl Compatible Regular Expressions,dvs. Perl, PHP og R), Python og Go.
Se:https://regex101.com/r/vkijKf/1/
^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0 |[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d *|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?: \.[0-9a-zA-Z-]+)*))?$Den semantiske versionsspecifikation blev oprindeligt skrevet afTomPreston-Werner, opfinder af Gravatar ogmedstifter af GitHub.
Hvis du gerne vil give feedback, bedes duåbn et issue påGitHub.