Maintain Ubuntu Desktop software¶

These are some common, day-to-day operations to build, maintain and package GNOME software for Ubuntu Desktop using the Git Build Package (gbp) workflow.

We use the gnome-control-center repository as an example.

Note

Some applications on Ubuntu Desktop are developed outside of Salsa and GNOME. They have their own, separate workflows, which aren’t described in this guide. The Desktop Team can help you find the right instructions on Matrix: #desktop-dev:ubuntu.com.

Prerequisites¶

Before you start, follow the instructions in Set up Git for Ubuntu Desktop work.

Workflow overview for external contributors¶

If you’re a community contributor and not a member of the Ubuntu Desktop Team, you have to send your contributions through a merge request:

Fork the Git repository on Salsa.
Follow this guide and make the changes in your fork.
Open a Salsa merge request from your fork to the original repository.

In some projects, no Ubuntu branch has been created in a long time. You might have to ask the Desktop Team to create the new branch for you. Contact them on Matrix at #desktop-dev:ubuntu.com.

Local changes¶

With the suggested Git configuration, any non-committed changes (file modifications, additions, or removal) halt the build because they won’t be included. This is a safety reminder.

What you can do when you have such changes:

Ignore them. The resulting package and build won’t include those uncommitted changes. The ../build-area/<your-package> directory will match the last commit.

To do this, add the --git-ignore-new Git option.
Force using the current directory with your local modifications instead of the build-area directory, and include any local modifications to the package despite the ignore-new option.

For this, add the --git-ignore-new --git-export=INDEX options to gbp.

Refresh branches¶

Use the following command to refresh the current ubuntu/<release> branch and the corresponding upstream/<release> branch. This applies only to the branches referenced in the debian/gbp.conf file on your current checkout. Also refresh the pristine-tar branch.

For example, on the ubuntu/latest branch:

gnome-control-center$

gbp pull

gbp:info: Fetching from default remote for each branch
gbp:info: Branch 'upstream/latest' is already up to date.
gbp:info: Branch 'ubuntu/latest' is already up to date.
gbp:info: Updating 'pristine-tar': 2bed57f20816..e59ab7422a13

The pristine-tar branch has been updated as referenced in debian/gbp.conf.

If you have a separate ubuntu/noble branch with its own upstream/46.x branch:

gnome-control-center$

git checkout ubuntu/noble

gnome-control-center$

gbp pull

gbp:info: Fetching from default remote for each branch
gbp:info: Branch 'ubuntu/noble' is already up to date.
gbp:info: Branch 'upstream/46.x' is already up to date.
gbp:info: Branch 'pristine-tar' is already up to date.

The gbp pull command, contrary to git pull, is a way to avoid checking out each branch and pulling them one by one.

Push your Git changes to Salsa¶

To contribute changes back to Salsa, push your changes using gbp:

gnome-control-center$

gbp push

Merge a new upstream version to latest¶

When upstream releases a new version of a given project, you can merge the version on the Debian and Ubuntu latest branches.

This applies when upstream releases the latest version of the latest series: for example when version 50.0 or 50.2 comes out, and version 51 hasn’t been released yet. Always merge new major releases on the latest branch. If you’re merging a new maintenance release of an earlier series, follow Merge a new upstream version to maintenance instead.

Switch to the branch where you want to import the new version, such as ubuntu/latest:

gnome-control-center$
git fetch upstreamvcs

gnome-control-center$
git checkout ubuntu/latest
Create a patch/queue/ubuntu/latest branch that is useful in case you need to refresh patches later.
- If you already have the patch/queue branch, rebase it:
  
  gnome-control-center$
  gbp pq rebase
- Otherwise, create the patch/queue branch:
  
  gnome-control-center$
  gbp pq import
Check whether this upstream version already exists in Debian:
gnome-control-center$
git tag -l | grep upstream
```
[…]
upstream/46.0
upstream/46.0.1
upstream/46.1
upstream/46.3
[…]
```
If Debian already has the upstream version, you don’t have to import the tarball. Merge with the latest upstream code:

gnome-control-center$
git merge upstream/46.3 -m "Update upstream source from tag 'upstream/46.3'"

The new upstream version is now merged. Push the changes:

gnome-control-center$
gbp push origin

Merge a new upstream version to Debian¶

If Debian doesn’t have the new upstream version, add the release to Debian and Ubuntu.

Scan for new releases:

gnome-control-center$

uscan --verbose --no-download

[…]
Newest version of gnome-control-center on remote site is 49.1, local version is 46.7
 => Newer package available from:
        => https://download.gnome.org/sources/gnome-control-center/49/gnome-control-center-49.1.tar.xz

Is uscan showing the upstream release that you want to import?

If so, you can let gbp download and import the latest release automatically:

gnome-control-center$

gbp import-orig --uscan

Otherwise, download the tarball with the new upstream release manually. Then, import the tarball:

gnome-control-center$

gbp import-orig ../gnome-control-center-46.2.tar.xz

What is the upstream version? [46.2] 
gbp:info: Importing '../gnome-control-center-46.2.tar.xz' to branch 'upstream/latest'...
gbp:info: Source package is gnome-control-center
gbp:info: Upstream version is 46.2
gbp:info: Replacing upstream source on 'ubuntu/noble'
gbp:info: Successfully imported version 46.2 of ../gnome-control-center-46.2.tar.xz

Push all related branches:

gnome-control-center$
gbp push origin

The gbp tool handles all branches automatically. In the example of this upstream release, gbp pushes the ubuntu/latest, pristine-tarball + upstream/46.x or upstream/latest branches.

Sync the affected upstream branch to Salsa, or push it to your fork and propose it as a merge request if you aren’t an Ubuntu developer.

Check for dependency changes¶

New upstream releases often change the dependencies of the application. Check for changes.

For example, if the application uses the Meson build system and you’ve updated from version 49.alpha to 49.0:

gnome-control-center$

git diff 49.alpha..49.0 -- meson.build

Reflect the updated package dependencies in the debian/control file. For details, see debian/ directory.

Troubleshooting¶

You might get the following errors when importing the tarball.

Revision not found¶

gnome-control-center$

gbp import-orig ../gnome-control-center-46.2.tar.xz

What is the upstream version? [46.2] 
gbp:info: Importing '../gnome-control-center-46.2.tar.xz' to branch 'upstream/latest'...
gbp:info: Source package is gnome-control-center
gbp:info: Upstream version is 46.2
gbp:error: Import of ../gnome-control-center-46.2.tar.xz failed: revision '…' not found

The reason might be one of the following:

You didn’t get the latest commits and tags in your repository metadata. Fetch them:

gnome-control-center$
git fetch upstreamvcs
Upstream has changed the tagging pattern. Update the upstream-tag value in the debian/gbp.conf file to match it. For details, see No upstream tarballs in the gbp documentation.
Upstream is using an inconsistent release pattern. Therefore, the debian/gbp.conf file can’t use a regular expression for the version.

Find the exact tag:

gnome-control-center$
git describe --tags --abbrev=0 upstreamvcs/main

Specify the version manually:

gnome-control-center$
gbp import-orig <tarball> --upstream-vcs-tag=<exact_version_tag>

Upstream tag already exists¶

gnome-control-center$

gbp import-orig ../gnome-control-center-46.2.tar.xz

What is the upstream version? [46.2] 
gbp:error: Upstream tag 'upstream/46.2' already exists

This error means that Debian already has this tarball. Merge from Debian as described in Merge a new upstream version to latest.

Merge a new upstream version to maintenance¶

When upstream releases a new version of a given project, you can merge the version on an Ubuntu maintenance branch. A maintenance branch is a branch for stable releases and backports.

This applies when upstream releases a new version of an earlier series, older than the current major version: for example when version 49.3 comes out, and the latest branch already contains version 50.0. If you’re merging a new release of the latest series, follow Merge a new upstream version to latest instead.

If main has a newer version than the maintenance branch and you are the first one to deal with that case for that maintenance release, additional steps are required.

Check if the debian/gbp.conf file sets the upstream-branch=upstream/latest option.
Check if the ubuntu/latest branch has a newer upstream version than the one that you are importing, which was never imported.

