Debian Mono Group Policy

David Paleino

Initial writing  

$ policy.xml rev. 4096 - Thu, 16 Sep 2010 20:52:34 +0000 (meebey) $


Table of Contents

Introduction
How to Contribute
Membership
Essential readings
Subversion
Give me the source!
Repository structure
Packaging
Announcing intent to package
Policy
debian/control
debian/copyright
debian/changelog
Debhelper
CDBS
Injecting a new package
Building the packages
Tagging packages
Handling patches

Introduction

This group is, together with <tt>pkg-cli-apps</tt> and <tt>pkg-cli-libs</tt>, meant to coordinate packaging work on Mono (CLI/.NET platform), MonoDoc, Gtk# and other CLI application/library packages.

How to Contribute

Please contact us on pkg-mono-devel@lists.aliothdebian.org, or #debian-mono on OFTC, if you want to help us. Please read the Membership section if you're interested in joining us.

If you speak a language other than English, you can contribute rightaway with translations of package descriptions at ddtp.debian.org.

When working on these, you will find immediate targets for improvements of the original English versions, too. For these, though, you need access to our source code repositories.

Membership

To request membership to this group, please go on our Alioth pages:

  • pkg-mono, if you want to hack on the general Mono framework;

  • pkg-cli-apps, if you want to host a CLI application with us;

  • pkg-cli-libs, if you want to host a CLI library with us.

Remember that you must have an Alioth account before requesting membership (see here to request an Alioth account).

Essential readings

Subversion

Our Subversion (SVN) repository is currently hosted on Alioth, the hosting facility provided by Debian to free software developers. You can have a look at the repository through Alioth's web interfaces:

Give me the source!

To check sources out from SVN, please do:

  • If you are a member of our teams (or a Debian developer, for pkg-cli-apps and pkg-cli-libs), you have write permission (adjust the URL properly):

    svn co svn+ssh://user@alioth.debian.org/svn/<group>/...

  • For read-only access, the syntax is slightly different:

    svn co svn://svn.debian.org/svn/<group>/...

Another way to check the sources is through the use of the debcheckout command, from the devscripts package.

Repository structure

The SVN repositories are structured as follows:



pkg-mono/
 ├ <package A>/
 │  ├ branches/
 │  ├ tags/
 │  └ trunk/
 │    └ debian/
 ├ <package B>/
 │  ├ branches/
 │  ├ tags/
 │  └ trunk/
 │     └ debian/
 ├ …
 │
 ├ scripts/
 └ web/
pkg-cli-apps/
 └ packages/
    ├<package A>/
    │  ├ branches/
    │  ├ tags/
    │  └ trunk/
    │    └ debian/
    ├ <package B>/
    │  ├ branches/
    │  ├ tags/
    │  └ trunk/
    │     └ debian/
    └ …
pkg-cli-libs/
 └ packages/
    ├<package A>/
    │  ├ branches/
    │  ├ tags/
    │  └ trunk/
    │    └ debian/
    ├ <package B>/
    │  ├ branches/
    │  ├ tags/
    │  └ trunk/
    │     └ debian/
    └ …

Packaging

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 mailing list pkg-mono-devel@lists.aliothdebian.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, when the ITP bug is automatically closed one year later.

Policy

debian/control

  1. Section. Should be appropriate to the kind of package.

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

  3. Maintainer. Maintainer should be Debian Mono Group , Debian CLI Applications Team or Debian CLI Libraries Team , according to where your package resides. Please subscribe to our mailing list if you list yourself in the Uploaders: field of one of our packages. You can refer to our QA pages (pkg-mono, pkg-cli-apps, pkg-cli-libs) to gather information about the packages.

  4. Upload by Debian Maintainers. Should be enabled with the field DM-Upload-Allowed: yes. This means that when an Uploader becomes Debian Maintainer, he will immediately get the possibility to upload the package to Debian. Please consider this when you sponsor packages in which some Uploaders are added.

  5. 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. It is totally acceptable to do some QA work on a package without adding oneself to the Uploaders field.

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

  7. Homepage. should be documented whenever possible

  8. Vcs-Svn: and Vcs-Browser: Please use the following template:

    Vcs-Svn: svn://svn.debian.org/svn/<group>/.../trunk/
    Vcs-Browser: http://svn.debian.org/wsvn/<group>/.../<package>/trunk/?rev=0&sc=0
    					

