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.
preferred debian packaging setup for dkg
- Use revision control, git in particular
- Upstream uses git
- use `git-buildpackage`
- keep upstream tarballs in git as well
- cryptographic verification of upstream
- keep upstream revision history in the same repo
- repo hosting in `collab-maint`
- standard branch naming
- pushing habits
- pull/refresh habits
- Historical imports
- file formatting
- feature branches
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.
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.
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 `collab-maint`
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 collab-maint on alioth (git.debian.org), 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 repo hosted on git.debian.org, i usually name that repo locally as gdo, 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:
experimental (work targetting the experimental )
wheezy, jessie, etc. (for proposed updates for the given suite)
wheezy-security, jessie-security (for security fixes for the given suite)
patch-queue/master, patch-queue/jessie, etc (note that these branch labels often jump around in a non-fast-forwardable way as new releases happen and patches are updated -- use a + any remote refspec for a tracking branch in your local copy)
upstream-vcs (if i want to publicly track the head of what i think upstream development is)
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 gdo master upstream pristine-tar --follow-tags
when i'm doing this collaboratively, sometimes i can forget to update from other people's work, and then we get into conflicts.
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.
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 sendemail.to firstname.lastname@example.org
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 master..patch-queue/master
If upstream is a github.com-hosted 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.
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.
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.
TBD write more about debian packaging feature branches here!