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 meson.build or configure.ac matches the version number of the last release of the module.
- Make sure you’re up to date:
- Make sure you don’t have local changes and/or revisions:
If you have been using pre-release incrementing, increment the version number in your meson.build or configure.ac. For instance, increase the version argument in the AM_INIT_AUTOMAKE macro.
- 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 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)
- 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.
Add an entry to the NEWS 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. 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).
Do a git commit.
- 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 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 and update the release tag.
- Distcheck finishes. It should show you something like this:
================================================== gnome-panel-2.3.1.tar.gz is ready for distribution ==================================================
Distribution package /opt/gnome/build/glib/meson-dist/glib-2.57.3.tar.xz tested.
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.
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.ac 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 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
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.