Making a Release#

Releases are how maintainers tell the world—or, more accurately, downstream developers—that it’s time to update their dependencies. These guidelines explain how maintainers can generate these releases.

Setting up GitLab CI/CD pipeline#

To make a release, a GitLab CI/CD pipeline needs to be set up in the project repository. This pipeline needs to be able to generate a release tarball and upload it to the GNOME server.

To do this, place a .gitlab-ci.yml file containing the CI/CD pipeline configuration in the root of the project (learn more). The configuration is project-specific and should be tailored to the project’s needs, but it is highly advised to utilize a CI/CD component prepared by the GNOME Release Team.

Example of a minimal .gitlab-ci.yml file#

include:
  - component: gitlab.gnome.org/GNOME/citemplates/release-service@master
    inputs:
      job-stage: release
      dist-job-name: "build-release-tarball"              # <1.>
      tarball-artifact-path: "${TARBALL_ARTIFACT_PATH}"   # <2.>

stages:
  - build
  - release

variables:
  MESON_BUILD_DIR: _build
  TARBALL_ARTIFACT_PATH: "${MESON_BUILD_DIR}/meson-dist/${CI_PROJECT_NAME}-${CI_COMMIT_TAG}.tar.xz"

build-release-tarball:                                    # <3.>
  stage: build
  script:
    - meson setup "${MESON_BUILD_DIR}"
    - meson dist -C "${MESON_BUILD_DIR}" --include-subprojects
  artifacts:
    name: "${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
    when: always
    paths:
      - "${TARBALL_ARTIFACT_PATH}"

  1. Makes it so the release job is triggered only after the build job finishes and is successful.

  2. The path to the release tarball artifact.

  3. The job that generates the release tarball. Will differ per project. You can use a pre-existing job that creates a release tarball.

Steps taken by the pipeline:

  1. The pipeline defines global variables.

  2. The pipeline includes the release service component and sets the necessary inputs.

  3. The pipeline builds the project, generates the release tarball and uploads it as an artifact.

  4. The included component inner workings are triggered, which will upload the tarball to the GNOME server.

If your application is already using the Flatpak CI template, it already creates a Release Tarball for you and you will only need to define ${TARBALL_ARTIFACT_PATH} instead.

Example of the `.gitlab-ci.yml for gnome-font-viewer

include:
  - project: 'gnome/citemplates'
    file: 'flatpak/flatpak_ci_initiative.yml'
  - component: gitlab.gnome.org/GNOME/citemplates/release-service@master
    inputs:
      dist-job-name: "flatpak"
      tarball-artifact-path: "${TARBALL_ARTIFACT_PATH}"

variables: #<1.>
  FLATPAK_MODULE: 'gnome-font-viewer'
  TARBALL_ARTIFACT_PATH: ".flatpak-builder/build/${FLATPAK_MODULE}/_flatpak_build/meson-dist/${CI_PROJECT_NAME}-${CI_COMMIT_TAG}.tar.xz"

flatpak:
  extends: '.flatpak'
  variables:
    MANIFEST_PATH: 'build-aux/flatpak/org.gnome.font-viewerDevel.json'
    RUNTIME_REPO: 'https://sdk.gnome.org/gnome-nightly.flatpakrepo'
    APP_ID: 'org.gnome.font-viewerDevel'
    BUNDLE: 'org.gnome.font-viewerDevel.flatpak'

nightly:
  extends: '.publish_nightly'
  dependencies: ['flatpak']
  needs: ['flatpak']

  1. Make sure that your TARBALL_ARTIFACT_PATH and FLATPAK_MODULE variables are on the same scope, so Gitlab will expand the nested variables correctly.

The release process is possible only with a pipeline that has been triggered by a protected Git tag. The tag is used as a trigger to generate and name the tarball. The tarball is then uploaded to the GNOME server. This limitation lies in the security constraints of the underlying service that is used to upload the tarball.

Requirements for the GitLab project settings and pipeline invocation#

  • The project must be hosted on GNOME GitLab.

  • The project must be part of the GNOME or Incubator group.

  • The pipeline must be triggered by a tag.

  • The tag must be protected.

    • All tags published on our git instance are immutable and impossible to delete. However, they are not marked as such in GitLab itself as that’s an Enterprise Edition feature. Thus, each project needs to add the following rule in their Project Settings by following these steps:

      1. Open the Settings dropdown menu on the sidebar,

      2. Click Repository,

      3. Open Protected Tags,

      4. Click Add rule,

      5. In the tag search bar, type “*”,

      6. Click on the Create Wildcard entry that will appear,

      7. Specify who should be allowed to create tags (e.g., Maintainers),

      8. Click Protect.

  • The release tarball name has to be in the format $CI_PROJECT_NAME-$CI_COMMIT_TAG.tar.xz, where $CI_PROJECT_NAME is the project name and $CI_COMMIT_TAG is the tag name (learn more).

Final last steps before the release#

  • Update the version number if necessary (in meson.build or equivalent).

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

    • Optionally, 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 for doing this:

      • Remember that the AppStream metadata is presented by GUI tools to the user.

        • Try to make the bullet points short and snappy but also understandable for a general user (not always easy).

        • If several entries relate to the same change, only use a single bullet point.

  • Ensure that the project is building and passing tests.

  • 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 not list development snapshots in the AppStream metadata, and instead make a full release description for the first stable release.

  • Update the NEWS file:

    • The NEWS file is generally used by packagers and integrators, so you can be more verbose than in the AppStream metadata.

    • Optionally, you can use this script for generating a NEWS file from your Git history.

    • You might wish to mention 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 -S

Tagging as the signal for the release#

As the release automation is triggered by a Git tag, the tag must be created in the GitLab repository. The tag should be named according to the version number of the release.

Ways to create a tag sorted by preference:

  1. Best way is to use git evtag sign <tag> with git-evtag to provide strong signing guarantees.

  2. If you can’t do that, use the basic way: git tag -s <tag>

  3. Or, worse: git tag -a <tag>

Once the tag is created, push it to the GitLab repository with git push origin <tag>. The pipeline will be triggered by the tag and the release process will start.

Monitoring the release#

When the tag is created in the GitLab repository, the release process will automatically start. The jobs will generate the tarball and upload it to the GNOME server. Monitor the release from the GitLab interface to ensure that everything went smoothly.

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 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 reference documentation on this, and the Programming Guidelines on developer.gnome.org.