docs/releasing.md

   1 Making a release
   2 ===
   3
   4 When to make a release
   5 ---
   6
   7 Releases are made on a schedule determined in the [roadmap](./roadmap.md). Each
   8 release corresponds to a [GitLab milestone](https://gitlab.gnome.org/GNOME/glib/-/milestones).
   9
  10 There is usually some scope to change a release date by plus or minus a week, to
  11 allow specific merge requests to land if they are deemed as more important to
  12 release sooner rather than waiting until the next scheduled release. However,
  13 there is always another release, and releasing on time is more important than
  14 releasing with everything landed. Releasing on time allows distributors to
  15 schedule their packaging work efficiently.
  16
  17 Maintainers should take it in turns to make releases so that the load is spread
  18 out evenly and every maintainer is practiced in the process.
  19
  20 How to make a release
  21 ---
  22
  23 Broadly, GLib follows the same process as [every other GNOME
  24 module](https://wiki.gnome.org/MaintainersCorner/Releasing).
  25
  26 These instructions use the following variables:
  27  - `new_version`: the version number of the release you are making, for example `2.73.1`
  28  - `previous_version`: the version number of the most-recently released version in the same release series, for example `2.73.0`
  29  - `branch`: the branch which the release is based on, for example `glib-2-72` or `main`
  30
  31 Make sure your repository is up to date and doesn’t contain local changes:
  32 ```sh
  33 git pull
  34 git status
  35 ```
  36
  37 Check the version in `meson.build` is correct for this release.
  38
  39 Download
  40 [gitlab-changelog](https://gitlab.gnome.org/pwithnall/gitlab-changelog) and use
  41 it to write a `NEWS` entry:
  42 ```sh
  43 gitlab-changelog.py GNOME/glib ${previous_version}..
  44 ```
  45
  46 Copy this into `NEWS`, and manually write some highlights of the fixed bugs as
  47 bullet points at the top. Most changes won’t need to be highlighted — only the
  48 ones which add APIs, change dependencies or packaging requirements, or fix
  49 impactful bugs which might affect distros’ decisions of how to prioritise the
  50 GLib release or how urgent to mark it as.
  51
  52 You can get review of your `NEWS` changes from other co-maintainers if you wish.
  53
  54 Commit the release:
  55 ```sh
  56 git add -p
  57 git commit -sm "${new_version}"
  58 ```
  59
  60 Build the release tarball:
  61 ```sh
  62 ninja -C build/ dist
  63 ```
  64
  65 Tag, sign and push the release (see below for information about `git evtag`):
  66 ```sh
  67 git evtag sign ${new_version}
  68 git push --atomic origin ${branch} ${new_version}
  69 ```
  70 To use a specific key add an option `-u ${keyid|email}` after the `sign` argument.
  71
  72 Use `${new_version}` as the tag message.
  73
  74 Upload the release tarball (you will need a
  75 [GNOME LDAP account](https://wiki.gnome.org/Infrastructure/NewAccounts) for this):
  76 ```sh
  77 scp build/meson-dist/glib-${new_version}.tar.xz master.gnome.org:
  78 ssh master.gnome.org ftpadmin install glib-${new_version}.tar.xz
  79 ```
  80
  81 Add the release notes to GitLab and close the milestone:
  82  - Go to https://gitlab.gnome.org/GNOME/glib/-/tags/${new_version}/release/edit
  83    and upload the release notes for the new release from the `NEWS` file
  84  - Go to https://gitlab.gnome.org/GNOME/glib/-/releases/${new_version}/edit
  85    and link the milestone to it, then list the new release tarball and
  86    `sha256sum` file in the ‘Release Assets’ section as the ‘Other’ types.
  87    Get the file links from https://download.gnome.org/sources/glib/ and
  88    name them ‘Release tarball’ and ‘Release tarball sha256sum’
  89  - Go to https://gitlab.gnome.org/GNOME/glib/-/milestones/
  90    choose the milestone and close it, as all issues and merge requests tagged
  91    for this release should now be complete
  92
  93 `git-evtag`
  94 ---
  95
  96 Releases must be done with `git evtag` rather than `git tag`, as it provides
  97 stronger security guarantees. See
  98 [its documentation](https://github.com/cgwalters/git-evtag) for more details.
  99 In particular, it calculates its checksum over all blobs reachable from the tag,
 100 including submodules; and uses a stronger checksum than SHA-1.
 101
 102 You will need a GPG key for this, ideally which has been signed by others so
 103 that it can be verified as being yours. However, even if your GPG key is
 104 unsigned, using `git evtag` is still beneficial over using `git tag`.