Packaging

Newcomer guidelines for building proper Debian packages
Announcing intent to package
Packaging with Git
Tools
Packaging walkthrough
Branches
Backports with Git
Importing source packages
Patches
Commit policy
Removing packages
Tips & tricks
Packaging with Subversion
Subversion tips
Backports
PPA for Ubuntu by UbuntuGIS
Derivatives working together with Debian GIS
R packages
Sponsorship

Newcomer guidelines for building proper Debian packages

Some newcomers tend to go the create DEBIAN dir, move files around and `dpkg-deb -b` way to create Debian packages. Short answer: Forget about this. The only way to the official Debian mirror leads via proper source packages. The right way to build Debian packages is described in the Debian New Maintainers' Guide.

See also the package template in our Git repository.

Announcing intent to package

If you intent to work on a Debian package you should follow the normal Debian rules and file a WNPP bug report.

It is a good idea to keep the Debian GIS mailing list debian-gis@lists.debian.org in CC and to set it as the owner of the ITP to keep your co-workers informed. This will ensure that we notice if for some reason the package has not been uploaded.

In addition, please add the package to the task file where it fits the best, and document your ITP number using the WNPP field name.

Packaging with Git

This section describes the procedures that Debian GIS contributors use to maintain packages in the Git repositories on git.debian.org.

It covers how to upload an initial package, how to update packages, how to build them, how to upgrade them, and how to package for derivatives.

For a more general guide to Git, see the Git User's Manual at https://www.kernel.org/pub/software/scm/git/docs/user-manual.html.

Tools

  • build-essential (PTS) depends on the essential packages required for every kind of Debian package development.

  • devscripts (PTS) provides debcheckout (man), debcommit (man), debuild (man), uscan (man), licensecheck (man), and many other commonly used programs in the Debian source packaging work flow.

  • git-buildpackage (PTS, man) and its helper tools are used by most source packages maintained as Git repositories in Debian GIS.

  • pristine-tar (PTS, man) is used to allow byte-identical recreation of the original tarball from the upstream branch.

    Use gbp buildpackage --git-pristine-tar to generate missing upstream tarballs with the pristine-tar command from the upstream and pristine-tar branches in the Git repository.

  • pbuilder (PTS, man) and cowbuilder (PTS, man) are used for clean builds from the source packages in distribution specific chroot environments.

    Use gbp buildpackage --git-pbuilder to use cowbuilder for building the package in a clean chroot instead of on the development system itself using plain debuild.

Packaging walkthrough

The packaging walkthough is split into the following subsections:

Setup the build environment

Building the source packages in clean chroot environments is supported out of the box by git-buildpackage's --git-pbuilder option.

cowbuilder is preferred over pbuilder by git-buildpackage for its increased performance using Copy-On-Write techniques.
pbuilder can be selected instead by setting the environment variable BUILDER to "pbuilder", and
qemubuilder can be selected by setting BUILDER to "qemubuilder".

Creating the cowbuilder chroot

Root privileges are required to run cowbuilder and pbuilder.
Configure sudo with visudo to allow <username> passwordless execution of cowbuilder and pbuilder using the following settings:

Defaults! PBUILDERS setenv

# Cmnd alias specification
Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder

# User privilege specification
<username>     ALL=(root)     NOPASSWD:PBUILDERS

To create distribution specific cowbuilder chroots, use:

sudo cowbuilder --create \
                --distribution=<distribution> \
                --basepath=/var/cache/pbuilder/base-<distribution>.cow

To create architecture specific cowbuilder chroots, use:

sudo cowbuilder --create \
                --distribution=<distribution> \
                --architecture=<architecture> \
                --basepath=/var/cache/pbuilder/base-<distribution>-<architecture>.cow

The default distribution for git-buildpackage is sid, other distributions can be specified with --git-dist=<distribution>

To create the default chroot for git-buildpackage:

sudo cowbuilder --create \
                --distribution=sid \
                --basepath=/var/cache/pbuilder/base-sid.cow

You can also use the git-pbuilder wrapper to create (and update) cowbuilder chroots for git-buildpackage:

git-pbuilder create

This will also create the default chroot for git-buildpackage (/var/cache/pbuilder/base-sid.cow).

Other distributions and architectures can be specified with environment variables:

DIST=<distribution> ARCH=<architecture> git-pbuilder create

Configure lintian pbuilder hook

It's highly recommended to run lintian after every build. pbuilder provides an example lintian hook in /usr/share/doc/pbuilder/examples/B90lintian for this.

Copy this file to your pbuilder hooks directory, and modify it to report all lintian tags and not fail the build if lintian reports issues.

mkdir /var/cache/pbuilder/hook.d/
cp /usr/share/doc/pbuilder/examples/B90lintian /var/cache/pbuilder/hook.d/
sed -i 's/lintian -I --show-overrides/& --pedantic -E/; s/^su /##&/; s/^#su /su /' /var/cache/pbuilder/hook.d/B90lintian

