Package maintainance using CDBS and git-buildpackage

Building the package

No special handling is required for normal package builds.

In particular, you can completely ignore the file debian/control.in file and simply use debian/control directly, if you are not interested in CDBS.

Upgrading to new upstream source

Official releases are tagged and signed and binary diffs of tarballs are stored using pristine-tar. This is documented below /usr/share/doc/git-buildpackage/manual-html/.

A custom build target shows current upstream and packaging versions:

debian/rules print-version

Current upstream source is fetched (and repackaged as needed) using this other build target:

debian/rules get-orig-source

Importing git tag + tarball

When upstream also use git, and need no DFSG-nonfre files stripped from source, it is preferred to keep that synchronized with our git: Look for a git URL in Source stanza of debian/copyright file.

First (once) make sure your local clone tracks upstream git:

git remote add upstream-repo ${upstream_git_url}

1. Fetch new upstream source, overriding DEB_UPSTREAM_TARBALL_VERSION:

debian/rules get-orig-source DEB_UPSTREAM_TARBALL_VERSION=${new_upstream_version}

2. Import tag + fetched source:

gbp import-orig --pristine-tar --sign-tags --upstream-vcs-tag=${tag} ${path-to-fetched-tarball}

Importing fake tarball from git tag

When upstream only use git, don't issue tarball releases, we need to create a fake tarball from git: Look for a git URL in Source stanza of debian/copyright file.

1. Have your local clone track upstream git (skip first command on repeated use):

git remote add upstream-repo ${upstream_git_url}
git fetch upstream-repo

1a. Create fake tarball:

mkdir ../tarballs
git archive --prefix=${project}-${tag}/ -o ../tarballs/${project}-${tag}.tar.gz ${tag}

1b. Fir github, you can alternatively fetch auto-created tarball:

debian/rules get-orig-source DEB_UPSTREAM_TARBALL_VERSION=${new_upstream_version} DEB_UPSTREAM_TARBALL_BASENAME=${tag}

2. Import tag + fetched source:

gbp import-orig --pristine-tar --sign-tags --upstream-vcs-tag=${tag} ../tarballs/${project}-${tag}.tar.gz

Importing tarball w/ checksum

When upstream does not use git, we have less ability to follow upstream activity, so extra care should be taken to ensure the integrity of imported code, by use of a checksum for the tarball.

1. Fetch new upstream source, overriding DEB_UPSTREAM_TARBALL_VERSION and suppressing existing DEB_UPSTREAM_TARBALL_MD5:

debian/rules get-orig-source DEB_UPSTREAM_TARBALL_MD5= DEB_UPSTREAM_TARBALL_VERSION=${new_upstream_version}

2. Import fetched source:

gbp import-orig --pristine-tar --sign-tags ${path-to-fetched-tarball}

3. Store new md5sum to help ensure identical source is received later.

Avoid alternative import methods

Please avoid other upgrade methods e.g. using uscan, especially when repackaging to strip non-DFSG files.

When copyright check is enabled and the source package is detected to contain new files or changed copyright or licensing statements, the following is emitted during normal builds:

WARNING: The following (and possibly more) new or changed notices discovered:

 ...

To fix the situation please do the following:
  1) Fully compare debian/copyright_hints with debian/copyright_newhints
  2) Update debian/copyright as needed
  3) Replace debian/copyright_hints with debian/copyright_newhints

To treat such warnings as errors and avoid removing debian/copyright_newhints in clean target when different, set DEB_MAINTAINER_MODE=1 during build.

Maintaining packaging build routines

This source package wraps debhelper commands and other tedious parts of the build routines using the CDBS framework. Please refer to the actual makefile snippets included from debian/rules for details on their purpose and ways to override defaults.

Setting DEB_MAINTAINER_MODE=1 enables additional build routines helpful during development of the package, but unfit for normal builds. This typically includes the CDBS feature of auto-updating debian/control with CDBS-related build-dependencies, which is forbidden by Debian Policy as build environment must not change during automated builds.

Use git for your package at collab-maint area of Alioth

Create new git locally from pristine tarball:

    mkdir mypkg
    cd mypkg
    git init
    cd ..
    mkdir tarballs
    cd tarballs
    wget http://example.org/source/my_pkg-1.2r3.tgz
    mv my_pkg.tgz mypkg_1.2.3.orig.tar.gz
    cd ../mypkg
    gbp import-orig --pristine-tar --sign-tags ../tarballs/mypkg_1.2.3.orig.tar.gz

Create debian packaging

    mkdir debian
    nano debian/rules
    nano debian/control
    nano debian/gbp.conf
    ...
    git add debian
    git commit

Publish git at collab-maint area of Alioth

    git remote add origin git.debian.org:/git/collab-maint/mypkg
    git config branch.master.remote origin
    git config branch.master.merge refs/heads/master
    ssh git.debian.org "cd /git/collab-maint && ./setup-repository mypkg 'mypkg Debian packaging'"
    git push --all; git push --tags

If you already have some Debian packaging then it is even easier

Bootstrap local git

    gbp import-dsc --pristine-tar --sign-tags mypkg_1.2.3.dsc

Or more elegantly you can bootstrap with as much history from past packaging as is possible:

Bootstrap local git

    iceweasel http://packages.qa.debian.org/m/mypkg.html
    (copy URLs from icons at right of "versions" in left side)
    dget -d http://ftp.debian.org/debian/pool/main/m/mypkg/mypkg_1.2.2-6.dsc
    ...
    debsnap -d . mypkg
    ...
    gbp import-dscs --pristine-tar --sign-tags mypkg*

You might still want to apply my cdbs-skel files. Use same commands and follow the git instructions to resolve any conflicts that might occur (if e.g. the packaging already contained a README.source).


See Also

Package Relationship management with CDBS

--- CategoryGit