versioning.page 9.56 KB
Newer Older
1 2 3 4 5 6
<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      type="topic"
      id="versioning">

  <info>
7
    <link type="guide" xref="index#maintainer-guidelines"/>
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

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

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

    <desc>Versioning and releasing libraries and applications</desc>
  </info>

  <title>Versioning</title>

  <synopsis>
    <title>Summary</title>

    <p>
      Module versioning differs for libraries and applications: libraries need a
      libtool version specified in addition to their package version.
      Applications just have a package version.
    </p>

    <list>
      <item><p>
33 34
        Libraries and applications have a package version of the form
        <em>major.minor.micro</em>. (<link xref="#package-versioning"/>)
35 36
      </p></item>
      <item><p>
37 38
        Libraries additionally have a libtool version of the form
        <em>current:revision:age</em>. (<link xref="#libtool-versioning"/>)
39 40
      </p></item>
      <item><p>
41
        Version numbers should be updated for each release (using release and
42 43 44 45
        post-release increments). (<link xref="#release-process"/>)
      </p></item>
      <item><p>
        Package versions should be incremented for feature changes or additions.
46
        (<link xref="#package-versioning"/>)
47 48 49
      </p></item>
      <item><p>
        Libtool versions should be updated for API changes or additions.
50
        (<link xref="#libtool-versioning"/>)
51
      </p></item>
52 53 54 55
      <item><p>
        Even/odd <em>minor</em> package versions can be used respectively for
        stable/unstable releases. (<link xref="#stable-unstable-versions"/>)
      </p></item>
56 57 58
    </list>
  </synopsis>

59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
  <section id="package-versioning">
    <title>Package Versioning</title>

    <p>
      Both libraries and applications have a package version of the form
      <em>major.minor.micro</em>.
    </p>

    <p>
      The package version number is that passed to
      <code>AC_INIT()</code>, and the one which is typically known as the
      projects version number. For example, the Debian package for a library
      will use the librarys package version (though may also include the major
      version number in the package name to allow for
      <link xref="parallel-installability">parallel installability</link>).
      Package versions are updated by the following rules:
    </p>
    <steps>
      <item><p>
        If breaking <link xref="api-stability">API compatibility</link> in a
        library, or making a large change to an application which affects
        everything (such as a UI redesign), increment major and set minor and
        micro to 0.
      </p></item>
      <item><p>
        Otherwise, if changing or adding a feature, or adding any API,
        increment minor and set micro to 0.
      </p></item>
      <item><p>
        Otherwise (if making a release containing only bug fixes and
        translation updates), increment micro.
      </p></item>
    </steps>

    <p>
      Note that the minor version number should be updated if any API is added.
    </p>
  </section>

  <section id="libtool-versioning">
    <title>Libtool Versioning</title>
100 101 102

    <p>
      Libraries have two version numbers: a libtool version which tracks ABI
103 104
      backwards compatibility (see <link xref="api-stability"/>), and a package
      version which tracks feature
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
      changes. These are normally incremented in synchronization, but should be
      kept separate because ABI backwards compatibility is not necessarily
      related to feature changes or bug fixes. Furthermore, the two version
      numbers have different semantics, and cannot be automatically generated
      from each other.
    </p>

    <p>
      A good overview of libtool versioning, and the differences from package
      versioning, is given in the
      <link href="https://autotools.io/libtool/version.html">Autotools
      Mythbuster</link>; another is in the
      <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">libtool
      manual</link>.
    </p>

    <p>
      To update the libtool version, follow the algorithm given in the comments
      below. This is a typical <file>configure.ac</file> snippet for setting up
      libtool versioning:
    </p>

    <code>
# Before making a release, the LT_VERSION string should be modified. The
# string is of the form c:r:a. Follow these instructions sequentially:
#   1. If the library source code has changed at all since the last update, then
#      increment revision (c:r:a becomes c:r+1:a).
#   2. If any interfaces have been added, removed, or changed since the last
#      update, increment current, and set revision to 0.
#   3. If any interfaces have been added since the last public release, then
#      increment age.
#   4. If any interfaces have been removed or changed since the last public
#      release, then set age to 0.
AC_SUBST([LT_VERSION],[0:0:0])</code>

    <p>
      The following snippet can be used in a <file>Makefile.am</file> to pass
      that version info to libtool:
    </p>
    <code>my_library_la_LDFLAGS = -version-info $(LT_VERSION)</code>
  </section>

