Overview
The Debian Common Lisp Team uses git-buildpackage to make working with the packaging repositories easier.
The package layout is the default git-buildpackage layout with full upstream source, upstream tarballs (no upstream git history) and pristine-tar.
The git repositories can be browsed at: https://salsa.debian.org/common-lisp-team
Contents
Initial setup
Install tools
sudo apt install devscripts debhelper git-buildpackage pristine-tar
Set up git URL aliases
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 a -guest account) or if the repo ever moves.
You can set up and change git url handling in your ~/.gitconfig or ~/.config/git/config
[url "git@salsa.debian.org:common-lisp-team/"]
insteadof = common-lisp-team:or you can achieve the same with git config:
git config --global url.git@salsa.debian.org:common-lisp-team/.insteadof common-lisp-team:
If you do not have write permissions yet, you will need to use the anonymous url:
[url "https://salsa.debian.org/common-lisp-team/"]
insteadof = common-lisp-team:or
git config --global url.https://salsa.debian.org/common-lisp-team/.insteadof common-lisp-team:
Tell git-buildpackage to use pristine-tar by default
The following should be put in your ~/.gbp.conf:
[DEFAULT] pristine-tar = True
so that all git-buildpackage commands use the pristine-tar branch by default.
If you need to override this for a given repository (that does not have the pristine-tar branch), you can use the --git-no-pristine-tar or --no-pristine-tar option (depending on the command).
Cloning a repository
Type the following to check out the Debian packaging (here using sbcl as an example):
gbp clone common-lisp-team:sbcl
(the common-lisp-team: prefix refers to the URL alias set up above)
Repo layout
The Debian Common Lisp Team uses the current default git-buildpackage layout for its repositories:
The primary packaging branch is named master.
The parallel branch for upstream source without the debian/ directory is named upstream.
The pristine-tar branch is used for storing information necessary to recreate a bit-to-bit identical tarball.
The latest version of the package should always be committed to the master branch. Per-release branches, using the distribution codenames (e.g. stretch or jessie), can be used for (old)stable uploads if the need arises.
For each upstream and Debian version, a corresponding tag is created, with the respective patterns upstream/${UPSTREAM_VERSION} and debian/${DEBIAN_VERSION} (standard git-buildpackage mangling rules apply for some special characters like : or ~).
![/!\](/htdocs/debwiki/img/alert.png "/!\"){kind=small}
Some repositories may have branches or tags that do not follow this naming pattern. This is most likely because another git workflow was used in the past, before standardizing on the one described on this page.
Building the package
This can be achieved using:
gbp buildpackage
Several useful options are:
--git-ignore-new: for building even if there are uncommitted changes
--git-pbuilder: to build with git-pbuilder
--git-builder: to build with another builder such as sbuild
--git-tag: to create the debian/${DEBIAN_VERSION} tag at the end of the build process
--git-debian-branch=$BRANCH: for building a branch different from master
Moreover, all options not prefixed with --git are passed to the builder (which by default is debuild), so you can directly pass options such as -S (for source-only).
Updating the repository
Pulling remote changes into your remote copy can be achieved with:
gbp pull
This will update all three default branches (master, upstream, pristine-tar) and tags.
Making a change
Edit the corresponding files, modify the changelog, stage all your changes (with git add) and finally create the commit (using debcommit).
Please keep the debian/changelog series as UNRELEASED until the version is actually being uploaded.
Importing a new upstream version
Assuming that debian/watch contains the right information, this can be achieved using:
gbp import-orig --uscan
This will download the tarball, update the upstream and pristine-tar branches, create the upstream/${UPSTREAM_VERSION} tag, and merge upstream into master.
Then you should create a new changelog entry:
dch -v ${UPSTREAM_VERSION}-1 "New upstream release."
git add debian/changelog
debcommit
Pushing your changes
Push all three default branches and all tags with:
gbp push
Making a Debian release
Here we finalize the changelog, build the source package (for a source-only upload) and create the release tag, and push the latest packaging and release tag.
dch -r git add debian/changelog debcommit -r gbp buildpackage -S gbp push
Then sign and upload the _source.changes file.
If you want to do a source+binary upload (typically for a NEW upload), or use another builder, you should adapt the gbp buildpackage line (keeping the --git-tag option).
Vcs-* fields
The Vcs fields in debian/control should be the following:
Vcs-Browser: https://salsa.debian.org/common-lisp-team/${PACKAGE}
Vcs-Git: https://salsa.debian.org/common-lisp-team/${PACKAGE}.git
Commit notifications by email
When creating a new repository on Salsa, please setup the commit notifications by email through tracker.debian.org, see Salsa/Doc#Email_notifications.
This can be easily achieved with the salsa tool from devscripts:
salsa update_repo common-lisp-team/${PACKAGE} --email --email-recipient dispatch@tracker.debian.org
Further documentation
Using git
A full git tutorial is beyond the scope of this wiki page. See the Pro Git book for one popular guide.
Using git-buildpackage
Please read the manual to learn how to use git-buildpackage.