Version control systems
Source package stored in a Git repository
New package
The Debian GIS Blend tasks
Building and tagging the packages
Handling patches
Using quilt
Contributing to the GIS Policy


  1. Section.  Should be science for the source package.

    Section: science

  2. Priority.  Should be optional unless forbidden by the Debian policy (see §2.5). Packages of priority extra are excluded from some QA tests.

    Priority: optional

  3. Maintainer.  Maintainer should be Debian GIS Project . Please subscribe to this list if you list yourself in the Uploaders: field of one of Debian GIS's packages. You can refer to the QA page corresponding to this email to gather information about the packages.

    Maintainer: Debian GIS Project <pkg-grass-devel@lists.alioth.debian.org>

  4. Uploaders.  Please add yourself as an uploader when you have a significant interest in a package. Being Uploader means that you are expected to answer to the bug reports. For more occasional works, you can do a team upload with dch --team.

    Uploaders: John Doe <johndoe@example.com>,
               Your Name <yourname@example.com>

  5. Standards-Version.  Please always use the latest unless there are concerns for backporting. If no changes are needed, please indicate this fact in the changelog, and increment the value of the field.

    Standards-Version: 4.6.1

  6. Homepage.  Should be documented whenever possible.

    Homepage: https://www.example.com/

  7. Vcs-Git and Vcs-Browser.  Please use the following templates, and refer to the Debian Policy § 5.6.26 for details:

    Vcs-Browser: https://salsa.debian.org/debian-gis-team/<package>
    Vcs-Git: https://salsa.debian.org/debian-gis-team/<package>.git


It is a very good idea to use Config::Model to unify the formatting of debian/control.

To do so make sure you have installed cme and libconfig-model-dpkg-perl and then you can simply call cme fix dpkg-control to get a properly formatted, sanity checked debian/control file.

Please note that sometimes you need to call this more than once.

apt-get install cme libconfig-model-dpkg-perl
# Install libconfig-model-tkui-perl for a graphical model editor
apt-get install libconfig-model-tkui-perl

cme check dpkg-control
cme fix dpkg-control


cme fix will bump the Standards-Version if it's lower than the built-in default.

Before bumping the Standards-Version you should check the Policy checklist for upgrading your packages for relevant changes and update the package accordingly.


We use the machine-readable format for the debian/copyright file.

The Source field does not need to contain the full URL to the particular version that is being packaged, since this can be determined by the uscan program with the debian/watch file.

