Making a Release

Releases are how maintainers tell the world—or, more accurately, downstream developers—that it's time to update their dependencies.

Version numbering

Versions are just numbers, but they can hold special meaning when it comes to describing what kind of release you're making, or from where the code is coming from, or (in case of libraries) the compatibility promise you are making.

The typical versioning scheme adopted by GNOME software is in the form:

    MAJOR_VERSION DOT MINOR_VERSION DOT MICRO_VERSION

For stable releases, MINOR_VERSION is typically an even number; for development snapshots, the MINOR_VERSION is typically an odd number.

Micro releases—also known as "point" releases, or "patch" releases—typically use an even MINOR_VERSION; ddd minor versions are reserved for code in Git.

If you are making a new micro release for your own project, it is highly recommended that you follow this scheme:

  1. increment your micro version by one so that it is an even number

  2. release your module
  3. increment your micro version by one so that is is an odd number

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).

Releasing

  • Make sure you’re up to date:
    • git pull

  • Make sure you don’t have local changes and/or revisions:
    • git status

  • 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 using Autotools, update the LT_VERSION string to control the SONAME of the library. There’s usually a comment in meson.build or configure.ac 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)
    • It is strongly recommended that you tie your SONAME versioning scheme to the project's version number, and you follow the rule of only ever adding and deprecating API in development cycles with an odd minor version number.

  • 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, if present.

  • For applications, add a <release> entry in the AppData file

    • You should read through the Git commit log and come up with a bullet point for each significant change and credit the person(s) who did the work. For modules using GitLab, this script should do most of the work for you. 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 all the commits under the po directory. Note that the actual translator isn’t always the one with who pushed the commit—try to credit the correct person/team. The format is $locale ($translator). Sort alphabetically by locale.

  • Use the AppData file to generate a NEWS file; if you are releasing a library, you can write the NEWS file directly

    • 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 script or this one might assist you.

  • Do a git commit.

  • Do a ninja dist or ./autogen.sh && make && make install && make distcheck. Fix any issues that crop up. Distcheck errors can be particularly 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)

    • If you need to make additional changes to fix distcheck, don’t forget to re-commit.

  • Distcheck finishes. It should show you something like this:
    • ==================================================
      gnome-panel-2.3.1.tar.gz is ready for distribution
      ==================================================
    • or
    • Distribution package /opt/gnome/build/glib/meson-dist/glib-2.57.3.tar.xz tested.
  • 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.
    • $ git evtag sign 2.3.1 or $ git tag -s 2.3.1 (from whatever branch you’re releasing)

    Use git-evtag if possible, to provide stronger signing guarantees. Otherwise, use normal git tag -s.

  • Do a git push --atomic origin master 2.3.1. If that fails because someone has pushed since you last updated, then you’ll need to repeat the entire process. Well, update, add a new NEWS entry, update the release commit and tag, and make distcheck again.

  • 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 ftpadmin install. There are no extra steps required for new modules. For example:

    • $ ssh (user)@master.gnome.org ftpadmin install 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. Finally, make sure to add a SOURCES file detailing how to build the binaries. When you are done, run signal-ftp-sync on master.gnome.org.

MaintainersCorner/Releasing (last edited 2019-05-10 14:37:46 by EmmanueleBassi)