For example:
- ubuntu/latest is on 46.2.
- ubuntu/noble is on 46.1, and we want to update to 46.2.
- The pristine-tar log lists that 46.1 and 46.2 have been imported.
- Consequently, the upstream/latest branch has upstream commits and tags for 46.1, 46.2 and corresponding gbp tags upstream/46.1 and upstream/46.2.
If the option is present and ubuntu/latest is newer, proceed with the next steps.

Otherwise, follow these sections:
1. Create a new maintenance branch.
2. Switch to the maintenance branch.
3. Merge a new upstream version, while on the maintenance branch.
Switch to the maintenance branch:

gnome-control-center$
git checkout ubuntu/noble
Create a new upstream/<series> branch:

Checkout the latest version of upstream/latest in your maintenance branch. In this example, it’s upstream/46.1:

gnome-control-center$
git branch upstream/46.x upstream/46.1
Update the debian/gbp.conf file to reference the correct upstream gbp branch:
debian/gbp.conf¶
```
upstream-branch=upstream/46.x
```
Commit the changes:

gnome-control-center$
git commit -a
Check whether Debian already has the new version in Salsa:
gnome-control-center$
git tag -l | grep upstream
```
[…]
upstream/46.0
upstream/46.0.1
upstream/46.1
upstream/46.3
[…]
```
If the version already exists in Debian, use Debian’s upstream branch tags:

gnome-control-center$
git merge upstream/46.3 -m "Update upstream source from tag 'upstream/46.3'"

Push the upstream and pristine-tar branches to Salsa:

gnome-control-center$
gbp push origin

Add the maintenance version in Debian¶

If the version doesn’t exist in Debian yet, add it to Debian and Ubuntu using an upstream tarball.

Fetch from upstream:

gnome-control-center$
git fetch upstreamvcs

Scan for new releases:

gnome-control-center$

uscan --verbose --no-download

[…]
Newest version of gnome-control-center on remote site is 49.1, local version is 46.7
 => Newer package available from:
        => https://download.gnome.org/sources/gnome-control-center/49/gnome-control-center-49.1.tar.xz

Is uscan showing the upstream release that you want to import?

If so, you can let gbp download and import the latest release automatically:

gnome-control-center$

gbp import-orig --uscan

Otherwise, download the tarball with the new upstream release manually. Then, import the tarball:

gnome-control-center$

gbp import-orig ../gnome-control-center-46.2.tar.xz

What is the upstream version? [46.2] 
gbp:info: Importing '../gnome-control-center-46.2.tar.xz' to branch 'upstream/latest'...
gbp:info: Source package is gnome-control-center
gbp:info: Upstream version is 46.2
gbp:info: Replacing upstream source on 'ubuntu/noble'
gbp:info: Successfully imported version 46.2 of ../gnome-control-center-46.2.tar.xz

Push your changes, including the new branch that you want to track:

gnome-control-center$
gbp push origin
Push the upstream and pristine-tar branches to Salsa.

You can push directly to the GNOME branch if you have the permissions. Otherwise, push to your personal fork and prepare a merge request.

gnome-control-center$
gbp push origin

Refresh patches¶

Before merging with an upstream release, refresh the patches.

Rebase the pq branch:

gnome-control-center$
gbp pq rebase
Use the Git rebase tools to refresh the patches.

Troubleshooting¶

The rebase might not work in certain cases, such as if you’re merging with an upstream/x.z.y tag or if you didn’t create the patch/queue branch first. In those cases, follow these steps:

Switch to the corresponding branch.
If the patch-queue branch exists, remove it:
gnome-control-center$
gbp pq drop
```
gbp:info: Dropped branch 'patch-queue/ubuntu/noble'.
```
Try to find the earliest point where the patches still apply. Increase the value until you find the previous release commit:
gnome-control-center$
gbp pq import --force --time-machine=30
```
gbp:info: 30 tries left
gbp:info: Trying to apply patches at '10ee426e74c4643a8b723e874c71b74cfc55746d'
gbp:info: 38 patches listed in 'debian/patches/series' imported on 'patch-queue/ubuntu/noble'
```
Replace 30 with a number that determines how far in history you want to look for the patches. The exact number depends on the size of your repository. Larger numbers provide better results, but the search gets increasingly slow, so start small.
Re-apply the debian/patches/series file on top of the new upstream code, stopping for manual action if needed:

