Making A Release

If you are making a release for someone else, you'll need to know whether the module is using pre-release version incrementing (i.e. bumping the version number just before release) or post-release version incrementing (which is preferred). Most everybody used to bump the version number just before the release but we've found that bumping just after the release works better because people can explicitly require the version number in HEAD; i.e. if the last release of gtk+ was 2.5.1 and new API is added, its nice for any module that uses that API to immediately require gtk+ 2.5.2. You can tell which method a module is using by whether the version number in configure.in or configure.ac matches the version number of the last release of the module.

• Make sure you're up to date:

  • svn update

• If you have been using pre-release incrementing, increment the version number in configure.in or configure.ac. For instance, increase AM_INIT_AUTOMAKE(gnome-panel, 2.3.1).
• If you have a comment in some file (e.g. README) about whether the given version is stable or unstable, and you are switching from stable to unstable or vice-versa with this release, be sure to update the comment.
• For libraries, update the LT_VERSION string. There's usually a comment in configure.in that explains how this works. For instance:

  • # Before making a release, the LT_VERSION string should be modified.
    # The string is of the form C:R:A.
    # - If interfaces have been changed or added, but binary compatibility has
    #   been preserved, change to C+1:0:A+1
    # - If binary compatibility has been broken (eg removed or changed interfaces)
    #   change to C+1:0:0
    # - If the interface is the same as the previous version, change to C:R+1:A
    
    LIB_PANEL_APPLET_LT_VERSION=0:14:0
    AC_SUBST(LIB_PANEL_APPLET_LT_VERSION)

• For the gnome-desktop module only, update the overall GNOME version. For instance, here I am doing a release for GNOME 2.3.1 on March 14.

  • GNOME_PLATFORM=2
    GNOME_MINOR=3
    GNOME_MICRO=1
    GNOME_VENDOR="GNOME.org"
    GNOME_DATE="March 14, 2003"

• Update the version number at the top of the README file.

• To let other developer knows that you have incremented the version, add a ChangeLog entry at the top of the module's directory. For instance,

  • 2003-03-14  Mark McLoughlin  <mark@skynet.ie>
            * configure.in: Version 2.3.1.

• Add an entry to the NEWS file. You should read through the ChangeLog and come up with a bullet point for each significant change and credit the person(s) who did the work. Some tips:

  • If several entries relate to the same change only use a single bullet point.
  • Try to make the bullet points short and snappy but understandable for a general user. That's not always easy.
  • Do not forget to include updated dependencies, since it makes life easier for packagers.

  • Generate the list of translations from po/ChangeLog. Note that the actual translator isn't always the one with who added the ChangeLog entry--try to credit the correct person/team. The format is $locale($translator). Sort alphabetically by locale. You might use a format similar to the following (note that you can use one line per language for translations):

    • =============
      Version 2.3.1
      =============
      Panel
              * Blah blah blah
      Applets
              ....
      Miscellanous
              ....
      Translations
              * az (Metin Amiroff), be (Dmitry G. Mastrukov), bg (Alexander Shopov),
                da (Ole Laursen), eo (Joël Brich), es (Pablo Gonzalo del Campo),
                .... and zh_TW (Abel Cheung).

    The translations section is the most time-consuming part. This or this scripts might assist you.

• Do an ./autogen.sh && make && make install && make distcheck. Fix any issues that crop up. Distcheck errors can be particuarly difficult, but releasing often makes it easier to discover and fix these problems. Some tips:

  • If a file comes up not found during distcheck, check that the file in question has been added to the Makefile.am in the component it comes from -- this can be the case if the files are referenced by po/POTFILES.in but someone forgot to add that file to the Makefile.am.
  • Don't forget to unset environment variables like LINGUAS that influence tarball generation (translations in this case)

• While that's churning, compose a mail to gnome-announce-list@gnome.org and also the mailing list of your module. Don't actually send it until you have completed all of these steps.

• Distcheck finishes. It should show you something like this:

  • ==================================================
    gnome-panel-2.3.1.tar.gz is ready for distribution
    ==================================================

• Do a svn commit. If that fails because someone has committed since you last updated, then you'll need to repeat the entire process. Well, update, add a new NEWS entry, and make distcheck again.

• Tag the release; This will allow you to make a branch later if you so desire but for now, at least it make it easy to see what was included in a particular release. The commit message for the tag will be included in a changes file in the release directory. Here are three examples on how to do it:

  • $ svn cp svn+ssh://svn.gnome.org/svn/some-module/trunk svn+ssh://svn.gnome.org/svn/some-module/tags/SOME_MODULEL_2_3_1 (if you're releasing from trunk)

  • $ svn cp svn+ssh://svn.gnome.org/svn/some-module/branches/gnome-2-3 svn+ssh://svn.gnome.org/svn/some-module/tags/SOME_MODULE_2_3_1 (if you're releasing from a branch)

  • $ svn cp . svn+ssh://svn.gnome.org/svn/some-module/tags/SOME_MODULE_2_3_1 (this command should work in all cases)

• If you are using post-release incrementing (or if you have previously used pre-release incrementing and want to switch now), increment the version number in configure.in or configure.ac, make a corresponding ChangeLog entry, and commit the change.

• Upload the tarball to ftp.gnome.org, by scp-ing it to master.gnome.org. All module maintainers who wish to be able to upload tarballs should request a shell account at master.gnome.org for this purpose -- see AccountPolicy. Ask someone else to do it for you if you are waiting for an account. For example:

  • $ scp gnome-panel-2.3.1.tar.gz (user)@master.gnome.org:

• Then ssh into master.gnome.org and call install-module. For example:

  • $ install-module gnome-panel-2.3.1.tar.gz

  This will move the tarball to the appropriate directory, do some additional administrative stuff, and send an email to the ftp-release mailing list so that the release-team will know about it.
• If you provide Windows binaries of your package, then scp these to master.gnome.org, placing them into e.g. /ftp/pub/GNOME/binaries/win32/gnome-panel/2.3/. You will need to create a directory for your project if there isn't one already. Also make sure to add contact information into /ftp/pub/GNOME/binaries/win32/README in this case. When you are done, run signal-ftp-sync on master.gnome.org.
• Send the announcement email.