Overview

The Debian GNOME Team uses git-buildpackage to make working with the packaging repositories easier. git-buildpackage is not required if you only want to build a package or for more contributions. Please do use git-buildpackage to import new versions.

The package layout is DEP-14 style with full upstream source and upstream history without upstream tags and with pristine-tar.

Browse the repos

https://salsa.debian.org/gnome-team

Contents

  1. Overview
    1. Browse the repos
  2. Recommended setup
    1. Install tools
    2. Set up git urls
    3. Do initial clone
  3. Use git
  4. Use git-buildpackage
  5. Repo layout
  6. Package new upstream version
  7. UNRELEASED
  8. debian/changelog
  9. Make a release
  10. Other information
    1. Initial packaging
    2. Warning for stable updates
    3. History
    4. pristine-tar branch not found
    5. Archived packages
    6. Git hooks
    7. Misc. cases
    8. Packages named differently from their git repos
    9. Our default gbp.conf
  11. upstream-vcs-tag
    1. To do

Install tools

sudo apt install debhelper git-buildpackage gnome-pkg-tools

Set up git urls

Git has a feature to rewrite urls. We can use this to create handy shortcuts that require less characters to type and will make migration easier if your username ever changes (for instance, if you become a Debian Developer and no longer need an Alioth -guest account) or if the repo ever moves (like happened with the 2018 Debian Gitlab migration).

You can set up and change git url handling in your ~/.config/git/config (or with the git config command). 

[url "git@salsa.debian.org:gnome-team/"]
        insteadof = pkg-gnome:

Do initial clone

For this example, we're going to grab the gnome-text-editor source.

It's recommended to use a separate directory for your code so that it doesn't clutter your home directory. pkg-gnome is a good name for that. (No example shown for this step).

Type the following commands in to your terminal to check out the Debian packaging and add a remote named upstreamvcs to track the upstream GNOME repo. 

gbp clone pkg-gnome:gnome-text-editor --add-upstream-vcs 
cd gnome-text-editor

The --add-upstream-vcs option requires git-buildpackage 0.9.29 or higher which is available in Debian Testing or Ubuntu 22.10. If you are using Ubuntu 22.04 LTS or Debian 11, use these commands instead: 

gbp clone pkg-gnome:gnome-text-editor
cd gnome-text-editor
git remote add upstreamvcs https://gitlab.gnome.org/GNOME/gnome-text-editor.git

The upstreamvcs repo is pulled from the Repository field of debian/upstream/metadata in each of our packaging repos. Several of our repos don't yet have debian/upstream/metadata so that will need to be added for the --add-upstream-vcs feature to work.

Use git

A full git tutorial is beyond the scope of this wiki page. See the Pro Git book for one popular guide.

Use git-buildpackage

Please read the manual to learn how to use git-buildpackage.

Repo layout

The Debian GNOME team does not use the current default git-buildpackage layout for its repositories. Instead, a DEP-14 style layout is used. debian/gbp.conf is provided to enable git-buildpackage to work without manual adjustment.

The primary packaging branch is named debian/master. The parallel branch for upstream source without the debian/ directory is named upstream/latest

pristine-tar is used. Also, full upstream source with full upstream commit history is integrated (automated with the help of git-buildpackage).

The latest version should always use the debian/master and upstream/latest branches. If the latest version is not suitable for upload to unstable, feel free to create a branches like debian/buster (where buster is the targeted Debian release even if it is initially upload to unstable). For the corresponding upstream branch, it should generally be named upstream/3.26.x if it is tracking upstream's 3.26 series.

Package new upstream version

Make sure you start from the debian/master branch with no uncommitted changes. 

gbp pull