Specify the pbuilder hook directory when creating the chroot to run the hook scripts contained therein.

sudo cowbuilder --create \
                --distribution=sid \
                --basepath=/var/cache/pbuilder/base-sid.cow \
                --hookdir=/var/cache/pbuilder/hook.d/

If you have already created the chroot, then you will need to do an update and override the configuration to ensure the hook is found:

sudo cowbuilder --update \
                --override-config \
                --basepath=/var/cache/pbuilder/base-<distribution>-<architecture>.cow \
                --hookdir=/var/cache/pbuilder/hook.d/

Updating cowbuilder chroots

Remember to update the chroots for git-buildpackage regularly to build with the latest packages from the repositories:

sudo cowbuilder --update \
                --basepath=/var/cache/pbuilder/base-<distribution>-<architecture>.cow

Or using git-pbuilder:

DIST=<distribution> ARCH=<architecture> git-pbuilder update

Starting a new package

When the upstream sources are distributed as compressed tar archives (tar.gz, …):

mkdir <package>
cd <package>
git init
gbp import-orig --pristine-tar ../package_version.orig.tar.gz
git clone git://git.debian.org/git/pkg-grass/package_template.git
mv package_template/debian/ .
rm -rf debian/.git/ package_template/

The above steps will create a repository with the appropriate layout for git-buildpackage, with three branches:

  • master, where the Debian development will happen,

  • pristine-tar, used by the pristine-tar tool during the package build process to recreate the original tarball, and

  • upstream, which will contain the upstream source.

Additionally the content of the debian/ directory is taken from the Debian GIS package template.

Change the placeholders in the files under the debian/ directory for the package in question following the requirements documented in the Policy section, and you can start building the package.

Working with existing packages

When the package is already in the Debian archive, you can use the debcheckout command with its --git-track='*' option to clone the package git repository.

debcheckout --git-track='*' <package>

For packages that are not in the archive yet, you can use the gbp clone command with its --all option to achieve the same.

gbp clone --all https://anonscm.debian.org/git/pkg-grass/<package>.git

To update the master, upstream and pristine-tar branches from an existing clone at once, use the gbp pull command.

gbp pull --pristine-tar

Updating other branches like experimental or ubuntu/precise can be done with git.

git fetch origin
git checkout <branch>
git pull

Make the changes to your package using the various tools at your disposal.

Commit the changes in your git repository following the Commit policy.

And don't be afraid to rebase your local branches into coherent commits before pushing your changes to git.debian.org.

Some prefer to update debian/changelog with each commit using the dch command, others leave this to the gbp dch tool at package release time.

In case you use gbp dch for the changelog entries, don't forget to use it when you stop working on the package.

While working on your changes you likely need to perform multiple rebuilds of the package.

Since the overhead of setting up the build environment can be quite extensive when many build dependencies need to be installed, it can be tempting to build the package with plain debuild instead of using a clean cowbuilder chroot.

It is highly recommended to always build the package in a clean chroot using gbp buildpackage --git-pbuilder. Refer to Setup the build environment for details about creating the cowbuilder chroots.

Upgrading to a new upstream release

To download the new upstream release and import the sources into the git repository, the most common way is to use uscan and gbp import-orig as follows.

First download the upstream tarball with uscan:

uscan --verbose --download

Then import the downloaded tarball with gbp import-orig:

gbp import-orig --pristine-tar ../<package>_<version>.orig.tar.gz

Finally create a new debian/changelog entry for the new upstream release and commit the change:

dch -v <version>-1 "New upstream release."
debcommit -a

gbp import-orig makes it easy to update the upstream branch using upstream releases distributed as a compressed archive, and to merge these changes in the master branch.

The gbp import-orig --pristine-tar option is very useful for stabilizing the MD5 sum of the orig.tar.gz produced when building a source package from the repository alone (not doing so results in archive rejection of package updates).

When the pristine-tar option is not configured in debian/gbp.conf you need to explicitly use gbp import-orig --pristine-tar.

If you do not use git-buildpackage, please use pristine-tar anyway to register the compressed archives that you upload to Debian as original upstream sources (the orig.tar.{gz|bz2|xz} file), with a command such as the following, where <tarball> is a path to the archive file and <tag> is the upstream release tag for that archive (as a fallback, if you created the tarball from a given branch, use the name of the branch).

pristine-tar commit <tarball> <tag>

Warning

While it's possible to use the --uscan option to have gbp import-orig download the upstream tarball using uscan before importing it, its use is not recommended when the upstream tarball is repacked. There is a bug (#635920) that causes gbp import-orig to import the unrepacked tarball. This bug is fixed in jessie, but gbp import-orig in wheezy is still affected.

Update patches for new upstream release

If patches are included in the source package it's likely they have been applied upstream and can be removed, or need to be refreshed.