147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
  <section id="stable-unstable-versions">
    <title>Stable and Unstable Package Versions</title>

    <p>
      Most GNOME modules follow a convention for stable and unstable releases.
      The minor version is even for stable releases and is odd for unstable
      releases.  For example, the 3.20.* versions are stable, but the 3.19.*
      versions are unstable.  The 3.19.* versions can be seen as alpha and beta
      releases of the 3.20 version.
    </p>

    <p>
      A new micro <em>stable</em> version (e.g. 3.20.0  3.20.1) doesnt add
      new features, only translation updates and bug fixes.  On the other hand,
      <em>unstable</em> micro releases (e.g. 3.19.1  3.19.2) can add API, or
      change or remove API which was added in a previous micro release in that
      minor series.
    </p>

    <p>
      The libtool version should be updated only for stable package versions.
    </p>
  </section>

171 172 173 174 175
  <section id="release-process">
    <title>Release Process</title>

    <p>
      The standard process for making a release of a module increments the
176 177 178
      libtool version (if the module is a library) at the time of release, then
      increments the package version number immediately afterwards (this is
      called a post-release increment).
179 180 181
    </p>

    <p>
182
      Updating the libtool versions at the time of release means that they are
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
      only incremented once for all ABI changes in a release. The use of
      post-release increment for package versions means the package version
      number is not outdated (still equal to the previous release) during
      the development cycle.
    </p>

    <p>
      The release process (based on the
      <link href="https://wiki.gnome.org/MaintainersCorner/Releasing">GNOME
      release process</link>):
    </p>
    <steps>
      <item><p>
        Make sure code is up to date: <cmd>git pull</cmd>
      </p></item>

      <item><p>
        Make sure you have no local changes: <cmd>git status</cmd>
      </p></item>
      <item><p>
203 204
        If the release is for a stable package version, increment the libtool
        version number in <file>configure.ac</file> (if it exists)
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233
      </p></item>
      <item><p>
        Add an entry to the <file>NEWS</file> file
      </p></item>
      <item>
        <p>
          Run
          <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd>
          and ensure it succeeds
        </p>
        <list>
          <item><p>
            Fix any issues which come up, commit those changes, and restart at
            step 3
          </p></item>
        </list>
      </item>
      <item><p>
        If <cmd>make distcheck</cmd> finishes with [archive] is ready for
        distribution, run <cmd>git commit -a -m "Release version x.y.z"</cmd>
        (where x.y.z is the package version number)
      </p></item>
      <item>
        <p>
          Run <cmd>git push</cmd>
        </p>
        <list>
          <item><p>
            If that fails due to other commits having been pushed in the
234 235 236 237 238
            meantime, run <cmd>git pull</cmd> to merge your commit on the
            branch followed by a second <cmd>git push</cmd>.  This is an
            exception to the GNOME guideline to have a linear Git history
            (<link xref="version-control#use-of-git"/>).  If you prefer to have
            a linear history, you need to restart at step 1.
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273
          </p></item>
        </list>
      </item>
      <item><p>
        Tag the release: <cmd>git tag -s x.y.z</cmd> (where x.y.z is the
        package version number)
      </p></item>
      <item><p>
        Run <cmd>git push origin x.y.z</cmd> (where x.y.z is the package
        version number)
      </p></item>
    </steps>

    <p>
      The release is now complete, and the post-release version increment can be
      done:
    </p>
    <steps>
      <item><p>
        Increment the package version number in <file>configure.ac</file>
      </p></item>
      <item><p>
        Run <cmd>git commit -a -m "Post-release version increment"</cmd>
      </p></item>
      <item><p>
        Run <cmd>git push</cmd>
      </p></item>
    </steps>

    <p>
      The package archive generated by <cmd>make distcheck</cmd> can now be
      uploaded to download.gnome.org or distributed in other ways.
    </p>
  </section>
</page>