Project:GNOME/GNOME Bumping Guide

From Gentoo Wiki
Jump to:navigation Jump to:search

This article aims to provide the reader with sufficient information to add new version of GNOME packages to the ::gentoo repository safely.

GNOME has two major releases per year (in March and September). The upstream release schedule is available here.

Nearly all packages maintained by the GNOME team are hosted on

The announcement and distributor, discourse tags often contain valuable information for distribution maintainers.

A list of outdated packages (as detected by maintained by the GNOME team can be found on

Build System diff'ing

It's important to handle upstream packaging changes since the last version when adding a new version to the tree. For example, the new version may have different dependencies, require different versions of dependencies, or have gained or lost configuration options.

To detect these changes, we diff the build system of the last version with that of the new version. For a package called category/package, first copy the ebuild and make the version bump commit:

user $cp package-1.2.3.ebuild package-1.2.4.ebuild
user $git add package-1.2.4.ebuild
user $ekeyword '~all' package-1.2.4.ebuild
user $repoman manifest
user $git commit -as -m "$(cat-pkg): Version bump to 1.2.4"

Run ebuild ... unpack on both old and new ebuilds:

user $ebuild package-1.2.3.ebuild unpack
user $ebuild package-1.2.4.ebuild unpack

And as root enter the category directory in PORTAGE_TMPDIR.

root #cd /var/tmp/portage/category/

And diff the build system files between the two versions.


user $cd ~/projects/gentoo/x11-terms/gnome-terminal
user $ebuild gnome-terminal-3.38.3.ebuild unpack
user $ebuild gnome-terminal-3.40.1.ebuild unpack
root #/var/tmp/portage/x11-terms
root #diff -u */work/*/
--- gnome-terminal-3.38.3/work/gnome-terminal-3.38.3/	2021-01-09 11:10:36.000000000 -0800
+++ gnome-terminal-3.40.1/work/gnome-terminal-3.40.1/	2021-04-30 09:43:36.000000000 -0700
@@ -1,6 +1,6 @@
@@ -64,7 +64,7 @@
-       VTE_REQUIRED=0.62.1
+       VTE_REQUIRED=0.64.0

From the diff we can see that a newer version of x11-libs/vte is required.


user $cd ~/projects/gentoo/gnome-extra/gnome-calendar
user $ebuild gnome-calendar-3.38.2.ebuild unpack
user $ebuild gnome-calendar-40.0.ebuild unpack
root #cd /var/tmp/portage/gnome-extra
root #find */work/* -type f ! \( -name '' -o -name 'meson_options.txt' \) -printf "%f\n" | diff -X - -Nru */work/*
diff -X - -Nru gnome-calendar-3.38.2/work/gnome-calendar-3.38.2/ gnome-calendar-40.0/work/gnome-calendar-40.0/
--- gnome-calendar-3.38.2/work/gnome-calendar-3.38.2/	2020-12-16 16:16:43.692903500 -0800
+++ gnome-calendar-40.0/work/gnome-calendar-40.0/	2021-03-22 11:55:09.575393400 -0700
@@ -1,9 +1,9 @@
-           version: '3.38.2',
+           version: '40.0',
            license: 'GPL3+',
-     meson_version: '>= 0.50.0'
+     meson_version: '>= 0.53.0'
@@ -163,8 +165,8 @@
 libecal_dep = dependency('libecal-2.0', version: '>= 3.33.2')
 libsoup_dep = dependency('libsoup-2.4')
 libdazzle_dep = dependency('libdazzle-1.0', version: '>= 3.33.1')
-libhandy_dep = dependency('libhandy-0.0', version: '>= 0.0.9')
-glib_dep = dependency('glib-2.0', version: '>= 2.58.0')
+libhandy_dep = dependency('libhandy-1', version: '>= 1.0.0')
+glib_dep = dependency('glib-2.0', version: '>= 2.67.5')
 gtk_dep = dependency('gtk+-3.0', version: '>= 3.22.20')
 gio_dep = dependency('gio-2.0', version: '>= 2.58.0')
 goa_dep = dependency('goa-1.0', version: '>= 3.2.0')

From the diff we can see that newer versions of dev-libs/glib and gui-libs/libhandy are required.


user $cd ~/projects/gentoo/mail-client/evolution
user $ebuild evolution-3.38.4.ebuild unpack
user $ebuild evolution-3.40.0.ebuild unpack
root #cd /var/tmp/portage/mail-client
root #find */work/* -type f ! \( -name '*.cmake' -o -name 'CMakeLists.txt' \) -printf "%f\n" | diff -X - -Nru */work/*
diff -X - -Nru evolution-3.38.4/work/evolution-3.38.4/CMakeLists.txt evolution-3.40.0/work/evolution-3.40.0/CMakeLists.txt
--- evolution-3.38.4/work/evolution-3.38.4/CMakeLists.txt       2021-02-12 01:43:03.000000000 -0800
+++ evolution-3.40.0/work/evolution-3.40.0/CMakeLists.txt       2021-03-18 23:41:05.000000000 -0700
@@ -4,7 +4,7 @@
 cmake_policy(VERSION 3.1)

-       VERSION 3.38.4
+       VERSION 3.40.0
        LANGUAGES C)
 set(PROJECT_URL "")