Step through the list of patches and update them for the new upstream release.

quilt push && quilt refresh

Check all patches that fail to apply and remove the ones applied upstream, git rm the patch file and remove its entry in debian/patches/series.

quilt delete <patch>
git rm debian/patches/<patch>

Patches that were only partially applied usually need to be forcefully applied and refreshed.

quilt push -f && quilt refresh

Review the *.rej files to make sure the patch was properly refreshed.

If manual merging of upstream changes is required, edit the file(s) and refresh the patch afterwards.

quilt edit <file>
quilt refresh

When all patches have been refreshed, and the quilt series is fully applied, unapply all patches and commit the changes.

quilt pop -a
rm -rf .pc/
git commit -m "Refresh patches" -a

Update copyright file

New upstream releases are likely to include copyright changes that need to be reflected in the debian/copyright file.

Review the changes in the upstream sources since the previous release by inspecting the diff between the upstream branch commits.

git diff upstream~1 upstream

Or by tag:

git diff upstream/<old-version> upstream/<new-version>

Look for removed files which may need to be removed from the debian/copyright file too, new files whose copyright statements need to be included in the debian/copyright file, and changes in existing files.

It may also be helpful to review the copyright file generated by licensecheck2dep5 for the new upstream release, and compared it to the existing debian/copyright file.

licensecheck --copyright -r * | /usr/lib/cdbs/licensecheck2dep5 > debian/copyright.new
diff -u debian/copyright debian/copyright.new

Finally tools such as license-reconcile can be useful for copyright review too.

Building the package

It's highly recommended to always build the package in clean cowbuilder chroot using:

gbp buildpackage --git-pbuilder

Without the --git-pbuilder option plain debuild is used on the development system itself instead of a distribution specific chroot.

To build the package for a different distribution than the default sid such as experimental or wheezy-backports, use the --git-dist option.

gbp buildpackage --git-pbuilder --git-dist=<distribution>

Refer to the Setup the build environment section for creating the distribution specific chroots.

git-buildpackage uses the configuration in debian/gbp.conf to override its default settings, and commandline parameters to overide both the built-in defaults and those loaded from debian/gbp.conf.

It's not recommended to set the git-builder option in debian/gbp.conf to use git-pbuilder by default, because this setting cannot by overriden using a commandline parameter.

The use of pristine-tar to recreate a byte-identical orig.tar.gz from the upstream branch is highly recommended.

If the pristine-tar is not set via the debian/gbp.conf you can use the --git-pristine-tar option.

gbp buildpackage --git-pbuilder --git-pristine-tar

Or if you need to override the automatic use of pristine-tar via the debian/gbp.conf use the --git-no-pristine-tar option.

Use the --git-arch option to build the package for a different architecture than that of the development system, such as i386 on amd64.

gbp buildpackage --git-pbuilder --git-arch=<architecture>

Refer to the Setup the build environment section for creating the architecture specific chroots.

When the source of the package is not in the master branch, use the --git-debian-branch option to specify another branch.

gbp buildpackage --git-pbuilder --git-debian-branch=<branch>

For building a package for experimental using dependencies from unstable only, the above is sufficient.

To build the package using a different distribution and branch use:

gbp buildpackage --git-pbuilder --git-dist=<distribution> --git-debian-branch=<branch>

For example, use the wheezy distribution and the wheezy-backports branch to build a backport. Or using both the wheezy distribution and branch to build the package for stable-proposed-updates.

Packages targeting UbuntuGIS or derivatives such as OSGeo-Live can be built from their distribution specific branches.

  • UbuntuGIS branches should be named ubuntu/<codename>, for example ubuntu/precise, ubuntu/quantal, etc.

  • OSGeo-Live branches should be named osgeo/<version>, for example osgeo/7.0, osgeo/8.0, etc.

  • Branches for other derivatives should be named <derivative>/<codename|version>.

    Using release codenames is preferred over release versions, but the latter are reasonable when codenames are not used.

    If the packaging work flow benefits more from tracking release aliases such as stable, testing or unstable this is also possible.

Pushing to git.debian.org

Before pushing your packaging changes to git.debian.org for the first time, an empty repository needs to be created there. And you need to configure a Git remote for the repository on Alioth.

Create a Git repository on Alioth

To create a Git repository on Alioth, connect to git.debian.org, enter the /git/pkg-grass directory, and run the ./setup-repository script.

ssh git.debian.org
cd /git/pkg-grass
./setup-repository <package> 'Packaging of <package> in Debian'

This will create an empty, bare, shared Git repository and setup some hooks. Each package is kept in its own Git repository.

See the SSH tips section for how to configure the default ssh username for git.debian.org.

Configure a Git remote for the repository

On your local machine add the Alioth repository as a remote:

git remote add origin ssh://git.debian.org/git/pkg-grass/<package>.git

