Semantisk versionering

Hvad det er

Semantisk versionering, på engelsk semantic versioning og som regel
forkortet SemVer, er et sæt regler for, hvordan udgivelser
nummereres, så selve nummeret fortæller, hvilken slags ændring en
udgivelse indeholder. Specifikationen, der nu er i version 2.0.0 og
oprindeligt blev skrevet af Tom Preston-Werner, bruger tre tal på
formen MAJOR.MINOR.PATCH. En udgivelse, der bryder det offentlige
API, hæver major-tallet. En udgivelse, der tilføjer funktionalitet
på en bagudkompatibel måde, hæver minor-tallet, og en, der kun
retter fejl uden at røre ved API'et, hæver patch-tallet. Når et tal
stiger, sættes tallene til højre for det tilbage til nul, og hvert
tal sammenlignes som et tal og ikke som tekst, så `1.10.0` kommer
efter `1.9.0`.

Det hele hviler på ét krav: Projektet skal erklære et offentligt
API, i koden eller i dokumentationen, for tallene beskriver
ændringer i netop det API og intet andet. Når en version først er
udgivet, må dens indhold ikke ændres; en rettelse er en ny version.
Major-version nul, `0.y.z`, er til den indledende udvikling, hvor
alt kan ændre sig når som helst, og hvor API'et ikke bør betragtes
som stabilt. Version `1.0.0` er det punkt, hvor det offentlige API
bliver defineret, og derfra følger tallene, hvordan det ændrer sig.

To valgfrie tilføjelser udvider formatet. En pre-release skrives
efter en bindestreg og sorteres før den udgivelse, den fører frem
til, så `1.0.0-alpha` kommer før `1.0.0-alpha.1`, der igen kommer
før `1.0.0-beta`, `1.0.0-rc.1` og til sidst `1.0.0`. Build-metadata
skrives efter et plustegn, som i `1.0.0+20130313144700`, og
ignoreres, når versioner sættes i rækkefølge, så to versioner, der
kun adskiller sig dér, har samme forrang. Et foranstillet v, som i
Git-tagget `v1.2.3`, er ikke en del af den semantiske version;
specifikationen kalder det en almindelig måde at vise på, at der er
tale om et versionsnummer. Go gør det til et krav: En kanonisk
version af et Go-modul er bogstavet v efterfulgt af en semantisk
version.

Hvorfor det betyder noget

Specifikationen tager udgangspunkt i det, den kalder
afhængighedshelvede. Er afhængighederne angivet for stramt, ender
man i versionslåsning, hvor man ikke kan opgradere én pakke uden at
udgive nye versioner af alt, der afhænger af den. Er de angivet for
løst, ender man i versionspromiskuitet og antager kompatibilitet med
flere fremtidige versioner, end der er rimeligt. Et versionsnummer
med en aftalt betydning gør det muligt for et projekt at sige, hvad
det vil acceptere: Et bibliotek, der bruger en funktion, som først
kom med i 3.1.0, kan acceptere alt fra 3.1.0 og op til, men ikke
med, 4.0.0 og få senere rettelser og tilføjelser med, uden at nogen
skal redigere kravet.

Pakkehåndteringsværktøjerne handler på det løfte uden at spørge. I
Cargo, Rusts pakkehåndtering, er et almindeligt krav som `"1.2.3"`
et caret-krav og betyder mindst 1.2.3, men under 2.0.0. Når Cargo
skriver `Cargo.lock`, vælger den den højeste version inden for det
interval, og den bliver på 1.x-linjen, efter at

2.0.0 er udgivet, fordi den betragter 2.0.0 som inkompatibel. I
node-semver, der præsenterer sig som npm's værktøj til semantiske
versioner, betyder `^1.2.3` det samme som `>=1.2.3 <2.0.0-0`, og
`~1.2.3` tillader kun ændringer på patch-niveau, `>=1.2.3 <1.3.0-0`.
Go bygger reglen ind i importstierne: Fra major-version 2 og frem
skal et moduls sti ende med et suffiks som `/v2`, så to inkompatible
major-versioner er to forskellige importstier. Derefter tager Go med
minimal version selection for hvert modul den højeste version, som
et krav beder om, og det er den laveste version, der opfylder dem
alle. Resultatet gemmes ikke i en låsefil; hver modulbevidst
kommando beregner det igen.

