Making a release essentially consists of converting GNOME's BuildStream projects to use tarballs instead of git, building it to make sure all the tarballs actually build together, publishing the result on, and then announcing the release.

Initial setup


  • Shell account to with 'ftpadmin' group (ability to change /ftp/pub/GNOME)
  • GNOME git account
  • Familiarity with release process for individual GNOME modules
  • Familiarity with Newcomers/BuildSystemComponent guide to building GNOME using BuildStream; in particular, the latest version of bst-external is often required

  • You must add yourself as a maintainer in gnome-build-meta.doap to receive commit access to the stable branches

  • Running ssh-agent

Put the following in ~/.ssh/config (even if your username matches the one on!):

Host *
        User yourusername

Setting up testing machine

You'll need to clone the gnome-build-meta and releng repos:

$ git clone
$ git clone

Types of releases

  • In this walkthrough, "development releases" are early unstable branch releases only, prior to x.y.90. E.g. 3.27.1, 3.27.2, and 3.27.3 are all "development releases." These releases are not tagged. Only temporary test branches are pushed to gnome-build-meta.
  • In this walkthrough, "stable branch releases" begin with the x.y.90 beta releases. E.g. 3.27.90 and 3.28.0 are both "stable branch releases" for the purposes of this walkthrough, even though 3.27.90 is really an unstable release leading up to 3.28. These releases are pushed to a stable branch in gnome-build-meta, e.g. gnome-3-28, and tagged.

This terminology might be confusing, so be careful.

Simple release walkthrough

As an example, let's assume you're making the 3.27.90 release.

