Project:GNOME/GNOME Bumping Guide

This article Article description::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.

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, first copy the ebuild and make the version bump commit with tools from :

And diff the build system files between the two versions.

Autotools
From the diff we can see that a newer version of is required.

Meson
From the diff we can see that newer versions of and  are required.

CMake
From the diff we can see that a new version of 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.

Update the new ebuild created by with the required changes found in the  output.

Build dependencies
First we ensure required dependencies are installed.

TODO: What if required dependencies are not stable?

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

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

Commit
Commit the ebuild and Manifest change.

app-text/docbook-xml-dtd
Packages that use for building documentation will often require  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, 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:

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)  - often not crucial to be done together with the rest
 * 1)  - often not crucial to be done together with the rest
 * 1)  - often not crucial to be done together with the rest
 * 1)  - often not crucial to be done together with the rest
 * 1)  - often not crucial to be done together with the rest
 * 1)  - often not crucial to be done together with the rest
 * 1)  - often not crucial to be done together with the rest

atk

 * - usually not needed to be done together with the above, but each orca release cycle needs at least the same release cycle of the above
 * - usually not needed to be done together with the above, but each orca release cycle needs at least the same release cycle of the above
 * - usually not needed to be done together with the above, but each orca release cycle needs at least the same release cycle of the above
 * - usually not needed to be done together with the above, but each orca release cycle needs at least the same release cycle of the above
 * - usually not needed to be done together with the above, but each orca release cycle needs at least the same release cycle of the above

gtk

 * - split package with its own repository and tags. Doesn't always result in a new tag if nothing changed, but should be checked and updated on each gtk+ bump
 * - split package with its own repository and tags. Doesn't always result in a new tag if nothing changed, but should be checked and updated on each gtk+ bump

gnome-session

 * - occasionally review the provided defaults.list in FILESDIR for needed updates (desktop filenames of default applications for various MIME types).
 * - 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.
 * - may occasionally need to be major version bumped together with gnome-settings-daemon for proper desktop integration.

vala

 * Update  in
 * Update  in
 * Update  in

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.

Patches

 * Both packages have a downstream patch series applied with
 * 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

webkit-gtk

 * - older is usually fine with newer webkit-gtk series as webkit-gtk is ABI stable and a new GNOME series doesn't typically need to block webkit-gtk getting ahead of epiphany for its security handling needs
 * - older is usually fine with newer webkit-gtk series as webkit-gtk is ABI stable and a new GNOME series doesn't typically need to block webkit-gtk getting ahead of epiphany for its security handling needs
 * - older is usually fine with newer webkit-gtk series as webkit-gtk is ABI stable and a new GNOME series doesn't typically need to block webkit-gtk getting ahead of epiphany for its security handling needs
 * - older is usually fine with newer webkit-gtk series as webkit-gtk is ABI stable and a new GNOME series doesn't typically need to block webkit-gtk getting ahead of epiphany for its security handling needs

gedit


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

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.