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
Recommended setup
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:Similarly, you can set up a git url for GNOME too.
[url "git@gitlab.gnome.org:GNOME/"]
insteadof = gnome:
Do initial clone
For this example, we're going to grab the gnome-desktop3 source (the git repos are named gnome-desktop).
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 gnome to track the upstream GNOME repo.
gbp clone pkg-gnome:gnome-desktop cd gnome-desktop git remote add gnome gnome:gnome-desktop --fetch --tags
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 gnome 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. In this example, the new version is named 3.26.2.
git push origin debian/master upstream/latest pristine-tar git push origin upstream/3.26.2
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
TODO
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
TODO: Rewrite this section for Salsa
When packages are removed from unstable, log into git.debian.org and move the repos to the ~archive directory. Edit the description file to add a prefix mentioning what series it was removed from.
Here are the archived packages: https://anonscm.debian.org/git/pkg-gnome/~archive
Git hooks
Commits are announced in the #debian-gnome IRC channel and to tracker.debian.org subscribers subscribed to the Vcs keyword.
Misc. cases
- intltool upstream uses bzr so we don't include upstream commit history for it.
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.)
- atk1.0
- atkmm1.6
- bijiben (upstream's git repo is gnome-notes)
- clutter1.0
- clutter-gst-3.0
- gdm3
- glib2.0
- glibmm2.4
- gnome-games-app
- gtk+2.0
- gtk+3.0
- gtk+4.0
- libxml++2.6
- libsigc++-2.0
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
Add a myrepos config to make it easier to work with a large number of repositories
- Document workflow for git snapshots. (Basically fetch, tag locally, create a tarball, and then use gbp import-orig --upstream-vcs-tag= /path/to/tarball )
Add protected tags to prevent pushing tags without a debian or upstream prefix.
- There are still a few packages (mostly unmaintained) that need to be converted from svn to git.