Check the git log for any changes that have been made since the last upload. If there are changes, run `gbp dch; git add debian/changelog; git commit -m "Update changelog" . Continue with the actual import 

git fetch --all
gbp import-orig --uscan

This will update the pristine-tar, upstream/latest and debian/master branches.

Make sure the package still builds, then push the branches and the single upstream tag. gbp push does all of this for us, except that it only pushes since the last tag so we need to manually push our debian/master branch. 

git push origin debian/master
gbp push

Note that currently the Debian GNOME team does not wish to push all upstream tags, only tags with the debian/ and upstream/ prefix.

UNRELEASED

Please keep the debian/changelog series as UNRELEASED until the version is actually being uploaded.

debian/changelog

We use gbp dch -- debian/. In general, that means you shouldn't directly edit debian/changelog except before importing a new release and when finalizing the changelog for upload.

We currently use the default short mode for gbp dch. That means that only the "subject" line of git commits is used for creating the debian/changelog entries. Add Gbp-Dch: Full on a blank line at the end of your commit message if you prefer the full commit message be used instead. Or if your commit is too trivial to be included in debian/changelog, you can use Gbp-Dch: Ignore.

Make a release

For this example, the Debian release is named 3.26.2-1. Here we finalize the changelog, make a release tag, and push the latest packaging and release tag. 

gbp dch -- debian/

Review debian/changelog and adjust if needed. 

git add debian/changelog
git commit -m "Update changelog"
git push origin debian/master

Then, if you are the uploader (skip this step if you are being sponsored), finalise the changelog for the intended distribution: 

dch -D unstable --release "" # or experimental
gbp buildpackage --git-tag-only
git push origin debian/master debian/3.26.2-1

Finally build the package for upload (source-only uploads are preferred except for packages that need to go through the new queue) and upload with dput.

Other information

Initial packaging

This example is about the gnome-shell-extension-desktop-icons-ng package whose upstream URL does not start with git@ssh.gitlab.gnome.org:GNOME/. Initially we want to grab all commits up to the one represented by the upstream tag 0.15.0. A corresponding orig.tar.gz file already exists. 

git clone git@gitlab.com:rastersoft/desktop-icons-ng.git -b 0.15.0
cd desktop-icons-ng
git checkout -b upstream/latest
git checkout -b debian/master

gbp import-orig --pristine-tar ../gnome-shell-extension-desktop-icons-ng_0.15.0.orig.tar.gz \
--upstream-vcs-tag=0.15.0 --upstream-branch=upstream/latest --debian-branch=debian/master

git remote set-url origin pkg-gnome:shell-extensions/gnome-shell-extension-desktop-icons-ng.git
git push origin debian/master upstream/latest pristine-tar
git push origin upstream/0.15.0

Warning for stable updates

When branching from an old release, be sure to run a thorough diff against the debian tarball to ensure file permissions are correct and there aren't obsolete files. This is needed because the svn conversion process wasn't 100% precise.

History

The Debian GNOME Team switched most of their packages from svn to git in December 2017. For some background notes on that, see /SvnConversion.

pristine-tar branch not found

If you see this error when trying to run gbp buildpackage 

$ gbp buildpackage
gbp:warning: Pristine-tar branch "pristine-tar" not found

Just run these commands: 

git checkout pristine-tar
git pull pristine-tar
git checkout debian/master

Archived packages

When packages are removed from unstable, log into the Salsa page for the repo. Click Settings > General. Open Advanced and click Archive Project.

Here are the archived packages:

https://salsa.debian.org/groups/gnome-team/-/archived

Git hooks

Commits are announced in the #debian-gnome IRC channel and to tracker.debian.org subscribers subscribed to the Vcs keyword.

Misc. cases

Packages named differently from their git repos

These packages have different git repo names than their Debian package names. (In particular, Gitlab does not accept the + character in repo names.)

Our default gbp.conf

[DEFAULT]
pristine-tar = True
debian-branch = debian/master
upstream-branch = upstream/latest

[buildpackage]
sign-tags = True

[dch]
multimaint-merge = True

[import-orig]
postimport = dch -v%(version)s New upstream release; git add debian/changelog; debcommit
upstream-vcs-tag = %(version%~%.)s

[pq]
patch-numbers = False

upstream-vcs-tag

The most common format is 3.26.2. For those packages, use this line in debian/gbp.conf: 

upstream-vcs-tag = %(version%~%.)s

Some packages add a prefix like libdazzle-3.26.2. That needs just a slight adjustment: 

upstream-vcs-tag = libdazzle-%(version%~%.)s

Some upstreams still use CVS style tags. (CVS did not support using the . character in release tags). This format is perhaps a bit "ugly" so you can ask upstream to consider changing to a more modern format. gbp-import-orig allows rewriting the _ characters like this: 

upstream-vcs-tag = GNOME_SETTINGS_DAEMON_%(version%.%_)s

To do

  1. Add a myrepos config to make it easier to work with a large number of repositories

  2. Document workflow for git snapshots. (Basically fetch, tag locally, create a tarball, and then use gbp import-orig --upstream-vcs-tag= /path/to/tarball )

  3. Add protected tags to prevent pushing tags without a debian or upstream prefix.