gnome-control-center$
gbp pq rebase
If a patch doesn’t apply cleanly, fix it:
1. Resolve the conflict, and record the fix using git add or git rm.
2. Proceed with git rebase --continue.
If the --time-machine step or gbp pq rebase fail, import the patches into the pq branch manually from a file:

gnome-control-center$
git am -3 < debian/patches/<patch-file>
Regenerate the debian/patches data:

gnome-control-center$
gbp pq export --no-patch-numbers
Switch back to your ubuntu/latest or ubuntu/<series> branch.
Commit the changes.

Add or modify patches¶

You can turn patch files into commits on a branch. This enables you to add new patches or modify existing ones.

Note

We recommend that you manage patches using the gbp tool on Ubuntu Desktop software, as described here. For the legacy patching workflow using the quilt tool, see How to work with Debian patches.

Switch to the correct ubuntu/ branch or your local experimental-feature branch. For example:

gnome-control-center$
git checkout ubuntu/latest
Turn all patches from the debian/patches/ directory into Git commits:
gnome-control-center$
gbp pq rebase
```
gbp:info: Switching to 'patch-queue/ubuntu/latest'
Current branch patch-queue/ubuntu/latest is up to date.
```
This command creates the patch-queue/ubuntu/latest branch and switches to it. This branch is based on the ubuntu/latest branch, and all patches referenced in the debian/patches/series file are applied as separate commits on top of it.

Check the commits:

gnome-control-center$

git missing ubuntu/latest..

* 11a3a8cc6 - (HEAD -> patch-queue/ubuntu/latest) [PATCH] night-ligth-dialog: Avoid dereferencing invalid p
ointer (5 minutes ago)
* da06252e1 - [PATCH 4/4] thunderbolt: move to the 'Devices' page (5 minutes ago)
* 2c9f5bcbb - [PATCH 3/4] thunderbolt: new panel for device management (5 minutes ago)
* 660e9e633 - [PATCH 2/4] shell: Icon name helper returns symbolic name (5 minutes ago)
* a78ae89dd - [PATCH 1/4] shell: Don't set per-panel icon (5 minutes ago)
[…]

This is similar to using git log to browse the commits, which also works.

Add or modify patches:
- Modify the software. Fix a bug or add a new feature. This will be the content of your new patch.
  
  When you commit your changes, every new commit turns into a separate patch applied at the end of the debian/patches/series file. The commit description is then converted to the patch description.
  
  If you want to build a package with the current content without having to switch your branch, use the following command:
  
  gnome-control-center$
  gbp buildpackage -b --git-ignore-new --git-export=INDEX
- Reorder your patches. If you don’t want this patch to be the last one, use an interactive Git rebase:
  
  gnome-control-center$
  git rebase -i ubuntu/latest
  
  There, reorder the patches as commits, amend or stash them. Removing a commit also removes the patch from the debian/patches/series file.
- Remove or edit patches. Any change to the commits results in the same change to the patch files.
  
  For example, you can use Git commit with the --amend option to modify the commit history. For details, see Git Tools - Rewriting History.

Reapply all your changes to the original branch:

gnome-control-center$

gbp pq export --no-patch-numbers

gbp:info: On 'patch-queue/ubuntu/latest', switching to 'ubuntu/latest'
gbp:info: Generating patches from git (ubuntu/latest..patch-queue/ubuntu/latest)

Update the changelog. For details, see Update the changelog.
The new patches end up as unstaged changes on your branch. Commit your changes.

Cherry-pick upstream commits¶

You can cherry-pick an upstream commit into a patch file.

Switch to the branch where you want to add the cherry-picked commit. For example, on the ubuntu/latest branch:

gnome-control-center$
git checkout ubuntu/latest
Update the branch:

gnome-control-center$
gbp pull origin
Turn patches into commits:

gnome-control-center$
gbp pq rebase || gbp pq import
Display the upstream Git log in the patch format. Note the hash of the commit that you want to cherry-pick:

gnome-control-center$
git log -p upstream/latest
Cherry-pick your selected commit using its hash and edit the commit message:

gnome-control-center$
git cherry-pick -x <hash>
Are there any conflicts?

