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 the `debian` team on salsa
- standard branch naming
- pushing habits
- pull/refresh habits
- New upstream release
- 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.
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 https://salsa.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 packaging repo hosted on https://salsa.debian.org, 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:
debian/experimental (work targetting the experimental distro)
debian/bullseye, debian/buster, etc. (for proposed updates for the given suite)
patch-queue/debian/sid, patch-queue/debian/bullseye, 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 salsa debian/sid 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, 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 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 debian/sid..patch-queue/debian/sid
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!