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

Defaults! PBUILDERS setenv

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

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

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

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

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

git-pbuilder create

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

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

HOOKDIR="/var/cache/pbuilder/hook.d/"

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

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

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 https://salsa.debian.org/debian-gis-team/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:

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.

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://salsa.debian.org/debian-gis-team/<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 ubuntugis/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 salsa.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.

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>

quilt push && quilt refresh

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

quilt push -f && quilt refresh

quilt edit <file>
quilt refresh

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

git diff upstream~1 upstream

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

licensecheck --deb-machine -r * > debian/copyright.new
diff -u debian/copyright debian/copyright.new

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 bookworm-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 override 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 overridden 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 bookworm distribution and the bookworm-backports branch to build a backport. Or using both the bookworm 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.

Before pushing your packaging changes to salsa.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 Salsa.

git clone https://salsa.debian.org/debian-gis-team/scripts.git
cd scripts
apt-get install libjson-perl libwww-perl
./salsa-create-repository.pl -v -t <token> -p <package>

chmod 600 $HOME/.salsa-token

git remote add origin https://salsa.debian.org/debian-gis-team/<package>.git
git remote set-url --push origin git@salsa.debian.org:debian-gis-team/<package>.git

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

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.

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

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

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

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

debcommit -r

git tag <distribution>/<package_version>

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

git push --tags

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

git checkout -b bookworm-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 = bookworm-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 bookworm-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 -a "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.

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

git checkout bookworm-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 related 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

The procedure to build a backport is nearly identical 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=bookworm -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=bookworm-backports -v1.2.0-1

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

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.

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

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

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"

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"

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 Salsa:

git push origin bookworm-backports --set-upstream

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

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 salsa.debian.org, because the anonscm.debian.org host only provides read-only services:

git remote set-url --push origin git@salsa.debian.org:debian-gis-team/<package>.git

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

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

Follow 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 Salsa.

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 Salsa.

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 ubuntugis/$(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.

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.

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.

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

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

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"

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.

If the Debian work is not on the master branch, change the default branch by editing the project settings and select the appropriate Default Branch.

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)