Making a Release#

Releases are how maintainers tell the world—or, more accurately, downstream developers—that it’s time to update their dependencies. These guidelines explain how maintainers can generate these releases.

Preliminaries#

In the Git repository:

  • Clean state, on the master or main branch: git status.

  • Up-to-date: git pull.

  • Without untracked files: git clean can be handy but must be used with caution (for example git clean -xdf).

  • If signing commits/tags (which you should be), ensure that your up-to-date GPG key is associated with your Gitlab account - this can be checked in your GitLab GPG key settings.

Tip: there’s nothing preventing you from having two copies of the Git repo, with one only being used for releases.

For the Git commit#

  • Update the version number if necessary (in meson.build or equivalent).

  • Update the README if necessary.

  • If the module is an application, add a <release> entry in the AppStream metadata file (refer to the AppStream documentation).

    • Optionally, 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. Some tips for doing this: * Remember that the AppStream metadata is presented by GUI tools to the user. * Try to make the bullet points short and snappy but also understandable for a general user (not always easy). * If several entries relate to the same change, only use a single bullet point.

  • Note: the AppStream specification does not deal with alphabetical components inside a version, so whenever releasing a development snapshot (alpha, beta, or rc) you will need to use tilde as a separator for the version attribute in the release element, e.g. 43.alpha becomes 43~alpha; 44.beta becomes 44~beta; and 45.rc becomes 45~rc.

    • You also have the option to not list development snapshots in the AppStream metadata, and instead make a full release description for the first stable release.

  • Update the NEWS file:

    • The NEWS file is generally used by packagers and integrators, so you can be more verbose than in the AppStream metadata.

    • Optionally, you can use this script for generating a NEWS file from your Git history.

    • You might wish to mention updated dependencies, since it makes life easier for packagers.

    • You might use a format similar to the following:

Version 43.0
------------
* Dependency update
* Some change
* A bug fix
* Small maintenance tasks
* Translation updates

  • Do a git commit -S

Rolling the tarball#

With Meson:

  • From the build directory, run meson dist

  • Fix any issues that crop up.

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

If successful, it should show you something like this:

Distribution package /opt/gnome/build/glib/meson-dist/glib-2.57.3.tar.xz tested.

git tag and git push#

Create a git tag to easily locate the version later on in the Git history.

  • Best way: git evtag sign 43.0 with git-evtag, to provide strong signing guarantees.

  • If you can’t do that, use the basic way: git tag -s 43.0

  • Or, worse: git tag -a 43.0

This will launch an editor for you to enter the message to use for the tag. Write the name and version of the project:

GNOME Foo 43.0

Then git push both the commit and the tag: git push --atomic origin HEAD 43.0

Upload the tarball#

$ scp gnome-foo-43.0.tar.xz USER@master.gnome.org:~
$ ssh USER@master.gnome.org
$ ftpadmin install gnome-foo-43.0.tar.xz

(Adapt to your taste).

Notes:

  • All module maintainers who wish to be able to upload tarballs should request a shell account at master.gnome.org for this purpose (see accounts). Ask someone else to do it for you if you are waiting for an account.

  • There are no extra steps required for new modules.

  • The ftpadmin install will move the tarball to the appropriate directory, do some additional administrative stuff, and email members of the Release Team so they know about it.

Updating library interface versions#

Note: this is relevant if you are still using Autotools, or have migrated from Autotools to Meson within the same major version. If you are writing a new library that has never used Autotools, or if you just bumped the API version and only ever used Meson, you can ignore all of it and use the soversion and version parameters of the library method.

For the -version-info linker flag, which is used to create the soname of the library:

  • There is usually a variable with a name such as LT_VERSION towards the top of the configure.ac, meson.build or equivalent file.

  • There is usually also a comment that summarizes how the version should be updated.

See the Libtool manual for reference documentation on this, and the Programming Guidelines on developer.gnome.org.