Making a Release

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


  • 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 or 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
    • 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_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
                * Blah blah blah
                * 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 ./ && 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 in the component it comes from—this can be the case if the files are referenced by po/ but someone forgot to add that file to the

    • 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, by scp-ing it to All module maintainers who wish to be able to upload tarballs should request a shell account at for this purpose—see Infrastructure/NewAccounts. 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)

  • Then ssh into and call ftpadmin install. There are no extra steps required for new modules. For example:

    • $ ssh (user) 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, 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

MaintainersCorner/Releasing (last edited 2021-01-25 17:58:43 by MatthewLeeds)