Philip Withnall philip.withnall@collabora.co.uk 2015 Číslování verzí a vydávání knihoven a aplikací Číslování verzí Shrnutí

Číslování verzí se liší pro knihovny a pro aplikace: knihovny potřebují mít mimo čísla verze pro balíček určené i číslo verze pro libtool. Aplikace mají jen číslo verze pro balíček.

Knihovny a aplikace mají čísla verzí balíčků ve formě hlavní.vedlejší.setinkové. ()

Knihovny navíc mají číslo verze pro libtool ve formě aktuální:revize:věk. ()

Číslo verze by mělo být aktualizováno u každého vydání (použijte zvýšení čísla při vydání a po vydání). ()

Číslo verze balíčku by mělo být zvýšeno při změně nebo přidání funkcionality. ()

Číslo verze libtool by mělo být aktualizováno při změnách nebo přidání API. ()

Lichá/sudá vedlejší čísla verze balíčku mohou být použita k rozlišení stabilních/nestabilních vydání. ()
Číslování verzí balíčků

Knihovny i aplikace mají čísla verzí balíčků ve formě hlavní.vedlejší.setinkové (major.minor.micro).

Číslo verze balíčku je to, které se předává do AC_INIT() a bývá známé jako číslo verze projektu. Například balíček ve formátu DEB (používaný distribucí Debian) pro knihovnu bude používat číslo verze balíčku s knihovnou (ačkoliv může v názvu balíčku obsahovat i hlavní číslo verze, aby se umožnila souběžná instalace). Verze balíčku jsou aktualizovány podle následujících pravidel:

Při porušení kompatibility API v knihovně nebo při provedení rozsáhlých změn v aplikaci, které ovlivní vše (třeba změna návrhu uživatelského rozhraní), zvyšte hlavní číslo verze a vedlejší a setinkové nastavte na 0.

V ostatních případech, když měníte nebo přidáváte funkce nebo přidáváte nějaké API, zvyšte vedlejší číslo verze a setinkové nastavte na 0.

V ostatních případech (když vydání obsahuje jen opravy chyb a aktualizace překladů), zvyšte setinkové číslo verze.

Nezapomeňte, že vedlejší číslo verze by mělo být aktualizováno, když je přidáno nějaké API.

Čísla verzí pro Libtool

Knihovny mají dvě čísla verze: verzi libtool, která sleduje zpětnou kompatibilitu ABI (viz ) a číslo verze balíčku, které sleduje změny vlastností. Normálně jsou zvyšovány současně, ale měly by se udržovat oddělené, protože zpětná kompatibilita ABI nemusí nutně souviset se změnami vlastností nebo opravami chyb. Navíc tato dvě číslování mají rozdílnou sémantiku a není tak možné vygenerovat jedno na základě druhého.

Dobrý přehled o číslování verzí libtool a o rozdílech oproti číslování verzí balíčků najdete v článku Autotools Mythbuster, a případně také v příručce k libtool.

Při aktualizaci verze libtool postupujte podle algoritmu uvedeném v komentářích níže. Jedná se o typický úryvek z configure.ac pro nastavení verze libtool:

# Před vydáním by se měl upravit řetězec LT_VERSION, který je ve formě a:r:v # (aktuální:revize:věk). Postupujte podle následujících bodů: # 1. Když od poslední aktualizace došlo ke změně zdrojového kódu knihovny # jako celku, zvyšte revizi („a:r:v“ se změní na „a:r+1:v“). # 2. Když bylo od poslední aktualizace přidáno, odebráno nebo změněno # rozhraní, zvyšte aktuální a revizi nastavte na 0. # 3. Když bylo od posledního veřejného vydání přidáno rozhraní, zvyšte věk. # 4. Když bylo od posledního veřejného vydání odebráno nebo změněno # rozhraní, nastavte věk na 0. AC_SUBST([LT_VERSION],[0:0:0])

Následující úryvek můžete použít v souboru Makefile.am k předání informace o verzi do libtool:

my_library_la_LDFLAGS = -version-info $(LT_VERSION)
Stabilní a nestabilní verze balíčku

Většina modulů GNOME dodržuje zvyklost stabilních a nestabilních vydání. Vedlejší číslo verze je sudé pro stabilní vydání a liché pro nestabilní vydání. Například verze 3.20.* jsou stabilní, ale 3.19.* nestabilní. Na verze 3.19.* můžete pohlížet jako na alfa a beta vydání pro verzi 3.20.

Nové setinkové stabilní verze (např. 3.20.0 → 3.20.1) nepřidávají nové funkce, ale jen aktualizace překladů a opravy chyb. Naproti tomu, nestabilní setinkové verze (např. 3.19.1 → 3.19.2) mohou přidat API nebo změnit nebo odstranit API, které bylo přidáno v předchozí setinkové verzi stejné vedlejší série.

Číslo verze pro libtool by mělo být aktualizováno jen pro stabilní verzi balíčku.

Proces vydání

Standardní proces tvorby vydání modulu zvyšuje v průběhu vydání číslo verze pro libtool (pokud je modul knihovnou) a bezprostředně po té zvýší číslo verze balíčku (tzv. post-release zvýšení).

Aktualizace verze libtool v době vydání znamená, že je zvýšena jen jednou naráz pro všechny změny ABI ve vydání. Použití zvýšení po vydání pro číslo verze balíčku znamená, že číslo verze balíčku nebude zastaralé (pořád stejné jako u předchozího vydání) během vývojového cyklu.

Proces vydání (vycházející z procesu vydávání GNOME):

Zkontrolujte, že je kód aktuální: git pull

Zkontrolujte, že nemáte provedené žádné místní změny: git status

V případě, že se jedná o vydání pro stabilní verzi balíčku, zvyšte číslo verze pro libtool v configure.ac (pokud existuje)

Přidejte záznam do souboru NEWS

Spusťe ./autogen.sh && make && make install && make distcheck a ověřte, že vše proběhlo v pořádku

Opravte případné problémy, které nastaly, zařaďte je a vraťte se ke kroku 3

Pokud make distcheck skončí s „[archive] is ready for distribution“, spusťte git commit -a -m "Release version x.y.z" (kde „x.y.z“ je číslo verze balíčku)

Spusťte git push

Pokud to selže, protože během správy byly nahrány další zařazení, spusťte git pull, aby se sloučily vaše zařazení s větví následovanou po druhém git push. Jedná se o výjimku oproti pokynům GNOME, které říkají, že máte mít v Git lineární historii (). Pokud dáváte lineární historii přednost, musíte se vrátit ke kroku 1.

Přidělte vydání štítek: git tag -s x.y.z (kde „x.y.z“ je číslo verze balíčku)

Spusťte git push origin x.y.z (kde „x.y.z“ je číslo verze balíčku)

Vydání je nyní hotové a můžete provést (post-release) zvýšení čísla verze pro následující vydání:

Zvyšte číslo verze balíčku v configure.ac

Spusťte git commit -a -m "Post-release version increment"

Spusťte git push

Balíček vygenerovaný pomocí make distcheck může být nyní nahrán na download.gnome.org nebo šířen nějakým jiným způsobem.