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

  • 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

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

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). Do not delete project.refs if you are doing a stable release.

$ rm project.refs
  • Update your gnome-build-meta checkout with 'git pull'.
  • cd into releng/tools/smoketesting
  • For development releases, update tarball-conversion.config if there are new download locations, module renames, or new modules.
  • For stable releases, update tarball-conversion-stable.config. Copy it from tarball-conversion.config if this is the first stable release of the cycle. 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.x tarball.
  • Run script to create the versions file and update the BuildStream projects:

$ ./ -v 3.27.90 -d ~/path/to/gnome-build-meta/

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.

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
  • Test the build:

$ bst build --track-all core.bst
  • You may also commit your changes to a topic branch and push it so it gets built by the CI. However, make sure to download the project.refs file from the pipeline artifacts.
  • 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 ./ 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.

  • Once you've fixed the build failures, update the version-controlled versions file under releng/tools (one directory above smoketesting), then push your changes to the releng repository. If working on an unstable release, do not push your changes to gnome-build-meta.

Packaging gnome-build-meta

  • For unstable releases:

$ cd gnome-build-meta
$ git add -f project.refs
$ git commit -am 'do not push'
$ git archive --prefix gnome-3.27.90/ -o gnome-3.27.90.tar @
$ xz gnome-3.27.90.tar
$ git reset @^
  • For stable releases, create a real commit instead and archive that instead.
  • It's worth saying twice: Do not push your changes to gnome-build-meta unless you are working on a stable release and pushing to a stable branch.

  • If working on a stable release, then you actually do want to push your changes, but only to a stable branch (e.g. gnome-3-28). If you're handling the .0 release, you'll need to create that branch yourself. Be sure to push a git tag as well (stable releases only).

Publishing on

Once you've built everything, it's time to publish it.

  • 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 -p /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
  • Optionally, you can use the output of 'ftpadmin simple-diff' to nag maintainers not providing updates:

$ ftpadmin simple-diff 3.27.3 3.27.90
$ ftpadmin simple-diff --same 3.27.3 3.27.90
  • Send an announce mail to desktop-devel, devel-announce, and (if doing a stable release) gnome-announce.

Extra steps for .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 2019-11-24 21:22:08 by MichaelCatanzaro)