debian/copyright

We use the proposed machine-readable format for the debian/copyright 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”.

debian/changelog

Packages hosted in our Subversion repositories, 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.

Also, the first-level indentation is represented by a *. The second-level indentation starts with a +, while the third-level with a -. The indentation must be of two spaces to the right with regard to the level just above.

Debhelper

Debhelper uses compatibility levels to control the behaviour of its commands. The latest level is not always available in Stable or Backports. Please avoid using it unless needed until it is available, to facilitate backporting. We currently recommend to use the level 6.

CDBS

The use of CDBS is welcome as it helps us to factorize our code. Nevertheless, please do not use complex CDBS for non-trivial packages, so that other developers can quickly understand the package when doing QA work.

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

Injecting a new package

To inject a new package to the SVN repositories, you must have write access to it; i.e. you must be a member of pkg-mono, pkg-cli-apps or pkg-cli-libs groups on Alioth.

You can inject a new package only after successfully building it with dpkg-buildpackage (or any wrapper around it). We use the MergeWithUpstream workflow, so please keep all the modifications in the debian directory, and use the -o of svn-buildpackage, as in the following example:

svn-inject -o package.dsc svn+ssh://user@alioth.debian.org/svn/<group>/.../

(the ... used in the URL above should be the parent directory of where other <package> directories are: that is: / for pkg-mono, and packages/ for pkg-cli-apps and pkg-cli-libs).

The svn-inject command is found in the svn-buildpackage package (just apt-get it).

Building the packages

To build the package, just use the tools that svn-buildpackage carries. First of all, we suggest you to define some aliases for the most common commands:

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

Checkout the sources (see the proper section).

Once done, you're ready to do the work. First, cd to the trunk directory, and download the upstream sources (if there is a debian/watch file):

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

Alternatively, you can try this, it depends on how the package was built (again, from the trunk/ directory):

debian/rules get-orig-source

Once done, edit the files you need, and then build the package with svn-b or svn-br.

If you're a team member, you can commit your changes:

svn commit

(also 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).

Tagging packages

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:

  • create it locally (it is a sibling of trunk/), and commit:

    svn mkdir tags

    svn commit

  • create it remotely:

    svn mkdir svn+ssh://user@svn.debian.org/svn/<group>/.../<package>/tags

After the tags directory has been created, you're ready to tag the package:

svn-buildpackage --svn-tag-only --svn-no-autodch

(--svn-no-autodch avoids debian/changelog to be marked as UNRELEASED).

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 upstream's source files, your changes will be put into a .diff.gz file, which should instead contain only debian. To better organise the patches and group the by function, please use a patch handling system which keeps patches under the debian/patches directory.

The most known are quilt, simple-patchsys (from the CDBS package) and dpatch. Please don't use any other patch system in our team, 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_PATCH_OPTS="--unified-reject-files"
QUILT_PATCHES="debian/patches"

After this, you're ready to start working with quilt.

Creating a patch

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

quilt new <patch_name>.patch

This will create (if it doesn't exist yet) a debian/patches/series file, 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

Just two easy commands to do the job:

  • quilt pop will unapply the topmost patch.

  • quilt push will apply the next patch in debian/patches/series.

You can just add a "-a" flag to the commands above, to respectively apply/unapply all patches in the series.

Tip

You can check which patches are applied/unapplied with, respectively, quilt applied and quilt unapplied.

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.

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

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: $(QUILT_STAMPFN) 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 flag of make).

Now add a dependency to the clean target:

...
clean: unpatch
...

If you've also patched the build system, using upstream's 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

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