If there are no conflicts, edit the commit message to comply with DEP 3 - patch file headers. This ends up as the patch header.

If there are conflicts:
1. Fix them. For example:
  
  gnome-control-center$
  git mergetool
2. Continue with cherry-picking:
  
  gnome-control-center$
  git cherry-pick --continue
3. Edit the commit message to comply with DEP 3 - patch file headers.
Reapply all your changes to the original branch:

gnome-control-center$
gbp pq export --no-patch-numbers
Update the changelog. For details, see Update the changelog.
Commit the changes:

gnome-control-center$
git add debian/patches/* debian/changelog

gnome-control-center$
git commit

For details about gbp pq, see Add or modify patches.

Update the changelog¶

You can edit the debian/changelog file manually, but it’s recommended to use the following command instead:

gnome-control-center$

gbp dch

By default, this command adds the first line of every commit to the changelog. You can adjust this behavior by including a string at the end of your commit message:

Gbp-Dch: Full: Add this full commit message, not just the first line.
Gbp-Dch: Ignore: Skip this commit in the changelog.

Alternatively, you can include all the commit descriptions:

gnome-control-center$

gbp dch --full

Then, filter them out by hand at the commit phase.

Import an Ubuntu upload tracked outside of Git¶

You can import a Debian Source Control (DSC) source package as a tarball, even if it doesn’t exist in Git.

Download the source tarball.

You can download the tarball that belongs to an Ubuntu release, like Noble:
gnome-control-center$
pull-lp-debs --download-only gnome-control-center noble
```
Found gnome-control-center 1:46.7-0ubuntu0.24.04.3 in noble
Downloading gnome-control-center_46.7-0ubuntu0.24.04.3.dsc from archive.ubuntu.com (0.004 MiB)
```
Or you can download the tarball based on a package version:

gnome-control-center$
pull-lp-debs --download-only gnome-control-center 46.7-0ubuntu0
Switch to the branch where you want to place this Ubuntu upload.
Import the tarball:

gnome-control-center$
gbp import-dsc ../gnome-control-center_46.1-0ubuntu5.dsc
If there had been changes in your tree, importing the latest tarball reverted all previous changes in Git.

Important

Do not use Git rebase to restore your changes (which would rewrite history) because everyone who pulls from the repository would have conflicts upon refreshing.

Reintroduce your changes by cherry-picking the commits. Because your commits are already in tree but reverted, you must cherry-pick using the following commands:

gnome-control-center$
git show <hash> | git apply

gnome-control-center$
git commit -C <hash>
Push the changes:

gnome-control-center$
gbp push origin

This pushes all needed branches, such as ubuntu/latest, and pristine-tarball + upstream/latest if this upload is a new upstream release.

Create a new maintenance branch¶

Find the latest version in common between the development release and that maintenance branch.

Here, we use the ubuntu/1%46.1-0ubuntu4 version tag as an example.
Create a branch from the starting point.

gnome-control-center$
git branch ubuntu/noble ubuntu/1%46.1-0ubuntu4

gnome-control-center$
git checkout ubuntu/noble
In the debian/gbp.conf file, change debian-branch to ubuntu/noble:
debian/gbp.conf¶
```
debian-branch = ubuntu/noble
```
In the debian/control file, change Vcs-Browser to the branch’s page on https://salsa.debian.org/<package>/tree/<branch>. For example:
debian/control¶
```
Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center/tree/ubuntu/noble
```
Note

Certain outdated projects might still use the debian/control.in file. To generate debian/control from it, use the dh_gnome tool during the clean target in the debian/rules file.

At the end of the Vcs-Git value, use the -b ubuntu/noble option. For example:

debian/control¶

Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git -b ubuntu/noble

Make sure that the XS-Debian-Vcs-Git and XS-Debian-Vcs-Browser fields are set to the Vcs-* values but without their Ubuntu versions:

XS-Debian-Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git
XS-Debian-Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center

Commit the changes:

gnome-control-center$
git commit -a

Push your changes to Salsa:

gnome-control-center$

gbp push origin

Total 0 (delta 0), reused 0 (delta 0)
To git+ssh://git@salsa.debian.org:gnome-team/gnome-control-center
 * [new branch]          ubuntu/noble -> ubuntu/noble
Branch 'ubuntu/noble' set up to track remote branch 'ubuntu/noble' from 'origin'.

Build a package locally¶

To build a local package, we use the sbuild framework and specify the target Ubuntu release. We don’t recommend building the package directly on your system without using sbuild because the test and build phase might be affected by the state of your machine.

Build a binary package for your Ubuntu release and CPU architecture. For example, Ubuntu Noble on the AMD64 architecture:

gnome-control-center$
gbp buildpackage -b --git-builder=sbuild noble-amd64
Build a source package:

gnome-control-center$
gbp buildpackage -b --git-builder=sbuild noble-amd64 -S

With the proposed configuration, the artifacts all end up in the ../build-area directory, including the tarball, which is reconstructed from the pristine-tar + upstream/latest branch. The build directory is then cleaned up.

Useful tips in some potential cases:

Don’t purge the build-area directory after building:

gnome-control-center$
gbp buildpackage --git-no-purge
Build current branch with local uncommitted modifications:

gnome-control-center$
gbp buildpackage --git-ignore-new --git-export=INDEX
When merging with Debian, releasing an SRU or uploading a version on top of one that is still in the proposed pocket, include both the Ubuntu and Debian part of the changelog in the .changes file, which is generated by dpkg-genchanges. Including all changelog entries ensures that bugs are automatically closed.

Add the -vX option to include all Debian and Ubuntu versions greater than X, which is the current version in main, security or updates repositories:

gnome-control-center$
gbp buildpackage -S -vX

For example, see the gnome-control-center_49.0-1ubuntu2_source.changes generated file.

Release a new version¶

Note

If this is a sponsored upload, the sponsor performs these steps.

Generate the changelog for native packages. For details, see Update the changelog.
You might need to manually edit the debian/changelog file to improve its syntax and clarity.
Finalize the changelog and specify the Ubuntu release:

gnome-control-center$
dch -r "" --distribution noble

gnome-control-center$
git commit -m "Upload to Noble" debian/changelog
Tag the package:

gnome-control-center$
gbp buildpackage --git-tag-only --git-ignore-new
Build the source package:

gnome-control-center$
gbp buildpackage -S

If this version hasn’t arrived in the main repository yet, include both the Ubuntu and Debian part of the changelog in the .changes file, which is generated by dpkg-genchanges. Add the -vX option to include all Debian and Ubuntu versions greater than X, where X is the current version in main, security or updates repositories:

gnome-control-center$
gbp buildpackage -S -vX

For example, consider the following scenario:
- The main pocket contains version 3.1.0-1ubuntu1.
- The proposed pocket contains 3.1.0-1ubuntu2.
- You’re uploading version 3.1.0-2ubuntu1.
In this case, use the -v3.1.0-1ubuntu1 option so that the changes in 3.1.0-1ubuntu2 are also listed in the change files.
Check the ../build-area/<your-package>.changes file to make sure that it’s correct. This file instructs dput which files to upload and provides a high-level view of the changes, such as the latest changelog entries.

For example, changes to the GNU Hello program as packaged for Ubuntu would be described in the hello_2.10-0ubuntu1.changes file.
Upload the files to the Ubuntu package upload queue:

gnome-control-center$
dput ../build-area/<your-package>.changes
Push the changes to Salsa:

gnome-control-center$
gbp push origin

This pushes all tracked branches to Salsa if you made any changes. The branches include:
- ubuntu/latest
- ubuntu/old-series
- pristine-tar
- upstream/lastest

Maintain Ubuntu Desktop software¶

Prerequisites¶

Workflow overview for external contributors¶

Local changes¶

Refresh branches¶

Push your Git changes to Salsa¶

Merge a new upstream version to latest¶

Merge a new upstream version to Debian¶

Check for dependency changes¶

Troubleshooting¶

Revision not found¶

Upstream tag already exists¶

Merge a new upstream version to maintenance¶

Add the maintenance version in Debian¶

Refresh patches¶

Troubleshooting¶

See also¶

Add or modify patches¶

Cherry-pick upstream commits¶

Update the changelog¶

Import an Ubuntu upload tracked outside of Git¶

Create a new maintenance branch¶

Build a package locally¶

Release a new version¶