Please list yourself in the Files: debian/* section if you think that your contributions are not trivial and therefore subjected to copyright. Please chose a license that is compatible with the program you package. You can also use same as if it were in the public domain or same as the packaged program itself.

To create some reasonable skeleton for a debian/copyright file you can try the following:

sudo apt-get install devscripts cdbs
licensecheck --deb-machine -r * > debian/copyright

To verify the correct syntax of the debian/copyright file you can use:

cme check dpkg-copyright
cme fix dpkg-copyright


config-edit -application dpkg-copyright -ui none

from package libconfig-model-dpkg-perl (see Config::Model above).


Packages hosted in our Git repository, that have been modified but not uploaded must use UNRELEASED as a distribution name.

This can be done automatically by declaring DEBCHANGE_RELEASE_HEURISTIC=changelog in ~/.devscripts and using dch.


We use the bibliographic information which should be stored in the file debian/upstream. The purpose of specifying this is to enhance the contact to upstream which thus gets an extra reward of their work if their citations show up on pages inside the Debian domain and if users more popularly are asked to cite upstream when working with the program in question.


Include this file to document the layout of the repository. Packages managed with git-buildpackage may omit default values.


# The default name for the upstream branch is "upstream".
# Change it if the name is different (for instance, "master").
upstream-branch = upstream

# The default name for the Debian branch is "master".
# Change it if the name is different (for instance, "debian/unstable").
debian-branch = master

# gbp import-orig uses the following names for the upstream tags.
# Change the value if you are not using gbp import-orig
upstream-tag = upstream/%(version)s

# Always use pristine-tar.
pristine-tar = True

pbuilder-options = --source-only-changes


This file is recommended by the Policy (§ 4.14) from version 3.8.0 for documenting source package handling. Please follow the recommendation. For instance, this file is needed when we use a patch system, when the upstream sources are in another format than gzipped tar archive, when we repack the sources,…


This file was (recommended by the Security team) for describing to others than the regular maintainer how the package functionality can properly be tested.


This file should contain 3.0 (quilt). Other formats should be avoided unless they bring a specific advantage.

3.0 (quilt)


For packages not using quilt patches, for example when committing changes directly to the Debian branch, this file should contain single-debian-patch in order to emulate the 1.0 format. This is better than using the 1.0 format directly because the 3.0 (quilt) format brings other advantages, in particular the conservation of file permissions in the debian directory.


Should no longer be used, use debhelper-compat (= <version>) build dependency instead.


Debhelper uses compatibility levels to control the behavior of its commands. We currently recommend to use the level 13 which is available in current stable (bookworm). It is also backported to Ubuntu focal.

It is strongly recommended to use the short dh notation in debian/rules files which makes code factorization very simple and easy to understand the packaging for other members of the team. Even complex packaging becomes quite transparent this way.


Before the short dh notation of debhelper existed CDBS was the only way to factorize code in debian/rules files. We would like to standardize on dh when both provide similar comfort. Please give it priority for new packages. It is also possible to switch to dh for existing packages, but this is entirely at the packagers discretion.

It is technically possible to build CDBS packages using Debhelper without the debian/compat file. Please do not, and always include such a file according to the above Debhelper guidelines.

Version control systems

We use Git repositories these days, in the past Subversion was used.

Source package stored in a Git repository

Git repositories should be stored in the debian-gis-team namespace on Salsa and created with the salsa-create-repository.pl script available in the scripts repository.

Git repositories managed with a helper tool should announce it. For instance, to show that git-buildpackage is used, the package can contain a configuration file in debian/gbp.conf.


Tags indicate the revision corresponding to uploaded packages. For Git debian/ is added before the version number.

New package

Try to inject a new package only after successfully building it with dpkg-buildpackage (or any wrapper around it). Use a file like debian/DRAFT to mention when the package is a draft.

The Debian GIS Blend tasks

Once you injected a new package please make sure that it is mentioned in the appropriate tasks file in the source of the debian-gis Blend package. Some team members watch the changes in the Debian GIS packaging pool but it helps if the maintainer of a new package verifies that everything is in the right place.

Building and tagging the packages

We prefer that uploaded packages are built in a chroot, to provide similar build environment to the whole team. After upload, please tag the Git repository.

Handling patches

Often happens that the upstream code doesn't fit well into the Debian distribution: be this wrong paths, missing features, anything that implies editing the source files. When you directly edit upstreams source files, your changes will be put into a .diff.gz file if you use the 1.0 source format and in a monolithic patch if you use the 3.0 (quilt) format. To better organize the patches and group the by function, please use a patch handling system which keeps patches under the debian/patches/ directory.

The 3.0 (quilt) dpkg source format provides its own patch system. Apart from this, the most popular is quilt. simple-patchsys, from the CDBS package, is deprecated since version 0.4.85. dpatch has been popular as well, but is not compatible with the 3.0 (quilt) source format and is planned to be removed 2017. Please don't use any other patch system in Debian GIS, unless absolutely necessary.

Using quilt

Using quilt is rather easy.

First, make sure you have correctly setup quilt: open .quiltrc in your home directory (create it if you don't have one), and make sure it looks like this:

# For debian packages
for where in ./ ../ ../../ ../../../ ../../../../ ../../../../../; do
        if [ -e ${where}debian/rules -a -d ${where}debian/patches ]; then
                export QUILT_PATCHES=debian/patches
                export QUILT_PUSH_ARGS="--color=auto"
                export QUILT_DIFF_ARGS="--no-timestamps --no-index -p ab --color=auto"
                export QUILT_REFRESH_ARGS="--no-timestamps --no-index -p ab"
                export QUILT_DIFF_OPTS='-p'

After this, you're ready to start working with quilt. See also the instructions in the New Maintainer's Guide.

Creating a patch

To create a patch, use the new command. Run:

quilt new <patch_name>.patch

This will create a debian/patches/series file (if it doesn't exist yet), which contains all the patches to be applied by quilt. Moreover, the new patch is also the topmost (the currently applied).

Now start editing files, with:

quilt edit <file>

And repeat the process for each file the patch is involved with. At the end, run:

quilt refresh

This will compare the noted state of the edited files with the current state, and will produce a patch in debian/patches. Remember: the patch is currently applied (you can check this with quilt applied).

Applying and unapplying patches

To apply the next patch in debian/patches/series:

quilt push

To unapply the topmost patch:

quilt pop

You can just add the -a option to the commands above, to respectively apply and unapply all patches in the series.


You can check which patches are applied with:

quilt applied

And which are unapplied:

quilt unapplied

To check which patch is next in debian/patches/series to be applied:

quilt next

And which is next to be unapplied:

quilt prev

Editing patches

To edit a patch, first make it the topmost:

quilt push <patch_name>

If the patch is already applied, but is not the topmost, run

quilt pop

until it becomes the currently applied one.

You can now run

quilt edit

on the files you want to change, and, when you're done:

quilt refresh

to update the patch with your changes.

Renaming patches

Sometimes it's useful to rename a patch. Without any hassle, do:

quilt rename -P <old_name>.patch <new_name>.patch

Other commands

Please see man 1 quilt to have a comprehensive list of commands.

Integration in the build process


Please note that the 3.0 (quilt) source version uses quilt automatically, the following instructions are deprecated but can be encountered in oldstable packages.

Add in the very first part of debian/rules (i.e. before the targets), the line:

include /usr/share/quilt/quilt.make

Please use this to import patch and unpatch rules instead of writing them, and remember to add the needed dependencies to its targets:

build:patch build-stamp
build-stamp: configure

This kind of dependency will ensure that if you also patch the build system, you get a working patched build process.


Don't also put configure as a dependency of build (leave it in build-stamp): that may cause problems during parallel buildings (i.e. the -j option of make).

Now add a dependency to the clean target:

clean: unpatch

If you've also patched the build system, using upstreams clean target might fail. This is what you should do:

clean: clean-patched unpatch

Obviously, you could always use an approach like this, but it's an useless complication if you don't patch the build system, and you should keep debian/rules the simplest you can.

Contributing to the GIS Policy

As a member of the Debian GIS Team you will be able to commit modifications to this policy. It would be wise to state your intentions on debian-gis@lists.debian.org first, and make sure there is general agreement on the proposed changes.

The source for the Debian GIS Policy can be downloaded from the same repository as all the GIS packages:

debcheckout --git-track '*' https://salsa.debian.org/debian-gis-team/debian-gis-team.pages.debian.net.git

To update the policy, you need to edit the policy.xml file. The website uses the Docbook XML syntax. If you copy the style used in the rest of the document, you will probably have no problems. Further information about the Docbook XML syntax can be found documented on the Docbook website.

The policy in particular makes use of <programlisting>, <command>, <option> tags, and lists package names using <literal> tags.

The maximum length of paragraph content is 80 characters, and XML children are indented with 2 spaces.

After making changes to the policy.xml file you must run make which will validate the XML syntax using xmllint before generating the HTML. Make sure you have the xsltproc, docbook-xsl & codespell packages installed for the 'make' command not to fail.

If there are no errors, commit your changes and push them to the Salsa git repository. Alternatively, create a patch and send it to the debian-gis@lists.debian.org mailing list for comments.

The generated HTML must be committed in the repository along with the policy.xml changes, because the HTML is not generated by the GitLab Pipeline.

It's highly recommended to configure a pre-commit hook, which generates the HTML for every commit:

cat > .git/hooks/pre-commit <<EOF

set -e

if [ -z "${GIT_DIR}" ]; then
    echo "GIT_DIR not set" 1>&2
    exit 1

exec 1>&2

echo "Running make to generate HTML"
chmod 755 .git/hooks/pre-commit

If the hook succeeded the commit must be amended to also include the generated HTML:

git commit --amend -a