This is done automatically after cloning a repository, for instance with debcheckout. The default remote repository is called origin.

Push the package

Make sure you've created the repository on Alioth and that you've added the remote!

Push all your locally changed branches to Alioth:

git push --all --set-upstream
git push --tags

The --set-upstream option is required to have the locally created branches track the changes from the upstream repository on Alioth.

Uploading a new package release

Before uploading a package, make sure that the appropriate distribution and urgency are set in the debian/changelog.

The defaults used by dch -r are usually fine, security uploads should use urgency=high.

A non default distribution and urgency can be specified with the --distribution and --urgency options, or their short form:

dch -r -D <distribution> -u <urgency>

First sign the .changes file generated after the package build:

debsign ../<package>_<version>_<architecture>.changes

If you are not a DD or lack the DM permissions to upload the package to ftp-master.debian.org, the package can be uploaded to mentors.debian.net.

Warning

Security uploads must be coordinated with the Security Team following the procedure documented in the Debian Developer's Reference: Handling security-related bugs

Do NOT upload to security-master or proposed-updates without prior authorization from the Security Team.

Upload to mentors

Before you can upload to mentors.debian.net you need to create an account using the registration form.

Follow the guidelines in the Introduction for maintainers to configure ~/.dput.cf for HTTP uploads:

[mentors]
fqdn = mentors.debian.net
incoming = /upload
method = http
allow_unsigned_uploads = 0
progress_indicator = 2
# Allow uploads for UNRELEASED packages
allowed_distributions = .*

You can then upload the signed .changes to mentors.debian.net using dput:

dput mentors ../<package>_<version>_<architecture>.changes

Once the package is available on mentors you can request sponsorship of the upload to the archive.

Upload to ftp-master

DDs and DMs (for specific packages) can upload to the archive directly withouth going through mentors first.

The default dput configuration in /etc/dput.cf will upload to ftp-master if no host is specified.

To upload the signed .changes to ftp-master.debian.org you can use plain dput:

dput ../<package>_<version>_<architecture>.changes

Or specify the host explicitly:

dput ftp-master ../<package>_<version>_<architecture>.changes

Tag a release

It's highly recommended to not tag a release before it's uploaded to the archive. Forcefully updating an existing tag for changes made before the actual upload is not desirable, especially when the tag is signed.

To tag a release using the version from latest entry in debian/changelog you can use:

debcommit -r

If the build modified the working directory, those modifications need to be reverted before the release can be tagged.

You can also tag a specific distribution and/or version using:

git tag <distribution>/<package_version>

To tag a release using a specific commit instead of the most recent in the current branch use:

git tag debian/x.y-z <commit>

Remember to push the new tags:

git push --tags

Branches

From time to time, there is a need to work in a branch for a stable update or a security fix. This kind of release specific packaging lives in its own release specific branches in the git repository.

First create a branch from the tag that represents the version currently in the archive if there is no release specific branch yet:

git checkout -b jessie debian/1.2.0-1

If the jessie branch already exists, check it out and merge the version currently in the archive:

git checkout jessie
git merge debian/1.2.0-1

From this point on, work normally in the jessie branch, build, tag and push. If you created the branch locally, remember to use the git push --set-upstream option to track changes from the shared repository on Alioth.

Backports with Git

Backports are maintained in separate branches named after the distribution in question (wheezy-backports, jessie-backports, etc.).

For UbuntuGIS and OSGeo-Live their respective branches are used for the Ubuntu specific backports (ubuntu/xenial, osgeo/10.0, etc.).

The following sections document the workflow for creating, updating, building, pushing, uploading & tagging backports.

The workflow for backports is not much different from the regular workflow documented in the Packaging walkthrough section.

The backports workflow mostly includes the specific considerations for backports, which are generally simple rebuilds of packages available in Debian testing/unstable for a different distribution release.

Creating a backport

To create a backport, first create the branch from the release tag of the version in testing:

git checkout -b jessie-backports debian/1.2.3-1

Update the debian-branch option in debian/gbp.conf to have git-buildpackage use the backports branch instead of master:

sed -i 's/^debian-branch\s*=.*/debian-branch = jessie-backports/g' debian/gbp.conf

Also update the Vcs-Git URL in debian/control for debcheckout to use the backports branch instead of the default:

sed -i 's/\(^Vcs-Git: .*\.git\).*/\1 -b jessie-backports/g' debian/control

Ensure that the proper version and distribution for the backport are set in debian/changelog.

For packages to be uploaded to backports.debian.org use dch --bpo to set the version and distribution automatically:

dch --bpo "Update branch in gbp.conf & Vcs-Git URL."

Backports for Ubuntu like those intended for UbuntuGIS and OSGeo-Live should append the distribution codename with the tilde prefix (as documented in the UbuntuGIS PPA section) to the version used for the last changelog entry, and set the distribution explicitly:

dch -v $(dpkg-parsechangelog -SVersion)~xenial1 -D xenial -m "Rebuild for xenial." -b
dch -am "Update branch in gbp.conf & Vcs-Git URL."

Review and commit the changes for the backport, before continuing to build the package:

git diff
debcommit -a

Simple backports don't require further changes than those for the changelog.

More complex backports may need changes to (build) dependency version requirements, patches to support older versions of (build) dependencies, or disabling features for missing or unmet (build) dependencies in the backports distribution. Ideally only the (build) dependencies from the stable release are used, but it's okay to use some backported (build) dependencies from the backports archive.

Updating a backport

To update an existing backport, checkout the backports branch and merge the release tag of the version in testing:

git checkout jessie-backports
git merge debian/1.3.2-1

Resolve the merge conflict with a 3-way merge and keep the changelog entry for the previous backport above its releated release.

Commit the changes after resolving the conflicts and adding the changed files:

git status
vi debian/changelog
git diff
git add debian/changelog
...
git commit -a

Add a new changelog entry for the updated backport:

dch --bpo

If there were no further changes, only the 'Rebuild for distribution' bulletpoint needs to be kept in the changelog.

Set the version and distribution explicitly if the backport is intended for Ubuntu (e.g. UbuntuGIS or OSGeo-Live), dch --bpo is only appropriate for Debian Backports:

dch -v $(dpkg-parsechangelog -SVersion)~xenial1 -D xenial -m "Rebuild for xenial." -b

Review and commit the changes for the updated backport, before continuing to build the package:

git diff
debcommit -a

Building a backport

The procedure to build a backport is nearly idential to building a regular package, in addition to the git-buildpackage --git-pbuilder option, the appropriate distribution for the cowbuilder chroot needs to be specified with the --git-dist option and the last version of the package in the stable release or backports with the -v option:

gbp buildpackage --git-pbuilder --git-dist=jessie -v1.2.0-1

If the build dependencies cannot be satisfied in the stable release, use the backports chroot instead:

gbp buildpackage --git-pbuilder --git-dist=jessie-backports -v1.2.0-1

Specifying the version is one of the Basic Rules for Debian Backports:

It is recommended to include all changelog entries since the last version on debian-backports or since stable if it's the first version. You should do this by passing "-v" to dpkg-buildpackage. Eg: "debuild -v0.7.5-2", where "0.7.5-2" is the version in stable. If the package wasn't in stable or backports before you don't have include the changelog entries (but you are free to do so). It helps others to follow the changes introduced with the backport (by reading the changes mailing list).

Building backports for the Ubuntu PPAs need to use the -S option to create a source-only upload:

gbp buildpackage --git-pbuilder --git-dist=xenial-<ppa> -S

If the package does not exist in the Ubuntu archive yet, the -sa option needs to be used as well to include the .orig.tar.gz in the upload too:

gbp buildpackage --git-pbuilder --git-dist=xenial-<ppa> -S -sa

It's a good idea to first do a full build by leaving out the -S option to ensure all binary packages build with the dependencies from Ubuntu, before building the source-only upload for Launchpad:

gbp buildpackage --git-pbuilder --git-dist=xenial-<ppa>

Refer to the Launchpad documentation for more information about building packages for Ubuntu PPAs.

If the cowbuilder chroots for the backport are not available yet, set those up first as documented in the next section. Otherwise you can continue to push the changes for the backport if it built successfully.

Setup the build environment for backports

To quote another one of the Basic Rules from the Debian Backports documentation:

Make sure that you have a proper build environment that only contains the suite for which the backport is for (e.g. jessie if you want to upload to jessie-backports) and no unneeded backports. [...]

Ideally only the (build) dependencies from the stable release are used for the backport, but it's okay to use some backported (build) dependencies from the backports archive if the dependencies cannot be satisfied otherwise.

Backports should always be built in the appropriate cowbuilder chroot, a plain stable chroot where possible, or one with the backports repository enabled in addition otherwise.

Ensure that the sudo configuration for cowbuilder is in place and the lintian pbuilder hook is configured before creating the cowbuilder chroot for stable updates and backports.

Plain stable cowbuilder chroots can be created with:

sudo cowbuilder --create \
                --distribution=jessie \
                --basepath=/var/cache/pbuilder/base-jessie.cow \
                --hookdir=/var/cache/pbuilder/hook.d/

To create a chroot with the backports repository enabled, use:

sudo cowbuilder --create \
                --distribution=jessie-backports \
                --basepath=/var/cache/pbuilder/base-jessie-backports.cow \
                --hookdir=/var/cache/pbuilder/hook.d/

For UbuntuGIS and OSGeo-Live their respective PPAs need to be specified along with the regular Ubuntu mirror.

Creating a cowbuilder chroot with the ubuntugis-unstable PPA enabled can be done with:

