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
- Recommended setup
- Use git
- Use git-buildpackage
- Repo layout
- Package new upstream version
- Make a release
- Other information
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 "firstname.lastname@example.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.
A full git tutorial is beyond the scope of this wiki page. See the Pro Git book for one popular guide.
Please read the manual to learn how to use git-buildpackage.
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.
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.
Please keep the debian/changelog series as UNRELEASED until the version is actually being uploaded.
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.
This example is about the gnome-shell-extension-desktop-icons-ng package whose upstream URL does not start with email@example.com: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 firstname.lastname@example.org: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
Add the debian/ folder including debian/gbp.conf and debian/watch.
Create a blank salsa project on the website
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.
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
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:
Commits are announced in the #debian-gnome IRC channel and to tracker.debian.org subscribers subscribed to the Vcs keyword.
- 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.)
- bijiben (upstream's git repo is gnome-notes)
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
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
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.