SemVer (sémantické verzování)

Příklady z praxe

1. 01

   Změna signatury v klientské knihovně

   Knihovna změnila tvar veřejného API pro načítání uživatele. Protože starý kód po aktualizaci přestane fungovat, správné vydání je nová major verze, například z 2.4.1 na 3.0.0. Uživatelé balíčku mohou podle čísla poznat, že migrace nebude jen běžná oprava.

   // Verze 2.4.1
   client.getUser(id)
   
   // Verze 3.0.0
   client.users.get({ id })

2. 02

   Automatická aktualizace závislosti

   Aplikace má v package.json povolený rozsah závislosti od 1.8.0 v rámci kompatibilních verzí. Správce balíčků může při instalaci zvolit novější minor nebo patch vydání, pokud pravidla daného nástroje takový rozsah dovolují. Lockfile pak pomáhá zajistit, že CI a produkce použijí stejný konkrétní build.

   {
     "dependencies": {
       "date-tools": "^1.8.0"
     }
   }

Časté omyly

MýtusKdyž změním jen interní implementaci, musím zvýšit major verzi.

Ve skutečnostiSemVer se řídí dopadem na veřejné rozhraní, ne velikostí interní práce. Interní přepis může být patch release, pokud zachová smluvené chování pro uživatele API.

MýtusPatch verze je vždy úplně bezpečná aktualizace.

Ve skutečnostiPatch verze má podle pravidel značit kompatibilní opravu, ale číslo verze samo o sobě nezaručuje kvalitu. Bez testů, lockfile a kontroly changelogu může i patch aktualizace způsobit problém.

Časté dotazy

Kdy má projekt začít používat SemVer?

SemVer má smysl zavést ve chvíli, kdy software používá někdo jiný než původní autor a změny mohou rozbít cizí kód, skripty nebo integrační smlouvy. U interního prototypu může stačit datum nebo číslo buildu. U knihovny, SDK, CLI nástroje nebo veřejného API ale SemVer pomáhá uživatelům plánovat aktualizace a odlišit běžnou opravu od migrace.

Co je v SemVeru breaking change?

SemVer považuje breaking change za změnu, která poruší dříve slíbené veřejné rozhraní. Typicky jde o odstranění metody, změnu názvu parametru, jiný formát odpovědi, nově povinné pole nebo změnu chování, na které se uživatelé mohli spoléhat. Interní refactoring bez dopadu na veřejné API breaking change být nemusí, i když je rozsáhlý.

Znamená major verze vždy velkou technologickou změnu?

SemVer sám nevyžaduje, aby každá nová major verze znamenala velký přepis systému. Major verze pouze říká, že existuje nekompatibilní změna veřejného rozhraní. Malá úprava může vyžadovat major release, pokud rozbije smlouvu s uživateli. Naopak rozsáhlý interní refactoring může zůstat patch nebo minor, pokud zachová kompatibilitu.

Dá se SemVer použít pro REST API?

SemVer může fungovat i u REST API, pokud služba jasně definuje veřejný kontrakt: cesty, metody, schémata požadavků, schémata odpovědí, chybové kódy a autentizaci. Číslo verze pak pomáhá rozlišit kompatibilní rozšíření od změn, které klienti musí upravit. U webových API se SemVer často kombinuje s verzovanými endpointy nebo verzemi klientského SDK.

Zdroje

1. Software versioning(otevře se v novém okně)Wikipedia
2. Package versioning(otevře se v novém okně)Microsoft
3. Git - Tagging(otevře se v novém okně)Git
4. Modules: Packages(otevře se v novém okně)Node.js

Související pojmy

• Blue-green deploymentBlue-green deployment je způsob nasazování aplikací, při kterém běží dvě identická produkční prostředí: jedno obsluhuje provoz, druhé přijímá novou verzi. Po ověření nové verze se provoz přepne najednou, obvykle na úrovni load balanceru nebo DNS. Staré prostředí zůstává nedotčené, takže návrat k předchozí verzi je otázkou vteřin.
• BranchBranch je pojmenovaný ukazatel na konkrétní commit ve verzovacím systému, který umožňuje vyvíjet změny odděleně od hlavní linie kódu. Ve výchozím nastavení se posouvá dopředu s každým novým commitem. Díky větvím může na jednom repozitáři pracovat víc lidí současně, aniž by si navzájem rozbíjeli rozpracovanou práci.
• CI/CDCI/CD je sada postupů a automatizací, které průběžně integrují změny kódu, ověřují je testy a připravují nebo provádějí nasazení aplikace. Cílem je zkrátit cestu od commitu k bezpečnému vydání, snížit ruční práci a rychle odhalit chyby v build procesu, konfiguraci nebo samotném kódu.
• ACIDACID je sada čtyř vlastností databázové transakce: atomicity, consistency, isolation a durability. Zaručuje, že skupina zápisů proběhne jako jeden celek, neporuší definovaná pravidla databáze, nebude se nebezpečně míchat s jinými transakcemi a po potvrzení přežije pád systému, například při převodu peněz.
• Adaptive IconAdaptivní ikona je formát ikony aplikace na Androidu, který se místo jedné hotové bitmapy skládá z oddělených vrstev: pozadí a popředí. Systém výsledný tvar sám ořízne podle masky výrobce zařízení a může vrstvy animovat nebo přebarvit. Vývojář tak dodá jeden zdroj a launcher z něj vytvoří kruh, čtverec i squircle.
• Adresa v pamětiAdresa v paměti je číslo, kterým procesor jednoznačně označuje konkrétní buňku operační paměti, obvykle jeden bajt. Program pomocí adresy říká, odkud má data načíst nebo kam je zapsat. Adresy tvoří souvislý číselný rozsah, jehož velikost určuje šířka adresní sběrnice a architektura, typicky 32 nebo 64 bitů.
• AI agentAI agent je softwarový systém, který pomocí modelu umělé inteligence vnímá zadaný kontext, plánuje další kroky a samostatně volá nástroje nebo služby k dosažení cíle. Na rozdíl od jednorázového promptu udržuje stav úlohy, vyhodnocuje výsledky akcí a může opakovat postup, dokud nesplní zadání nebo nenarazí na limit.
• AndroidAndroid je operační systém postavený nad linuxovým jádrem, který vyvíjí Google a otevřeně uvolňuje jako projekt AOSP. Android pohání převážnou většinu chytrých telefonů, dále tablety, televize, hodinky i palubní systémy aut. Aplikace se pro něj píší hlavně v Kotlinu nebo Javě a distribuují přes Google Play i alternativní obchody.