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

or

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.

[DEFAULT]

# 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

[buildpackage]
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.

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

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.

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.

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.

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.

# 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'
                break
        fi
done

quilt new <patch_name>.patch

quilt edit <file>

quilt refresh

quilt push

quilt pop

quilt applied

quilt unapplied

quilt next

quilt prev

quilt push <patch_name>

quilt pop

quilt edit

quilt refresh

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

include /usr/share/quilt/quilt.make

...
build:patch build-stamp
build-stamp: configure
...

...
clean: unpatch
...

...
clean: clean-patched unpatch
clean-patched:
...

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
#!/bin/sh

set -e

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

exec 1>&2

echo "Running make to generate HTML"
make
EOF
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