sudo cowbuilder --create \
                --distribution=xenial \
                --basepath=/var/cache/pbuilder/base-xenial-ubuntugis-unstable.cow \
                --hookdir=/var/cache/pbuilder/hook.d/ \
                --mirror=http://nl.archive.ubuntu.com/ubuntu/ \
                --othermirror="deb [ trusted=yes ] http://ppa.launchpad.net/ubuntugis/ubuntugis-unstable/ubuntu xenial main" \
                --components="main universe"

Make sure to replace the Ubuntu mirror URL with the mirror closest to your location.

A cowbuilder chroot with the OSGeo-Live nightly PPA enabled can be created with:

sudo cowbuilder --create \
                --distribution=xenial \
                --basepath=/var/cache/pbuilder/base-xenial-osgeolive.cow \
                --hookdir=/var/cache/pbuilder/hook.d/ \
                --mirror=http://nl.archive.ubuntu.com/ubuntu/ \
                --othermirror="deb [ trusted=yes ] http://ppa.launchpad.net/osgeolive/nightly/ubuntu xenial main" \
                --components="main universe"

Also make sure to replace the Ubuntu mirror URL with the mirror closest to your location.

Pushing a backport

When the backports branch was created locally, e.g. for a new backported package, the git push --set-upstream option needs to be used to track changes from the origin repository on Alioth:

git push origin jessie-backports --set-upstream

Plain git push is sufficient when the backports branch was checked out from the origin repository on Alioth:

git push

Depending on how the local git repository was created, the protocol for git pushes may need to be changed to ssh, and the host to git.debian.org, because the anonscm.debian.org host only provides read-only services:

git remote set-url --push origin ssh://<username>@git.debian.org/git/pkg-grass/<package>.git

The <username> doesn't have to be specified if the appropriate username is configured in ~/.ssh/config as documented in the SSH tips section.

After pushing the changes for the backport to the repostitory on Alioth, continue to upload the package and tag the release.

Uploading a backport

Only Debian Developers and Debian Maintainers who have been added to the backports ACL can upload backported packages to the Debian archive.

Folllow the instructions on the Debian Backports website to request addition to the backports ACL, or request sponsorship from a DD in the team who is included in the backports ACL already.

Beside the ACL restriction, uploading a backport is not very different from uploading a new package release.

The appropriate distribution and urgency are already set by dch --bpo, leaving only the need to sign the .changes file and upload it to ftp-master.

debsign ../<package>_<version>_<architecture>.changes
dput ../<package>_<version>_<architecture>.changes

For UbuntuGIS and OSGeo-Live the appropriate distribution should be set before the final build as documented in the Building a backport section.

Uploads to Launchpad also need to specify the appropriate PPA in the dput command:

dput ppa:your-lp-id/ppa ../<package>_<version>_<architecture>.changes

Refer to the Uploading a package to a PPA documentation on Launchpad for more information.

After uploading the changes for the backport don't forget to tag the last commit and push the changes to the git repository on Alioth.

Tagging a backport

Tagging a backport is also not very different from tagging a regular release.

Use debcommit to create the tag from the version in debian/changelog and push the tag to the git repository on Alioth.

debcommit -r
git push --tags

If the build modified the working directory, those modifications need to be reverted before the release can be tagged.

Backports for UbuntuGIS and OSGeo-Live should use their respective tag prefixes instead:

# UbuntuGIS
git tag ubuntu/$(dpkg-parsechangelog -SVersion | sed 's/~/./g; s/^[0-9]*://')
git push --tags

# OSGeo-Live
git tag osgeo/$(dpkg-parsechangelog -SVersion | sed 's/~/./g; s/^[0-9]*://')
git push --tags

Because the tilde is not a valid character in tags, all occurrences in the package version need to replaced by dots as debcommit does too, and the optional epoch needs to be excluded if present.

Refer to the Tags for upstream and package releases section for some examples of the tagging convention for derivatives.

Importing source packages

Sometimes changes from published source packages need to be included in the git repository, e.g. NMUs or packages from UbuntuGIS or OSGeo-Live that don't have their dedicated branches yet.

First download the source package with dget using the URL to the .dsc file copied from the Debian Package Tracker or Launchpad:

cd /tmp
dget -u -d http://example.com/<package>_<revision>.dsc

The -d option is used to only download the source package files, and not extract them as well.

Change the current working directory to the package git repository and ensure the approriate branch is checked out and up-to-date.

cd <path/to/git/repository>
git checkout <branch>
git pull

Assuming an NMU from the Debian archive is imported on the master branch, using the gbp import-dsc defaults is sufficient:

gbp import-dsc /tmp/<package>_<revision>.dsc

When importing source packages from UbuntuGIS or OSGeo-Live the appropriate branches and tags need to be used.

You may also need to create the branch first if it does not exist yet and the package doesn't originate from UbuntuGIS or OSGeo-Live.

Create the branch by checking out the debian/ tag on which the UbuntuGIS or OSGeo-Live package is based:

