Making a Release

Releases are how maintainers tell the world—or, more accurately, downstream developers—that it's time to update their dependencies.

Preliminaries

In the Git repository:

  • Clean state: see git status

  • Up-to-date: git pull

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

Tips:

  • Nothing prevents you from having two copies of the git repo, to use one for releases only.

For the git commit

  • Update the version number if necessary (in meson.build or equivalent).
    • For a library, update also the interface version (for the soname, see below).
  • 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).

    • 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. Some tips:
      • Remember that the AppStream metadata is presented by GUI tools to the user

      • Try to make the bullet points short and snappy but understandable for a general user. That’s 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 skip listing development snapshots in the AppStream metadata, and instead make a full release description for the first stable release

  • Update the NEWS file

    • You can generate the NEWS file from your commit log or from your AppStream metadata

    • The NEWS file is generally used by packagers and integrators, so you can be more verbose

    • Do not forget to include 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

Rolling the tarball

With Meson:

  • Do a 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.

For other build systems:

git tag and git push

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

Basic way:

  • git tag -a 43.0

But it's better to do:

  • git tag -s 43.0

  • Or even better: git evtag sign 43.0 with git-evtag, to provide stronger signing guarantees.

The message of the tag should be in the format:

GNOME Foo 43.0

* The contents of the NEWS file for this release.
* Dependency updates
* Some change
* A bug fix
* Small maintenance tasks
* Translation updates

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

  • Push the commit as usual.
  • In the rare case where another commit was pushed in the meantime (usually for a translation), you can do a normal git pull (so without --rebase) and there will be a merge commit that you can push (the translation will need to wait the next release).

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 Infrastructure/NewAccounts. 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 send an email to the ftp-release mailing list so that the release-team will know about it.

More advanced stuff

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](https://mesonbuild.com/Reference-manual_functions.html#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 a reference documentation on this, and the Programming Guidelines on developer.gnome.org.

See also

MaintainersCorner/Releasing (last edited 2022-09-25 13:05:53 by EmmanueleBassi)