Policy

debian/control
Config::Model
debian/copyright
debian/changelog
debian/upstream
debian/gbp.conf
debian/README.source
debian/README.test
debian/source/format
debian/source/option
debian/compat
Debhelper
CDBS
Version control systems
Source package stored in a Git repository
Source package stored in a Subversion repository
Tags
New package
The Debian GIS Blend tasks
Building and tagging the packages
Handling patches
Using quilt
Using dpatch
Contributing to the GIS Policy

debian/control

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

  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://anonscm.debian.org/cgit/pkg-grass/<package>.git/
    Vcs-Git: https://anonscm.debian.org/git/pkg-grass/<package>.git
    

    or

    Vcs-Browser: https://anonscm.debian.org/viewvc/pkg-grass/packages/<package>/trunk/
    Vcs-Svn: svn://anonscm.debian.org/pkg-grass/packages/<package>/trunk/
    

Config::Model

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 libconfig-model-perl 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 libconfig-model-dpkg-perl libconfig-model-perl
# Install libconfig-model-itself-perl for a graphical model editor
apt-get install libconfig-model-itself-perl

cme check dpkg-control
cme fix dpkg-control

Caution

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.

debian/copyright

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 --copyright -r * | /usr/lib/cdbs/licensecheck2dep5 > 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).

debian/changelog

Packages hosted in our Git or Subversion 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.

debian/upstream

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.

debian/gbp.conf

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

debian/README.source

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,…

debian/README.test

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

debian/source/format

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

3.0 (quilt)

debian/source/option

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.

debian/compat

Should normally contain 9. This debhelper compatibility level is recommended for its improved support of hardening buildflags and Multi-Arch.

9

Debhelper

Debhelper uses compatibility levels to control the behavior of its commands. We currently recommend to use the level 9 which is available in current stable (Wheezy) and backported to oldstable. However, there is no urgent need to touch packages only because it has an older Debhelper version.

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.

CDBS

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 mostly use Git, but some packages still use Subversion.

Source package stored in a Git repository

Git repositories should be stored in the /git/pkg-grass directory on Alioth and created with the setup-repository script available there. On Alioth write access must be given to the pkg-grass group and all the Debian Developers, with appropriate Unix permissions (including SGID bit on directories) and ACLs. See /git/pkg-grass itself as an example. setup-repository does this automatically.

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.

Source package stored in a Subversion repository

We often use the mergeWithUpstream work flow. In that case, please keep all the modifications in the debian directory, and use the -o option of svn-buildpackage, as in the following example:

svn-inject -o package.dsc svn+ssh://svn.debian.org/svn/pkg-grass/packages/.

Tags

Tags indicate the revision corresponding to uploaded packages. For Subversion, the version number is used, and for Git, debian/ is added before the version number. In the Subversion repository, older tags may be deleted to save space.

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 or Subversion 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:

QUILT_DIFF_ARGS="--no-timestamps --no-index"
QUILT_REFRESH_ARGS="--no-timestamps --no-index"
QUILT_PATCHES="debian/patches"

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.

Tip

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

Note

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.

Caution

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
clean-patched:
...

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.

Using dpatch

Removal of dpatch is planned for 2017. The commands below are for reference, but the use of dpatch in Debian GIS is discouraged. The quilt package contains a conversion script, /usr/share/doc/quilt/examples/dpatch2quilt.sh.

  • Creating a patch: dpatch-edit-patch

  • Applying and unapplying patches: apply(-all), unapply(-all), status

  • Editing patches: dpatch-edit-patch

  • Renaming patches: is this possible?

  • Other commands: please see man 1 dpatch for a comprehensive list of commands.

  • Integration in the build process: follow the instructions for quilt and adapt the path of inclusion to /usr/share/dpatch/dpatch.make

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 --user <username> git://git.debian.org/pkg-grass/website.git --git-track '*'

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 it's highly recommended to run make which will validate the XML syntax using xmllint before generating the HTML. Make sure you have the xsltproc package installed for the 'make' command not to fail.

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

Run the git status command to check if there are any stray files. If there are none, update the policy online (which is included in pkg-grass website on Alioth) using make publish. This will rsync the current working directory to the team webspace on Alioth and fix the group permissions. There are currently problems with the icons directory on Alioth (which is owned by frankie) but this does not cause problems for normal updates.