git checkout -b ubuntu/xenial debian/1.2.3-1
git checkout -b osgeo/10.0 debian/1.2.3-1

Because the debian/gbp.conf file may not have the appropriate configuration yet, the Ubuntu or OSGeo-Live specific branches and tags need to be specified explicitly:

gbp import-dsc --debian-branch=ubuntu/xenial --debian-tag="ubuntu/%(version)s" /tmp/<package>_<revision>.dsc
gbp import-dsc --debian-branch=osgeo/10.0 --debian-tag="osgeo/%(version)s" /tmp/<package>_<revision>.dsc

Patches

quilt does a fine job managing patches, especially if using the 3.0 (quilt) source format. Refer to the Handling patches section for a guide.

gbp-pq can be used for treating the patches as a series of commits, see: Keeping debian/patches on a patch-queue branch

Commit policy

Single change per commit

This is true for any VCS, but it won't hurt saying it again: please include only one change in each commit.

git-gui's and git add -p's ability to stage single lines (or hunks) is a huge help if you have done several unrelated changes in the sources.

Changelog maintenance

Some prefer to update debian/changelog with each commit, while others prefer to do that only at release time by using gbp dch.

The current group policy states that whenever you stop working on a package, the changelog should be updated and pushed.

That is, either include the changelog entry with each commit using dch, or finish your work by updating the changelog, e.g. using gbp dch.

Removing packages

To remove packages from the archive follow the procedure as documented in the Debian Developer's Reference: Removing packages

Following the archive removal request, the packages should be removed from the Blend Tasks.

The git repositories for the packages on Alioth don't need to be removed, and can be kept for historic reference.

Tips & tricks

Set the devscripts variables DEBEMAIL and DEBFULLNAME

debcheckout will then set git's options user.email and user.name accordingly.

Setting the gpg key for signing git tags

To ensure the correct gpg key is used when signing git tags: git config --global user.signingkey yourkeyID

Configure Git to commit using your packager name and address

The --global option is to say Git these are the default parameters for every Git repository you commit to, without it the settings will be per-repository only:

git config [--global] user.name "$DEBFULLNAME"
git config [--global] user.email "$DEBEMAIL"

To track extra remote branches, simply check them out

With recent versions of git, the remote branch will be automatically tracked when running git checkout.

For example, when a pristine-tar branch is available upstream and not yet tracked locally, the command git checkout pristine-tar will implicitly run the command git branch -t pristine-tar origin/pristine-tar.

To change the default branch

If the Debian work is not on the master branch, change the default branch by editing the HEAD file in the bare repository on Alioth, and replace master by the name of the new default branch. For a branch called debian/unstable the contents of the file will be refs/heads/debian/unstable.

If upstream manages his sources with Git

The following makefile script can help producing a version number when no Git tag is available:

SOURCEPKG=$(shell dpkg-parsechangelog | sed -n 's/^Source: \(.*\)/\1/p')
UPSTREAM=$(shell dpkg-parsechangelog | sed -n 's/^Version: \(.*\)-[^-]*/\1/p')
SHA1=$(lastword $(subst ~g, ,$(UPSTREAM)))
ORIG=${SOURCEPKG}_${UPSTREAM}.orig.tar.gz

describe-current-version:
	git describe --tags upstream | sed 's,^release-,,;s,-,+,;s,-,~,;'

get-orig-source:
	git archive --format=tar $(SHA1) | gzip -9 > ../$(ORIG)

Packaging with Subversion

Subversion was used in the past to maintain the source packages, but (almost) all packages have since moved to Git. Refer to the status of migrations on the Debian Wiki for details.

The old Subversion repositories are still available on svn.debian.org, and can viewed using the ViewVC web interface.

Subversion tips

Suggested aliases for svn-buildpackage:

alias svn-b='svn-buildpackage -us -uc --svn-ignore'
alias svn-br='svn-b --svn-dont-purge --svn-reuse'
alias svn-bt='svn-buildpackage --svn-tag'

svn-inject -o sets up the mergeWithUpstream property for the SVN directories where packages are stored. In case svn-inject was not used, you can do it by hand with the command:

svn propset mergeWithUpstream 1 debian

To download the upstream sources (if there is a debian/watch file):

echo "origDir=.." >> .svn/deb-layout && uscan --force-download

Alternatively, you can try:

make -f debian/rules get-orig-source

If you're a Debian Developer or a member of the pkg-grass group on Alioth, you can commit your changes: svn commit (or svn ci). Otherwise, you can ask to be added to the group (see the Membership section), or send the result of svn diff to the mailing list (gzip -9 it, if it's too large).

