<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="versioning" xml:lang="cs">

  <info>
    <link type="guide" xref="index#maintainer-guidelines"/>

    <credit type="author copyright">
      <name>Philip Withnall</name>
      <email its:translate="no">philip.withnall@collabora.co.uk</email>
      <years>2015</years>
    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Číslování verzí a vydávání knihoven a aplikací</desc>
  </info>

  <title>Číslování verzí</title>

  <synopsis>
    <title>Shrnutí</title>

    <p>Čí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.</p>

    <list>
      <item><p>Knihovny a aplikace mají čísla verzí balíčků ve formě <em>hlavní.vedlejší.setinkové</em>. (<link xref="#package-versioning"/>)</p></item>
      <item><p>Knihovny navíc mají číslo verze pro libtool ve formě <em>aktuální:revize:věk</em>. (<link xref="#libtool-versioning"/>)</p></item>
      <item><p>Čí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í). (<link xref="#release-process"/>)</p></item>
      <item><p>Číslo verze balíčku by mělo být zvýšeno při změně nebo přidání funkcionality. (<link xref="#package-versioning"/>)</p></item>
      <item><p>Číslo verze libtool by mělo být aktualizováno při změnách nebo přidání API. (<link xref="#libtool-versioning"/>)</p></item>
      <item><p>Lichá/sudá <em>vedlejší</em> čísla verze balíčku mohou být použita k rozlišení stabilních/nestabilních vydání. (<link xref="#stable-unstable-versions"/>)</p></item>
    </list>
  </synopsis>

  <section id="package-versioning">
    <title>Číslování verzí balíčků</title>

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

    <p>Číslo verze balíčku je to, které se předává do <code>AC_INIT()</code> 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 <link xref="parallel-installability">souběžná instalace</link>). Verze balíčku jsou aktualizovány podle následujících pravidel:</p>
    <steps>
      <item><p>Při porušení <link xref="api-stability">kompatibility API</link> 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.</p></item>
      <item><p>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.</p></item>
      <item><p>V ostatních případech (když vydání obsahuje jen opravy chyb a aktualizace překladů), zvyšte setinkové číslo verze.</p></item>
    </steps>

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

  <section id="libtool-versioning">
    <title>Čísla verzí pro Libtool</title>

    <p>Knihovny mají dvě čísla verze: verzi libtool, která sleduje zpětnou kompatibilitu ABI (viz <link xref="api-stability"/>) 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.</p>

    <p>Dobrý přehled o číslování verzí libtool a o rozdílech oproti číslování verzí balíčků najdete v článku <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link>, a případně také v <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">příručce k libtool</link>.</p>

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

    <code>
# 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])</code>

    <p>Následující úryvek můžete použít v souboru <file>Makefile.am</file> k předání informace o verzi do libtool:</p>
    <code>my_library_la_LDFLAGS = -version-info $(LT_VERSION)</code>
  </section>

  <section id="stable-unstable-versions">
    <title>Stabilní a nestabilní verze balíčku</title>

    <p>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.</p>

    <p>Nové setinkové <em>stabilní</em> verze (např. 3.20.0 → 3.20.1) nepřidávají nové funkce, ale jen aktualizace překladů a opravy chyb. Naproti tomu, <em>nestabilní</em> 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.</p>

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

  <section id="release-process">
    <title>Proces vydání</title>

    <p>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í).</p>

    <p>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.</p>

    <p>Proces vydání (vycházející z <link href="https://wiki.gnome.org/MaintainersCorner/Releasing">procesu vydávání GNOME</link>):</p>
    <steps>
      <item><p>Zkontrolujte, že je kód aktuální: <cmd>git pull</cmd></p></item>

      <item><p>Zkontrolujte, že nemáte provedené žádné místní změny: <cmd>git status</cmd></p></item>
      <item><p>V případě, že se jedná o vydání pro stabilní verzi balíčku, zvyšte číslo verze pro libtool v <file>configure.ac</file> (pokud existuje)</p></item>
      <item><p>Přidejte záznam do souboru <file>NEWS</file></p></item>
      <item>
        <p>Spusťe <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd> a ověřte, že vše proběhlo v pořádku</p>
        <list>
          <item><p>Opravte případné problémy, které nastaly, zařaďte je a vraťte se ke kroku 3</p></item>
        </list>
      </item>
      <item><p>Pokud <cmd>make distcheck</cmd> skončí s „[archive] is ready for distribution“, spusťte <cmd>git commit -a -m "Release version x.y.z"</cmd> (kde „x.y.z“ je číslo verze balíčku)</p></item>
      <item>
        <p>Spusťte <cmd>git push</cmd></p>
        <list>
          <item><p>Pokud to selže, protože během správy byly nahrány další zařazení, spusťte <cmd>git pull</cmd>, aby se sloučily vaše zařazení s větví následovanou po druhém <cmd>git push</cmd>. Jedná se o výjimku oproti pokynům GNOME, které říkají, že máte mít v Git lineární historii (<link xref="version-control#use-of-git"/>). Pokud dáváte lineární historii přednost, musíte se vrátit ke kroku 1.</p></item>
        </list>
      </item>
      <item><p>Přidělte vydání štítek: <cmd>git tag -s x.y.z</cmd> (kde „x.y.z“ je číslo verze balíčku)</p></item>
      <item><p>Spusťte <cmd>git push origin x.y.z</cmd> (kde „x.y.z“ je číslo verze balíčku)</p></item>
    </steps>

    <p>Vydání je nyní hotové a můžete provést (post-release) zvýšení čísla verze pro následující vydání:</p>
    <steps>
      <item><p>Zvyšte číslo verze balíčku v <file>configure.ac</file></p></item>
      <item><p>Spusťte <cmd>git commit -a -m "Post-release version increment"</cmd></p></item>
      <item><p>Spusťte <cmd>git push</cmd></p></item>
    </steps>

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