Intet af dette gør nummeret til en garanti. Det er et løfte fra dem,
der udgiver pakken, og det er aldrig bedre end deres vurdering af,
hvad der tæller som et brud. Derfor udgiver Cargo en lang
kompatibilitetsguide, der inddeler ændringer i major, minor og
muligvis brydende. Det meste af guiden handler om ændringer, der får
kode, som byggede i går, til ikke at bygge i dag. Guiden skriver
selv, at næsten enhver ændring indebærer en vis risiko for at
påvirke opførslen under kørsel, og at det som regel er op til
vedligeholdernes skøn, om sådan en ændring er inkompatibel.

Sådan ser det ud i praksis

Følg et opdigtet Rust-bibliotek, tally, gennem dets udgivelser.
Version 0.4.2 er stadig indledende udvikling. Version 1.0.0 erklærer
det offentlige API for stabilt. Version 1.0.1 retter en
afrundingsfejl og er en patch. Version 1.1.0 tilføjer funktionen
`parse_strict` og markerer den gamle `parse` som forældet:
Specifikationen kræver en minor-udgivelse for at markere noget som
forældet og beder om mindst én sådan udgivelse, før funktionen
fjernes. Version 2.0.0 fjerner `parse` og er en major-udgivelse.
Version 2.1.0-rc.1 er en pre-release af den næste minor-version.

Et program, der afhænger af tally og tre andre opdigtede crates,
angiver sine krav i `Cargo.toml`. Kommentarerne viser det interval,
Cargo læser ud af hver linje:

```toml
[dependencies]
tally = "1.0.1"         # >=1.0.1, <2.0.0: takes 1.1.0, never 2.0.0
ledger = "0.4.2"        # >=0.4.2, <0.5.0: 0.5.0 counts as breaking
stamp = "~1.2.3"        # >=1.2.3, <1.3.0: patch releases only
quill = "=2.1.0-rc.1"   # exactly this pre-release
```

Linjen med `ledger` viser en konvention i værktøjerne og ikke i
specifikationen: Cargo betragter det første tal fra venstre, der
ikke er nul, som det, der signalerer et brud, mens specifikationen
siger, at alt under 1.0.0 kan ændre sig når som helst. Cargo
udelader pre-releases fra et krav, medmindre kravet selv nævner en,
så kravet `"2.0"` ville aldrig hente tallys release candidate. Den
eksakte `=`-form på sidste linje er det tilfælde, hvor Cargos
dokumentation siger, at et fuldt specificeret krav kan være
berettiget: når man afhænger af en pre-release og vil undgå brydende
ændringer mellem pre-releases. Når versionerne er fundet,
registreres de i `Cargo.lock`, og `cargo update` flytter dem inden
for de intervaller. Med `--locked` giver et build, der ville skulle
ændre låsefilen, i stedet en fejl.

Det, nummeret ikke dækker, er alt uden for API'et.
Licensgennemgangen af 644 Rust-crates, udført i september 2026,
tjekker licensen på hver crate ved hvert build mod en
tilladelsesliste. Grunden er, at en rutinemæssig versionsopdatering
dybt nede i afhængighedsgrafen kan ændre, hvilke vilkår et program
må distribueres under, uden at nogen opdager det, i en låsefil, der
aldrig bliver læst i sin helhed. For at bevise, at tjekket virker,
blev det bevidst provokeret til at fejle to gange. Den ene gang blev
en crates licensudtryk omskrevet, hvilket svarer til en crate, der
ændrer sine vilkår upstream mellem versioner, og det fanger en
menneskelig gennemgang ikke, fordi selve craten ikke er ny. Den
anden gang blev den fastlåste kernerevision flyttet, uden at
gennemgangen blev genereret igen. En semantisk version kan fortælle
dig, at 1.4.0 er ment til at virke med kode, der er skrevet mod
1.0.0. Den kan ikke fortælle dig, at du stadig må sende den ud.

Hvor det går galt

