preferred debian packaging setup for dkg

Here is my current preferred way to package software for debian. Not all of these choices are in my control, but where they are, i'll try to make things happen this way. These are aspirational -- sometimes i don't get to doing them, and they may be updated. please suggest improvements, and let me know if you see me not following through on them.

Use revision control, git in particular

Anyone doing any sort of modern software development without revision control is a bit nutty. I prefer to take my risks elsewhere. Git is my preferred VCS of choice. I keep debian packaging in git, like any other software.

Upstream uses git

I prefer it when upstream also uses git. It's great when packagers can contribute to upstream, and using git in both places makes that feedback loop easier.

If upstream doesn't use git, but uses a different revision control system, i'll try to figure out a bridge between the two, and keep a git variant of upstream myself. Good packages for this are git-svn, git-cvs, git-remote-hg, and git-arch.

use `git-buildpackage`

git-buildpackage (gbp) makes tracking packaging changes and managing multiple branches concurrently possible. Sometimes it's complicated, but it's worth the effort.

keep upstream tarballs in git as well

I use the gbp import-orig approach that keeps everything under revision control, including pristine-tar deltas so that anything uploaded to the archive can be reconstructed from the git repository.

cryptographic verification of upstream

if upstream publishes tarballs, they should publish cryptographic signatures. If they do publish them, verify them using the pgpsigurlmangle feature in debian/watch (see uscan(1)). If they don't publish cryptographic signatures, ask them to do so.

If upstream just uses git repositories, they should release with tags. If their tags aren't signed, ask upstream to start signing them. Verify upstream's signed tags before considering packaging them.

If upstream signatures don't verify properly, ask your upstream about them!

keep upstream revision history in the same repo

Since upstream is using git (or i have a git mirror of upstream) i keep that in the same git repository as the debian packaging as well. I use gbp  import-orig --upstream-vcs-tag when importing tarballs to align the tarball with the upstream code.

Joey Hess has a good discussion about why this is nice to do, which convinced me.

I prefer to set upstream-vcs-tag in debian/gbp.conf directly, so that i don't need to remember to pass it on the command line.


When my packaging includes differences from upstream, I use the 3.0 (quilt) packaging format. gbp-pq helps to manage these


I tag every upstream release i see, and every uploaded debian version.

I try to sign all published tags.

repo hosting in the `debian` team on salsa

This is free software work. I do it openly and would love to have help. The best way to do that in debian that i know of right now is to use the debian group on , so that's where i put things if i can. I'm also fine hosting repos in other places, if there are enough helpful people active in those places to compensate for the cost of my mirroring to them.

If i am working with a packaging repo hosted on, i usually name that repo locally as salsa, so that i can reserve origin for upstream's repo.

standard branch naming

So a normal repo will have the following branches:

Some repos will also have the following branches:

pushing habits

Always push all the relevant branches, and all the relevant tags!

After a new version is uploaded to unstable, i might push like this:

git push salsa debian/sid upstream pristine-tar --follow-tags

pull/refresh habits

when i'm doing this collaboratively, sometimes i can forget to update from other people's work, and then we get into conflicts, especially for the upstream and pristine-tar branches.

Using tracking branches and git pull is useful for avoiding this situation, though it's possible to get into a little bit of a mess with this approach too.

I'd like to be able to separate the git remote update or git fetch action from the merging of tracking branches that git pull does, so that i can inspect the proposed differences before merging, without risking some other remote update happening during the review.

New upstream release

- make sure that the local debian/sid, upstream, and pristine-tar branches are up-to-date with the ones in salsa. - ensure that you know about upstream's tagged releases in git (e.g. git remote update) - make sure you're on the debian/sid branch. - run gbp import-orig --uscan

Assuming that debian/gbp.conf correctly documents the local configuration, the new version should get pulled in, and the local upstream, pristine-tar, and debian/sid branches should get updated correctly.

When you've ensured it builds and tests, and debian/changelog reflects the new version, make sure you push the packaging branches back to salsa.


i do my best to send patches upstream. Installing pre-configuring git-email makes it easy to do so if upstream is a mailing list-oriented project.

git config

If your entire debian/patches directory is managed by gbp-pq in patch-queue/master, you can now send it upstream with:

git send-email debian/sid..patch-queue/debian/sid

If upstream is a project instead, they'll probably prefer pull requests. I don't have a good workflow for this (it usually means i have to fire up a web browser, which i dislike). If anyone has a good suggestion for how to automate pull request submissions, please tell me.

Historical imports

some of these practices have grown over time. I don't make a big deal about trying to rewrite history to pretend i've practiced them forever. If i'm transitioning to them, i'm fine with just transitioning to them going forward and not trying to import some huge history of past work.

I don't object to anyone doing historical imports (i welcome them, in fact!) but if i've got a few hours to spend on debian, i'd rather spend it on forward-looking work.

file formatting

I make use of wrap-and-sort -ast from the devscripts package to ensure that files in debian/ are reasonably formatted. Among other aesthetic benefits, this makes diffs much cleaner.


I prefer machine-readable debian/copyright files.

feature branches

TBD write more about debian packaging feature branches here!