@@ -12,7 +12,7 @@
 # Base Version: This is for API/version tracking for things like
 # D-Bus server files. This should always be the major/minor of
 # the stable version or stable version to be.
-set(BASE_VERSION 3.38)
+set(BASE_VERSION 3.40)

 # Used for pkg-config files
@@ -48,8 +48,8 @@

 # Keep these two definitions in agreement.
-set(glib_minimum_version 2.46)
-set(glib_encoded_version GLIB_VERSION_2_46)
+set(glib_minimum_version 2.56)
+set(glib_encoded_version GLIB_VERSION_2_56)

 # Keep these two definitions in agreement.
 set(gdk_minimum_version 3.22)

From the diff we can see that a new version of dev-libs/glib is required.

Package Groups

GNOME contains many packages organized into groups that should be bumped together.

Core groups

The core groups are the most critical (i.e., they are the reverse dependencies of the largest number of other GNOME packages) and should be bumped first.


  1. dev-libs/gobject-introspection-common
  2. dev-libs/gobject-introspection
  3. dev-util/gdbus-codegen
  4. dev-util/glib-utils
  5. dev-libs/glib
  6. net-libs/glib-networking
  7. dev-python/pygobject - often not crucial to be done together with the rest





  • gnome-base/gnome-session - occasionally review the provided defaults.list in FILESDIR for needed updates (desktop filenames of default applications for various MIME types).
  • gnome-base/gnome-settings-daemon - sometimes needs to be in sync with gnome-session if the RequiredComponents of gnome-session changes; depending on the exact changes, it usually needs version range dependencies as well to ensure a new RequirementComponent will be present from gnome-settings-daemon.
  • gnome-base/gnome-control-center - may occasionally need to be major version bumped together with gnome-settings-daemon for proper desktop integration.



  • dconf, dconf-editor
  • gtk-doc, gtk-doc-am
  • yelp, yelp-xsl, yelp-tools
  • grilo, grilo-plugins
  • eog, eog-plugins
  • cheese, gnome-video-effects

Independent groups

These groups can typically be updated independently of core GNOME.




  • Both packages have a downstream patch series applied with USE=-vanilla
  • The patches are from the Fedora and are available in their repos:
    • vte291
      • vte291-cntnr-precmd-preexec-scroll.patch
    • gnome-terminal
      • gnome-terminal-cntr-ntfy-autottl-ts.patch
      • The last patch in the gnome-terminal series ("screen, window: Preserve current toolbox, if any") should be removed. Simply delete it from the .patch file.
  • Compress both patches and upload them to your distfiles directory, since they are too large to go into ${FILESDIR}




Note that amtk and tepl use a x.y.z versioning scheme where unstable releases are denoted with an odd value of y. We typically don't care to package those unstable releases.




These two (mainly libxslt as the consumer) rely on internal API changes which may be carried out between releases. Be careful when making snapshots, and bump new versions at the same time.