Sémantické verzování (SemVer) a releasy na GitHubu

Verze 2.4.1 není jen číslo. Podle sémantického verzování (SemVer) říká uživatelům vaší knihovny nebo API, zda je aktualizace bezpečná. Ukážeme si pravidla, práci s Git tagy a jak releasy na GitHubu vytvářet ručně i automaticky.

Formát MAJOR.MINOR.PATCH

Část	Zvyšte, když…	Příklad
MAJOR	provedete zpětně nekompatibilní změnu	odstraněný endpoint, změněný formát odpovědi
MINOR	přidáte funkci zpětně kompatibilně	nový volitelný parametr, nový endpoint
PATCH	opravíte chybu zpětně kompatibilně	oprava výpočtu, bezpečnostní záplata

Při zvýšení vyšší části se nižší vynulují: 1.4.7 → 1.5.0 → 2.0.0.

Klíčové je, co považujete za veřejné API: funkce knihovny, HTTP endpointy, formát konfigurace, CLI přepínače. Změna interní funkce, kterou nikdo zvenku nevolá, není breaking change.

Speciální případy

Verze 0.y.z – počáteční vývoj. Podle specifikace se cokoli může kdykoli změnit a veřejné API se nepovažuje za stabilní. Verzí 1.0.0 deklarujete stabilní API.

Pre-release – za pomlčkou:

2.0.0-alpha.1 < 2.0.0-alpha.2 < 2.0.0-beta.1 < 2.0.0-rc.1 < 2.0.0

Build metadata – za plusem, při porovnávání verzí se ignorují: 1.3.0+20261012.abc123.

Prefix v u tagů (v1.2.3) není součástí SemVer, ale je to běžná konvence v Gitu.

Co verze znamenají pro závislosti

Správci balíčků se SemVer řídí při rozsazích verzí:

Zápis (npm)	Povolí
^1.4.2	>=1.4.2 <2.0.0 (minor + patch)
~1.4.2	>=1.4.2 <1.5.0 (jen patch)
1.4.2	přesně tuto verzi

Pozor: u verzí 0.x je ^0.4.2 přísnější a povolí jen <0.5.0. Proto je správné verzování důležité – když vydáte breaking change jako minor, rozbijete projekty všem, kdo používají ^.

V Pythonu (PEP 440) podobně funguje ~=1.4.2 (>=1.4.2, <1.5).

Git tagy

Release označte anotovaným tagem (obsahuje autora, datum a zprávu):

git switch main && git pull
git tag -a v1.5.0 -m "Verze 1.5.0"
git push origin v1.5.0

Užitečné příkazy:

git tag --list "v1.*"               # výpis tagů
git describe --tags                 # nejbližší tag k aktuálnímu commitu
git log v1.4.0..v1.5.0 --oneline    # co se změnilo mezi verzemi
git tag -d v1.5.0                   # smazat lokálně
git push origin --delete v1.5.0     # smazat na GitHubu

Už zveřejněný tag neměňte ani nepřesouvejte – někdo si ho mohl stáhnout. Chybu opravte novou patch verzí.

GitHub Releases

Release na GitHubu je tag doplněný o poznámky a volitelně soubory ke stažení. Nejrychleji přes CLI:

gh release create v1.5.0 --generate-notes
gh release create v2.0.0-rc.1 --prerelease --generate-notes
gh release create v1.5.0 ./dist/app-linux-amd64.tar.gz --title "1.5.0"

--generate-notes sestaví seznam sloučených pull requestů a přispěvatelů od posledního releasu.

Kategorie v automatických poznámkách

Soubor .github/release.yml rozřadí PR podle labelů:

changelog:
  exclude:
    labels: [skip-changelog]
  categories:
    - title: "⚠️ Breaking changes"
      labels: [breaking]
    - title: "✨ Nové funkce"
      labels: [enhancement]
    - title: "🐛 Opravy"
      labels: [bug]
    - title: "Ostatní"
      labels: ["*"]

Release workflow v GitHub Actions

Sestavení a nahrání artefaktů po pushnutí tagu:

name: Release
on:
  push:
    tags: ["v*.*.*"]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make build
      - name: Vytvořit release
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes

permissions: contents: write je potřeba, aby výchozí token mohl release vytvořit. Základy workflow najdete v článku GitHub Actions: první workflow.

Plná automatizace: Conventional Commits + release-please

Pokud píšete commity podle Conventional Commits, lze verzi určit automaticky: fix: → patch, feat: → minor, feat!: nebo BREAKING CHANGE: → major.

Nástroj release-please od Googlu to dělá přes pull requesty:

name: release-please
on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: node

Po každém pushi do main udržuje otevřený „release PR“ s vygenerovaným CHANGELOG.md a zvýšenou verzí v package.json. Když PR sloučíte, vytvoří tag a GitHub Release. Podporuje i Python, Go, Rust a další (release-type: python, go, rust, simple).

Alternativou je semantic-release, který vydává rovnou bez mezikroku s PR.

CHANGELOG.md

I s automatickými poznámkami se vyplatí udržovat changelog v repozitáři. Rozšířený formát „Keep a Changelog“ dělí změny do sekcí Added, Changed, Deprecated, Removed, Fixed, Security a nahoře drží sekci Unreleased.

Shrnutí

1. Určete, co je vaše veřejné API.
2. Breaking change = major, nová funkce = minor, oprava = patch.
3. Release = anotovaný tag + GitHub Release s poznámkami.
4. Zveřejněné verze neměňte.
5. S Conventional Commits nechte verzování na nástroji.