Et brud i en minor-udgivelse. Det sker ved et uheld, eller fordi man
ser forskelligt på, hvad der tæller som et brud. Cargos guide nævner
ændringer, der ser harmløse ud, men ikke er det: At tilføje en
variant til en offentlig enum bryder kode, der matcher udtømmende på
den, medmindre enum'en var markeret med `#[non_exhaustive]` fra
starten, og i sjældne tilfælde med glob-importer kan selv et nyt
offentligt element give en kompileringsfejl. Specifikationens svar,
når fejlen bliver opdaget, er at udgive en ny minor-version, der
genopretter kompatibiliteten, aldrig at ændre den udgivelse, der
allerede er ude, og at fortælle brugerne, hvilken version der var
skyld i det. Hos dem, der bruger pakken, er det en låsefil, der
ligger i repositoryet, og test, der kører ved hver opdatering, som
fanger bruddet, før produktionen gør det.

At blive på 0.x i årevis. Ifølge specifikationen har major-version
nul slet ikke et stabilt API. Dens FAQ siger det ligeud: Bruges
softwaren allerede i produktion, bør den efter al sandsynlighed
allerede være 1.0.0. Værktøjerne udfylder hullet med deres egen
konvention: Cargo og node-semver betragter det første tal fra
venstre, der ikke er nul, som det brydende, så `^0.2.3` accepterer
kun flere 0.2.x-udgivelser, og `^0.0.3` accepterer slet ingen
opdateringer. Et bibliotek, der har stået på 0.x i årevis, har
brugere, der afhænger af det, men intet defineret løfte til dem.
Udgiv 1.0.0, når folk er afhængige af API'et; det ændrer et tal,
ikke koden.

At læse mere ind i nummeret, end det siger. Kompatibilitet efter
specifikationen handler om det offentlige API. Cargos guide placerer
det at hæve den mindste Rust-version, en crate kræver, under
muligvis brydende og anbefaler generelt at behandle det som en
minor-ændring, så en minor-opdatering kan stoppe buildet på en ældre
toolchain. Sætter man `package.rust-version`, kan Cargos resolver
forsøge med ældre versioner af craten, når det er nødvendigt.
Licensvilkår, ydeevne og opførsel, som API'et aldrig har
dokumenteret, ligger helt uden for nummeret. Tjek dem for sig, med
en licensgennemgang og test, i stedet for at udlede dem af en
minor-udgivelse.

To major-versioner i ét build. Når to afhængigheder kræver
inkompatible versioner af samme crate, for eksempel 0.6 og 0.7,
bygger Cargo dem begge. Compileren betragter deres typer som
forskellige, selv når navnene er ens. Det viser sig som regel som en
kompileringsfejl, men nogle gange først under kørsel: Cargos
dokumentation beskriver en downcast, der fejler, fordi objektet blev
oprettet af et bibliotek, der bruger version 1.0.0, mens den
kaldende kode downcaster til typen fra 2.0.0. `cargo tree -d` viser
dublerede versioner, og hvor de kommer fra. En biblioteksforfatter
kan gøre en major-udgivelse mindre smertefuld med det, Cargos
dokumentation kalder »the semver trick«: Udgiv den nye
major-version, og udgiv derefter en punktudgivelse af den gamle, der
reeksporterer typerne fra den nye.

Læs mere

  * Semantic Versioning 2.0.0 — specifikationen og dens FAQ, blandt
andet om, hvad man gør, når man ved en fejl har udgivet en brydende
ændring. Findes også i dansk oversættelse.

  * SemVer Compatibility — Cargo Books guide til, hvilke ændringer i
et Rust-bibliotek der er major, minor eller muligvis brydende, hver
med et eksempel.

  * Specifying Dependencies — Cargos syntaks for krav: standard,
caret, tilde og sammenligninger, og hvordan pre-releases bliver
matchet.

  * Dependency Resolution — hvordan Cargo vælger versioner, hvad
låsefilen indeholder, og farerne ved to inkompatible versioner i
samme graf.

  * node-semver — npm's værktøj til semantiske versioner med
reglerne for caret, tilde og pre-releases i intervaller.

  * Go Modules Reference — suffikser for major-versioner, reglen om
importkompatibilitet og minimal version selection.

hDenne side på nettet	URL:https://engineer.company/da/glossary/semantic-versioning/	engineer.company	70