Release gnome-desktop

  • gnome-desktop includes the gnome-version.xml file (generated from the version in that is used to display version information in the gnome-control-center details panel.
  • The first step of every GNOME release is to release a new gnome-desktop tarball with a matching version number.
  • (This walkthrough assumes you are already familiar with the process for releasing individual modules.)
  • As with any library, don't forget to bump the library version in, not just the project version.

Run tarball conversion

  • Ensure you don't have any local changes to gnome-build-meta and that you are on the appropriate branch (master branch for development releases, stable branch otherwise).
  • If you are doing a development release, you must also delete or move your project.refs file (or you may use a separate git worktree instead). You do not need to delete project.refs if you are doing a stable branch release because stable branches use inline refs:

$ rm project.refs
  • Update your gnome-build-meta checkout:

$ git pull
  • cd into releng/tools/smoketesting
  • Run to create the versions file and update the BuildStream projects. This script examines every element in the gnome-build-meta project that uses git, and attempts to replace it with a tarball instead, respecting the tarball locations and version limits specified in tarball-conversion.config (or tarball-conversion-stable.config):

$ ./ -v 3.27.90 ~/path/to/gnome-build-meta/
  • If fails with an error message, you may need to update tarball-conversion.config (or tarball-conversion-stable.config) if there are new download locations, module renames, or new modules.
  • For stable releases beginning with x.y.0 (not including the x.y.90-x.y.92 stable branch releases), you may need to update tarball-conversion-$VERSION.config. (Copy it from tarball-conversion.config if this is the x.y.0 release.) Review the output of 'git diff' and check for problematic tarball version updates. It is important to add limit values for actively developed modules; otherwise, development releases will creep into your stable release! The limit attribute works by specifying the too-new version. E.g. if 3.27 is the current development stream, you want to put limit="3.27" to restrict your release to picking up only the latest 3.26.z tarball. You may need to discard your changes and rerun tarball conversion several times until you are happy with the converted result.

Build the moduleset

  • BuildStream workspaces will pollute your build, and you will likely forget about open workspaces. Always start by closing your open workspaces:

$ bst workspace close --all
  • If strict build plan has been disabled in ~/.config/buildstream.conf, reenable it. You must use strict build plan to avoid broken releases:

# This configuration reduces the amount of necessary rebuilds
#  gnome:
#    strict: False
  • Now comes the hard part: testing the build. You may prefer to do this locally to get a successful local build before trying to use the CI (recommended, because the CI is slow), or you may skip this step and go straight to building on CI. If you choose to build locally:

$ bst build --track-all core.bst sdk.bst
  • Push a temporary branch (e.g. "mcatanzaro/3.27.90") to use gnome-build-meta's CI. If this is a stable branch release (x.y.90 or later) and you did not build everything locally already, then you'll need to manually track everything first, because the CI will not do so for you. Skip the track step if you already have a successful local build:

$ git checkout -b mcatanzaro/3.27.90
$ bst track --deps=all core.bst sdk.bst
$ git commit -a -m 'Testing 3.27.90'
$ git push -u origin mcatanzaro/3.27.90
  • You'll probably encounter several build failures, which you'll need to fix, either by manually updating the tarball versions used in the BuildStream projects, or hounding maintainers to make new releases and then re-running ./ Dealing with build failures is the most frustrating part of the release process. Don't hesitate to manually downgrade tarball versions as needed to get a successful build, but if you do so, be sure to nag maintainers to get the problem fixed before the next release.

  • If your CI fails, you'll need to force-push a new commit to your temporary branch after fixing the build failure:

$ git commit --amend
$ git push -f
  • Continue to the next step once your CI is green.

Update releng

  • Update the version-controlled versions file under releng/tools (one directory above smoketesting), then push your changes to the releng repository. For unstable releases:

$ cp tools/smoketesting/versions tools/versions
$ git commit -a -m 'GNOME 3.27.90'

For stable releases, copy your versions file to tools/versions-stable instead. For oldstable releases, copy it to tools/versions-oldstable.

Updating gnome-build-meta

  • If working on a stable branch release (x.y.90 and later), tag your changes and push them to the corresponding stable branch (e.g. gnome-3-28). (If you're handling the x.y.90 release, you'll need to create that branch yourself. See the extra steps for x.y.90 release, below.) Then delete your temporary branch:

$ git checkout gnome-3-28
$ git merge --ff-only mcatanzaro/3.27.90
$ git tag -a 3.27.90 -m 'GNOME 3.27.90'
$ git push --follow-tags
$ git push --delete origin mcatanzaro/3.27.90
  • If working on a development release, do not push your changes anywhere except your temporary branch. Do not create a tag.

Publishing on

  • Create a git archive with the contents of your gnome-build-meta git HEAD:

$ git archive --prefix gnome-3.27.90/ -o gnome-3.27.90.tar @
$ xz gnome-3.27.90.tar
  • Copy files to, then ssh in:

$ scp gnome-build-meta/gnome-3.27.91.tar.xz
$ scp releng/tools/smoketesting/versions
$ ssh
  • Install the release. Note that 'cp -a' is to preserve the correct permissions. The files being copied should be world-readable. Also note that when running 'simple-news', the first argument is the previous release, and the second argument is the current release.

$ mkdir /ftp/pub/GNOME/teams/releng/3.27.90
$ cp -a ~/gnome-3.27.90.tar.xz ~/versions /ftp/pub/GNOME/teams/releng/3.27.90
$ ftpadmin release-suites 3.27.90 ~/versions
$ ftpadmin simple-news 3.27.3 3.27.90
$ signal-ftp-sync
  • Send an announce mail to desktop-devel-list@ and devel-announce-list@. If doing a stable release, x.y.0 or later (not including the x.y.90-x.y.92 stable branch releases), also send it to gnome-announce-list@.

Extra steps for x.y.90 release

  • TODO: Abderrahim should document these steps!
  • TODO: Some of the extra steps for x.y.0 release should move up here.

Extra steps for x.y.0 release

  • Create a new stable flatpak runtime: Change the branch variable in project.conf and the FLATPAK_BRANCH variable in .gitlab-ci.yml.

  • Create new stable branch in gnome-build-meta and push your work there. The flatpak runtimes will be automatically published to Flathub.
  • Remember to mention the release name (most recent GUADEC/GNOME.Asia host city)
  • Update the -stable files (tarball-conversion.config and versions)
  • Update the schedule scripts in the releng module to reference the new schedule files (to receive automatic mails)
  • Make sure is updated to note the new release (gnome-web-list is the contact, right?)
  • Remove the authentication on (ask a gnome-sysadmin to edit the apache config and reload the server; e.g. #sysadmin on
  • Make sure a LiveCD and VM machines are out
  • Get someone to send out the press release if there's one (tell the board when the release will happen)
  • Announce on gnome-announce-list and on devel-announce-list (coordinate with #engagement for social media)
  • Update so that it refers to the correct stable and unstable releases
    Currently sysadmin-only, ask sysadmin to edit /etc/apache2/sites-enabled/ on socket and do a service apache2 reload. The content of currently lives behind Best to talk to the website people for updating this and other website content.

  • Update links in ReleasePlanning

  • Ask bugmaster to add a new version/target milestone for the next version of GNOME in bugzilla
    GNOME target and GNOME version

  • Create jhbuild modulesets for the next development cycle
  • Make sure the new schedule is available as ics (git location: gnomeweb-wml/ and on the wiki
    The creates this, see releng module, tools/schedule directory. new still redirects to old GNOME for the ics file

Some other things we should put in a check list:

  • Have screenshots of a default GNOME (so users know what it will look like)
  • Have screencasts to demo some new features
  • Keep up-to-date wrt to stable distro releases and GNOME versions

ReleasePlanning/MakingARelease (last edited 2020-12-23 16:34:51 by MichaelCatanzaro)