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 https://gitlab.gnome.org/GNOME/.

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

A list of outdated packages (as detected by repology.org) maintained by the GNOME team can be found on packages.gentoo.org.

Workflow

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 with tools from app-portage/mgorny-dev-scripts:

user $pkgbump package-1.2.3.ebuild package-1.2.4.ebuild
user $pkgcommit -s -m "Version bump to 1.2.4" .

And diff the build system files between the two versions.

user $pkgdiff --build-system package-1.2.3.ebuild package-1.2.4.ebuild

Autotools

user $pkgdiff --build-system package-1.2.3.ebuild package-1.2.4.ebuild
--- gnome-terminal-3.38.3/work/gnome-terminal-3.38.3/configure.ac	2021-01-09 11:10:36.000000000 -0800
+++ gnome-terminal-3.40.1/work/gnome-terminal-3.40.1/configure.ac	2021-04-30 09:43:36.000000000 -0700
@@ -1,6 +1,6 @@
 m4_define([terminal_version_major],[3])
-m4_define([terminal_version_minor],[38])
-m4_define([terminal_version_micro],[3])
+m4_define([terminal_version_minor],[40])
+m4_define([terminal_version_micro],[1])
 m4_define([terminal_version_extra],[])
 m4_define([terminal_version],[terminal_version_major().terminal_version_minor().terminal_version_micro()terminal_version_extra])
 
@@ -64,7 +64,7 @@
        GTK_MIN_REQUIRED=3.18
        GTK_MAX_ALLOWED=3.24
        VTE_API_VERSION=2.91
-       VTE_REQUIRED=0.62.1
+       VTE_REQUIRED=0.64.0
        ;;
 esac

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

Meson

user $pkgdiff --build-system package-1.2.3.ebuild package-1.2.4.ebuild
--- gnome-calendar-3.38.2/work/gnome-calendar-3.38.2/meson.build	2020-12-16 16:16:43.692903500 -0800
+++ gnome-calendar-40.0/work/gnome-calendar-40.0/meson.build	2021-03-22 11:55:09.575393400 -0700
@@ -1,9 +1,9 @@
 project(
   'gnome-calendar',
                'c',
-           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.

CMake

user $pkgdiff --build-system package-1.2.3.ebuild package-1.2.4.ebuild
--- 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)

 project(evolution
-       VERSION 3.38.4
+       VERSION 3.40.0
        LANGUAGES C)
 set(PROJECT_BUGREPORT "https://gitlab.gnome.org/GNOME/evolution/issues/")
 set(PROJECT_URL "http://wiki.gnome.org/Apps/Evolution/")
@@ -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
 set(INTERFACE_VERSION 3.0)
@@ -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.

Common things to look for in diffs

  • Changes in dependencies (added, removed, required version)
  • Changes in configuration options
  • Build system transitions. Many packages are moving from Autotools to Meson. We should aim to use the Meson build system if possible.
  • The removal of meson.add_install_script often allows us to remove the need for Python in the ebuild. In the pkgdiff -b output, look for changes such as:
FILE git diff output
-meson.add_install_script('build-aux/meson/postinstall.py')
+gnome.post_install(
+  glib_compile_schemas: true,
+  gtk_update_icon_cache: true,
+  update_desktop_database: true,
+)

Removing the need for Python is usually mechanical.

FILE git diff output
diff --git a/media-gfx/shotwell/shotwell-0.32.1.ebuild b/media-gfx/shotwell/shotwell-0.32.1.ebuild
index 4fdd2e16ec91..5be584be1de2 100644
--- a/media-gfx/shotwell/shotwell-0.32.1.ebuild
+++ b/media-gfx/shotwell/shotwell-0.32.1.ebuild
@@ -3,8 +3,7 @@
 
 EAPI=8
 
-PYTHON_COMPAT=( python3_{9..11} )
-inherit gnome.org gnome2-utils meson python-any-r1 vala xdg
+inherit gnome.org gnome2-utils meson vala xdg
 
 DESCRIPTION="Open source photo manager for GNOME"
 HOMEPAGE="https://wiki.gnome.org/Apps/Shotwell"
@@ -44,7 +43,6 @@ RDEPEND="${DEPEND}
 	media-plugins/gst-plugins-meta:1.0
 "
 BDEPEND="
-	${PYTHON_DEPS}
 	$(vala_depend)
 	dev-libs/appstream-glib
 	dev-libs/glib

To confirm that Python is not needed, emerge dev-lang/python-exec with USE=-native-symlinks and confirm that the package still successfully builds, tests, and installs.

root #mkdir -p /etc/portage/profile/package.use.force
root #echo "dev-lang/python-exec -native-symlinks" > /etc/portage/profile/package.use.force/native-symlinks
root #USE=-native-symlinks emerge -1 dev-lang/python-exec


Update the new ebuild created by pkgbump with the required changes found in the pkgdiff -b output.

Build dependencies

First we ensure required dependencies are installed.

user $sudo emerge package -va1o --with-test-deps

TODO: What if required dependencies are not stable?

Confirm it builds

Now we should do a basic sanity check that the new version builds.

user $sudo ebuild package-1.2.4.ebuild clean install

Assuming the package builds and installs successfully, we should now check that any unit tests it has pass.

user $sudo ebuild package-1.2.4.ebuild clean test

Commit

Commit the ebuild and Manifest change.

user $pkgcommit -s -m "Version bump to 1.2.4" .

Dependencies

app-text/docbook-xml-dtd

Packages that use dev-util/gtk-doc for building documentation will often require app-text/docbook-xml-dtd as well. The absence of the right docbook-xml-dtd slot is often non-fatal which leads to the dependency often being forgotten or incorrect.

Without the appropriate docbook-xml-dtd slot installed, dev-util/glade builds successfully, but with this warning: 

[372/372] /usr/bin/xsltproc --output man/glade.1 --stringparam man.output.quietly 1 --stringparam funcsynopsis.style ansi --stringparam man.th.extra1.suppress 1 --stringparam man.authors.section.enabled 0 --stringparam man.copyright.section.enabled 0 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl ../glade-3.40.0/man/glade.xml
../glade-3.40.0/man/glade.xml:3: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
                                                                 ^

It's best to grep the sources of the package to determine exactly what slot is required:

root #grep -r 'docbook/xml' /var/tmp/portage/dev-util/glade-3.40.0/work/glade-3.40.0
doc/gladeui-docs.xml:                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
help/C/index.docbook:"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
man/glade.xml:        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
man/glade-previewer.xml:        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

TODO: Why do the absences of app-text/docbook-xml-dtd:4.1.2 and app-text/docbook-xml-dtd:4.5 not trigger a warning?

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.

glib

  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

gtk

gnome-shell

gnome-session

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

vala

TODO

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

gnome-terminal

Patches
  • 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}

evolution

webkit-gtk

gedit

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.

gnome-flashback

libxml2

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.

gphoto2

sysprof

Retrieved from "https://wiki.gentoo.org/index.php?title=Project:GNOME/GNOME_Bumping_Guide&oldid=1253582"