Differences between revisions 8 and 9
Revision 8 as of 2018-01-29 21:58:30
Size: 6709
Comment: Add missing dch text
Revision 9 as of 2018-02-01 09:42:14
Size: 6732
Comment: Add ToC
Deletions are marked like this. Additions are marked like this.
Line 9: Line 9:



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

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:


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:

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 ~).

/!\ 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

Pushing your changes

With the version of git-buildpackage in buster/unstable:

gbp push

(this will push all three default branches and all tags)

With the version of git-buildpackage in stretch and older:

git push --all
git push --tags

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 --git-tag
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 scripts from https://salsa.debian.org/mehdi/salsa-scripts, using:

./emails_on_push.sh common-lisp-team/${PACKAGE} dispatch+${PACKAGE}_vcs@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.