It may happen that a package version has been uploaded to Debian repositories, and you forgot to tag the last build with svn-buildpackage --svn-tag. You can tag this package also retroactively. A first step, creating the tags directory, can be achieved in two ways: either create it locally as sibling of trunk/ with svn mkdir tags, and commit with svn commit, or create it remotely with svn mkdir svn+ssh://<user>@svn.debian.org/svn/pkg-grass/packages/<package>/tags. After the tags directory has been created, you're ready to tag the package: svn-buildpackage --svn-tag-only --svn-no-autodch. The --svn-no-autodch avoids debian/changelog to be marked as UNRELEASED.

Here is an example session where a package is prepared manually:

# Check out pkg-grass, cd to pkg-grass/packages
# Create new project folder with
svn mkdir projectname
svn mkdir projectname/trunk

# Put orig.tar.gz in place
mv some_version.orig.tar.gz projectname

# Inform svn-buildpackage about the location of the orig.tar.gz
echo "origDir=.." > projectname/trunk/.svn/deb-layout

# Untar source tree for development
cd projectname
tar xzvf some_version.orig.tar.gz
cd some-version # entering the unpackaged source tree
if [ ! -d debian ]; then dh_make ; fi
mv debian ../trunk
ln -s ../trunk/debian .

# continue development
fakeroot ./debian/rules binary

# until it works, finally
cd ..

# debian directory is the only thing that is stored in svn, to be merged with upstream svn propset merge with upstream
svn propset mergeWithUpstream 1 trunk/debian

# See if things can be compiled via svn-buildpackage
cd trunk
svn-buildpackage -uc -us

# check build
lintian ../build-area/*changes

Backports

Debian offers backports of newer package versions for its stable (and oldstable) release via backports.debian.org.

Backports of Debian GIS packages should be kept as branches in the package Git repository (e.g. wheezy-backports, jessie-backports, etc.).

To upload backports DDs (and DMs for their packages) need to be added to the backports ACL, and follow the Basic Rules as documented in Debian Backports ›› Contribute on the Backports website.

The workflow for packaging backports is documented in more detail in the Backports with Git section.

PPA for Ubuntu by UbuntuGIS

The UbuntuGIS team maintains Personal Package Archives (PPA) on Launchpad, where packages are backported for Ubuntu.

Please keep in mind issues like the possibility to upgrade to the next Ubuntu stable release. Packages that are backports can be made inferior in version by using a tilde. If the package contains additional development, a version number without the tilde will make it higher, but not as high as the next Debian revision. For example:

  2.12.0-1~natty1 (backport in PPA)
< 2.12.0-1        (from Debian in Ubuntu)
< 2.12.0-1natty1  (in PPA, containing additions)
< 2.12.0-2        (from Debian in Ubuntu).

Packages sent to the UbuntuGIS PPAs may be kept as branches in our repositories.

The workflow for packaging backports for the UbuntuGIS PPA is documented in more detail in the Backports with Git section.

Lintian checks are adapted to Ubuntu by setting the environment as follows: LINTIAN_PROFILE=ubuntu.

Derivatives working together with Debian GIS

Debian GIS is proud that derivatives (like for instance UbuntuGIS and OSGeo-Live) are profiting from our work inside Debian and we try to establish strong connections to these derivatives. With UbuntuGIS the connection is as strong that a common work flow was created where UbuntuGIS developers are injecting their packaging straight into the Debian GIS version control system. To make sure that there will be no conflicts with the Debian revisions some attention should be paid to the revision numbering. If the derivative is creating a new package (either from scratch or an upgraded version) it should get the version <upstreamversion>-0<derivativename><derivativerevision> (which is the versioning scheme usually used by Ubuntu).

Packages for derivatives may be kept as branches in our repositories.

The workflow for packaging backports for derivatives like OSGeo-Live is documented in more detail in the Backports with Git section.

R packages

GNU R sometimes introduces backward incompatibilities, so the current practice is to make packages depend on versions equal or higher to the one against which they were built. When using r-base-dev, this can be achieved by adding the substitution variable ${R:Depends} in the Depends field of the binary package.

Sponsorship

There are several Debian Developers in the Debian GIS team, unfortunately they are very busy and may not respond to requests for sponsorship sent to the Debian GIS Developers Mailing List. It is therefore recommended to follow the normal process in Debian and file a Request For Sponsorship (RFS) bugreport. The Debian Mentors website is the best place to upload your package to attract sponsors, the website also provides a template for your RFS bugreport.

The RFS bugreport should also be copied to the Debian GIS Developers Mailing List. The best way to do this is to use the X-Debbugs-CC header in the bugreport. Add X-Debbugs-CC: pkg-grass-devel@lists.alioth.debian.org to your message's mail header, or use the s option in the reportbug utility.

As Debian GIS is a Pure Blend, a good way to get sponsorship is to use Andreas Tille's Sponsoring of Blends (SoB) initiative. If you cannot find a sponsor in the Debian GIS team, you can add a new entry for your package to the SoB wiki page to request sponsorship via the SoB initiative, assuming the conditions documented on the SoB wiki page are met.