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 master.gnome.org, and then announcing the release.

Contents

  1. Initial setup
    1. Requirements
    2. Recommended
    3. Setting up testing machine
    4. Types of releases
  2. Simple release walkthrough
    1. Run tarball conversion
    2. Build the moduleset
    3. Update releng
    4. Updating gnome-build-meta
    5. Publishing on master.gnome.org
    6. Extra steps for x.beta release
    7. Extra steps for x.0 release

Initial setup

Requirements

  • GNOME git account
  • Shell account to master.gnome.org with 'ftpadmin' group (ability to change /ftp/pub/GNOME)
  • 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

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

Host *.gnome.org
        User yourusername

Setting up testing machine

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

$ git clone git@gitlab.gnome.org:GNOME/gnome-build-meta.git
$ git clone git@gitlab.gnome.org:GNOME/releng.git

Types of releases

  • In this walkthrough, "development releases" is also used to mean the alpha 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 beta releases. These releases are pushed to a stable branch in gnome-build-meta, e.g. gnome-41, and tagged.

This terminology might be confusing, so be careful.

Simple release walkthrough

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

Run tarball conversion

  • Create a new branch in gnome-build-meta from the appropriate branch (master branch for alpha or beta releases, stable branch otherwise). 
    $ git fetch
$ git switch -c abderrahim/41.beta origin/master
  • cd into releng/tools/smoketesting

  • Run convert-to-tarballs.py 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-$VERSION.config): 

    $ ./convert-to-tarballs.py -v 41.beta ~/path/to/gnome-build-meta/
  • If convert-to-tarballs.py fails with an error message, you may need to update tarball-conversion.config if there are new download locations, module renames, or new modules.
  • For the x.0 stable release, you must create a tarball-conversion-$VERSION.config file (copy it from tarball-conversion.config). You may do so earlier (for beta or rc releases) if you need to set limits.
  • For stable branch releases, 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 rerun tarball conversion several times until you are happy with the converted result.
  • Some elements will need to be tracked.
    • If you're doing an alpha or beta release, most elements need to be tracked and it's easier to just track everything 
      bst track --deps all iso/image.bst vm/repo-devel.bst
    • If doing an rc or stable release, it may be faster to track just the elements with empty ref: field. You can try looking for those in the diff, or run 
      bst show core.bst | grep "no reference"

Build the moduleset

  • Commit your changes, push your branch and create a merge request. The MR should target master for the beta release for now, and the appropriate stable branch for later releases (don't create a merge request for alpha releases). The CI will build it for you for the supported architectures.
  • If you have a fast computer and/or want to debug build failures, you can try to build locally.

    • 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, or pass --strict to Buildstream. You must use strict build plan to avoid broken releases.
    • Launch the build using 
      $ bst --strict build core.bst sdk.bst

  • 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 ./convert-to-tarballs.py. 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 41.beta'

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 doing a beta release, make sure that all MRs relevant to both the master and the new stable branch have been merged. Then create the stable branch (gnome-41 in this walkthrough) by going to Repository > Branches in the gitlab sidebar and clicking New branch. Don't forget to change the target branch of your MR to the newly created branch.

  • Try to get another member of the release team to review your merge request and merge it.

  • Once merged, tag the commit and push your tag. You can also create the tag from the Gitlab UI by going to Repository > Tags in the sidebar and clicking New tag.

  • If working on an alpha release, do not create a tag.

Publishing on master.gnome.org

  • Create a git archive with the contents of your gnome-build-meta git HEAD: 
    $ git fetch
$ git archive --prefix gnome-41.beta/ -o gnome-41.beta.tar 41.beta
$ xz gnome-41.beta.tar
  • Copy files to master.gnome.org, then ssh in: 
    $ scp gnome-build-meta/gnome-41.beta.tar.xz master.gnome.org:
$ scp releng/tools/smoketesting/versions master.gnome.org:
$ ssh master.gnome.org
  • Install the release. 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/41.beta
$ cp ~/gnome-41.beta.tar.xz ~/versions /ftp/pub/GNOME/teams/releng/41.beta
$ ftpadmin release-suites 41.beta ~/versions
$ ftpadmin simple-news 41.alpha 41.beta
  • (Optional) If you're doing a beta, rc or .0 release, then it's better to mirror the VM image. Once the CI pipeline for the tag finishes, run (replacing the version obviously) 
    $ curl -O -L https://os.gnome.org/download/41.beta/gnome_os_installer_41.beta.iso
$ mkdir /ftp/pub/GNOME/gnomeos/41.beta
$ mv gnome_os_installer_41.beta.iso /ftp/pub/GNOME/gnomeos/41.beta

    Make sure to mention the link in the announcement: https://download.gnome.org/gnomeos/41.0/gnome_os_installer_41.0.iso (replacing the version)

  • Send announcement to https://discourse.gnome.org/c/desktop/6, with the "announcement" tag

Extra steps for x.beta release

  • Check on the various other release-related efforts: release notes, video, website, press package, etc. Sync with the engagement team on these

Extra steps for x.0 release

  • Remember to mention the release name (most recent GUADEC/GNOME.Asia host city)
  • Update the schedule scripts in the releng module to reference the new schedule files (to receive automatic mails)
  • Make sure www.gnome.org is updated to note the new release (gnome-web-list is the contact, right?)
  • Remove the authentication on library.gnome.org/misc/release-notes/X.Y (ask a gnome-sysadmin to edit the apache config and reload the server; e.g. #sysadmin on irc.gnome.org)
  • Get someone to send out the press release if there's one (tell the board when the release will happen)
  • Announce on Discourse (coordinate with #engagement for social media)

  • Update www.gnome.org/start/ so that it refers to the correct stable and unstable releases
    Currently sysadmin-only, ask sysadmin to edit /etc/apache2/sites-enabled/www.gnome.org on socket and do a service apache2 reload. The content of www.gnome.org/start currently lives behind www.gnome.org/wp-admin.php. Best to talk to the website people for updating this and other website content.

  • Update links in ReleasePlanning

  • Make sure the new schedule is available as ics (git location: gnomeweb-wml/www.gnome.org/start/schedule-unstable.ics) and on the wiki
    The ical.py creates this, see releng module, tools/schedule directory. new www.gnome.org 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 www.gnome.org/getting-gnome up-to-date wrt to stable distro releases and GNOME versions

ReleasePlanning/MakingARelease (last edited 2023-03-20 17:56:04 by MichaelCatanzaro)