Debian Perl Group Subversion Guide

Note: This documentation is deprecated now. The Debian Perl Group uses now git repositories to maintain the packages. See: http://pkg-perl.alioth.debian.org/git.html

This guide describes the procedures that the Debian Perl Group developers use to upload packages to the Subversion (SVN) repository Debian provides to them.

It will describe how to upload an initial package, how to update the packages, how to build them and how to upgrade them.

This is a work in progress. Please send any comments or ideas to <debian-perl@lists.debian.org>.


1. The Tools

This section will describe what tools are available and what they do.

Most of the tools you will be using will come from either the svn-buildpackage or the subversion packages. These are their contents:

svn-buildpackage

The svn-buildpackage contains the following tools:

Attention: You need at least version 0.6.22 of svn-buildpackage, earlier versions had problems with "layout 2". You need svn-buildpackage version 0.6.26 or later for svn-inject to accept option "--setprops".

Subversion

The tool you will mostly be using is svn. This is the tool similar to cvs in that it is used to add files, remove files, move files, etc. It is also used for check-out, export, and commit commands, amongst others.

ssh

The Perl Group Subversion repository is hosted by svn.debian.org, which only allows commit access via ssh. svn will use ssh to connect to svn.debian.org.


2. Repository Anatomy

The structure of a standard Subversion repository is a follows:

    trunk/
    tags/
    branches/

Obviously, trunk/ is where the trunk lives, tags/ is where tags live (they are a little different in SVN than in CVS, please see http://svnbook.red-bean.com), and branches/ is where branches live.

The Perl Group used to use a different repository layout, but has now switched to this standard one. Each perl module gets its own subdirectories under trunk/, tags/, and branches/:

    trunk/libfile-touch-perl/
    tags/libfile-touch-perl/
    branches/upstream/libfile-touch-perl/
    trunk/libperl6-export-perl/
    tags/libperl6-export-perl/
    branches/upstream/libperl6-export-perl/

Currently, branches/upstream/ is where the upstream code resides. Various tools use this branch to download original tarballs to generate .diff.gz files when building. -- Only few packages have other branches, e.g. for backports.

In tags/, we tag all of our releases like we do in CVS, like so:

    tags/libfile-touch-perl/0.04-1/

If we wanted to check out libfile-touch-perl 0.04-1, we could simply check out the location of the tag. More on that in the SVN documentation and in this document later on.


3. Initial Upload

You might want to upload your public key to the SVN server before starting this procedure. You may also need to do some ssh setup if your local username is different than your svn.debian.org username. See 8. Hints and Tricks, and the Alioth FAQ at http://wiki.debian.org/Alioth/SSH.

The upload procedure is simple. Once you have the source to the package (.orig.tar.gz, .diff and .dsc), all you have to do is:

    svn-inject -l 2 --setprops \
        libfile-touch-perl_0.04-1.dsc \
        svn+ssh://svn.debian.org/svn/pkg-perl/

Other useful options might be "-c 0" (don't check out anything) and "-t trunk/tarballs" (put .orig.tar.gz in directory trunk/tarballs).

svn-inject will now start doing the following:

  1. Start a new package tree in SVN.
  2. Upload the orig.tar.gz to branches/upstream/.
  3. Check out this upstream version into a working directory.
  4. Patch the working directory version with your .diff.gz.
  5. Upload this new debianized version to trunk/.
  6. Set subversion props on the debian directory so that svn-{buildpackage,upgrade} know the layout.

If the imported release is already in the Debian archive you might want to tag that release, using the following command. It is not really required, though, as long as "our" releases are tagged properly.

    svn copy \
        svn+ssh://svn.debian.org/svn/pkg-perl/trunk/libfile-touch-perl/ \
        svn+ssh://svn.debian.org/svn/pkg-perl/tags/libfile-touch-perl/0.04-1

More about tagging later.


4. Building the Package

4.1 Building the trunk

If we wanted to check out a release for building, we would carry out the following command:

    svn co svn+ssh://svn.debian.org/svn/pkg-perl/trunk/libcgi-safe-perl/ .

This checks out the trunk into the current directory. (Alternatively, you might choose to keep all of trunk/ checked out.) Now, type:

    svn-buildpackage [-rfakeroot] [-kyourkey] [-uc] [-us]

This will try to build the package and, in doing so, will perform the following steps:

  1. Extract the current version from debian/changelog
  2. Export the current check-out to ../build-area/
  3. a. Check for the availability of the .orig.tar.gz source tarball, or...
  4. b. Check for the availability of .orig source dir
  5. Build the package using dpkg-buildpackage
  6. Clean the build tree and delete the exported check-out
  7. Things will be done in ../build-area/

Note that if there were previous uploads with the same upstream version to the Debian archive that were not built with svn-buildpackage, the Debian archive scripts would most likely complain if you build your package with the .orig.tar.gz that svn-buildpackage creates from the SVN repository. To avoid this, put the .orig.tar.gz file from the Debian archive in your build directory (manually, or using apt-get source). If you make the first and subsequent uploads of an upstream version, you don't have to worry about this.

To build the package, use:

    svn-buildpackage -rfakeroot -uc -us [-kyourkey] [--svn-lintian]

The --svn-lintian option can (and should) be used to check the resulting package for sanity and for compliance with Debian policy.

4.2 Building an already tagged release

This is a little trickier than building the trunk. First check out the tag:

    svn co svn+ssh://svn.debian.org/svn/pkg-perl/tags/libcgi-safe-perl/0.04-1 \
        libcgi-safe-perl_0.04-1

Now, if we want a full build, we need the sources. Therefore, we have to sort of hack around some limitations of svn-buildpackage. We need to add a line to libcgi-safe-perl_0.04-1/.svn/deb-layout:

    upsCurrentUrl=svn+ssh://svn.debian.org/svn/pkg-perl/branches/upstream/libnet-imap-simple-perl/0.93

This enables svn-buildpackage to find upstream sources correctly.

If you signed the package, it is ready for upload with dput et al.


5. Tagging and Releasing

We will need to be able to fetch the source of any Debian release that is out there. This is why we have to tag our repository after every package release. Like we said before, tagging is not exactly the same as in CVS. In CVS, the version number for every tagged file is aliased with that tag. That way, version 1.1.1 is aliased 0.1-1 and version 1.1.2 is aliased 0.1-2, for example. In SVN, this works differently.

In SVN, we simply copy the trunk/packagename directory to a new directory called tags/packagename. This way, file revisions aren't aliased, we simply copy the trunk in its current form to a different location just like you would in a regular filesystem. SVN does this cleverly, so you can keep track of log entries and the tag copy doesn't take up any extra space on disk.

5.1 Automatic tagging using svn-buildpackage

You can create the tag automatically when building the final version of the package that is going to be uploaded to the archive by using svn-buildpackage's --svn-tag option:

    svn-buildpackage [...] --svn-tag

If you have already built and/or uploaded the final version, you can use svn-buildpackage's --svn-tag-only option to create the tag only and not do any package building:

    svn-buildpackage --svn-tag-only

5.2 Automatic tagging using debcommit

Even shorter:

    debcommit -r|--release

5.3 Manual tagging

In case you need or want to create a tag manually, it works like this:

    svn copy \
        svn+ssh://svn.debian.org/svn/pkg-perl/trunk/libfile-touch-perl/ \
        svn+ssh://svn.debian.org/svn/pkg-perl/tags/libfile-touch-perl/0.04-1

You don't need a check-out of the SVN tree to do this. It even works faster if you don't have one. It can execute these commands over the network.

You can tag an older revision by using the -r switch:

    svn copy -r 53 \
        svn+ssh://svn.debian.org/svn/pkg-perl/trunk/libfile-touch-perl/ \
        svn+ssh://svn.debian.org/svn/pkg-perl/tags/libfile-touch-perl/tag_we_forgot

5.4 Working with tags

Whenever you would feel like checking out one Debian release, just check out the directory you copied earlier.

    svn export \
        svn+ssh://svn.debian.org/svn/pkg-perl/tags/libfile-touch-perl/0.04-1 \
        libfile-touch_0.04-1

Now, dpkg-buildpackage away!

NB! Never modify files in the tag directory. If you tag by mistake, just delete the directory and copy a different revision of the trunk.


6. Upstream upgrade

When a new version of a package has been released upstream, the SVN repository should be brought up to date and a new Debian upload should be made.

6.1 Classical version

If the Debian package has a debian/watch file, you can use the uscan utility from within the trunk/ directory to check for and fetch the latest upstream release:

    uscan

If you don't like the symlink it produces, you can do:

    uscan --rename

which will rename the tarball instead of symlinking it.

This will download the latest upstream tarball to ../ and give it a proper name (as a Debian original package tarball). The availability of new upstream versions of packages with watch files can be easily checked by using the Debian Watch Health System (DEHS) at http://dehs.alioth.debian.org or by going to http://pet.debian.net/pkg-perl/pet.cgi.

If the package has no watch file, you have to download the upstream tarball manually. Or you could create a watch file yourself, which is always a good idea -- see uscan(1).

Then use svn-upgrade from within trunk/, passing it the name of the upstream tarball you just downloaded. For example:

    svn-upgrade ../File-Touch-0.04.tar.gz

This will upgrade the upstream package in the SVN repository, automatically merge the Debian changes from the last Debian release with it, and place the result into trunk/. You can then review and fine-tune the result, and adjust the debian/changelog, manually or using debchange.

6.2 Easier version

Since version 0.6.25 svn-upgrade has a --uscan switch, so the previous two steps can be combined as

    svn-upgrade --uscan

(maybe after checking for newer versions with uscan --report --verbose.)

Finally, for both versions, check the diff with svn diff and commit your changes to SVN using svn ci or debcommit. Then you can build and release/tag the package normally as shown in the previous sections.


7. Maintaining debian/changelog

Of course, the proper tool for this is debchange or for short, dch. There are a couple of caveats, though.

First, add DEBCHANGE_RELEASE_HEURISTIC=changelog to ~/.devscripts. This would turn on release heuristics of dch, causing it to treat changelog entry with release=UNRELEASED as a working one and if release is not UNRELEASED, then the entry is considered released and dch adds new entry (with release=UNRELEASED). This way one always knows which package is released and which is not.

Second, add svn-noautodch to ~/.svn-buildpackage.conf. This will stop svn-build-package --svn-tag from adding new changelog entries.

With these configurations in place, the release field in the last debian/changelog entry reflects the current state of the repository:

UNRELEASED

When you put "UNRELEASED" in the release field, then this means the package is work in progress. It is not uploaded yet and is not ready to be uploaded, it still needs some work before it is in a state to be released.

something else

The package is either uploaded or is pending upload. The periodic cron job / post-commit hook that generates http://pet.debian.net/pkg-perl/pet.cgi distinguishes between the two cases by looking in the package archive/incoming and NEW.


8. Hints and Tricks

How to have svn-buildpackage not ask for a password so often

One of the annoying things about svn-buildpackage is that when you check out a package using the svn+ssh protocol, it will ask your password pretty often when building, about 25 times. This tends to get annoying by the second time you have to type in your password. To avoid this, upload your public SSH key in the alioth account area (https://alioth.debian.org/account/editsshkeys.php).

Note that even if ssh-copy-id seems to work, this is only temporary since the authorized_keys file is re-generated from the alioth account info every now and then.

To avoid typing even the public key passphrase you may want to run SSH agent (see ssh-agent(1), included in the openssh-client package).

What if your svn.debian.org username is different than your local username

The URLs used above for svn commands assume that your username on svn.debian.org is the same as your local username. If this is not the case, you can put user@ in front of svn.debian.org in all of the URLs, but this will cause problems with the current svn-buildpackage. It uses properties stored in the repository to find URLs, and of course those properties don't have any specific usernames in them.

You can solve this problem with your local ssh configuration, however. Edit ~/.ssh/config (creating it if you don't already have it) and add a stanza for svn.debian.org like:

    Host svn.debian.org
        User <user>

replacing <user> with your username on svn.debian.org. This will tell ssh to use that username by default when connecting to svn.debian.org unless another is specified, and will let you use svn with the default URLs.

How to not build directly under trunk/package/../build-area/

You might choose to check out all of trunk/, this seems to be a common practice. When building from inside the trunk directory, the standard location for svn-buildpackage will be trunk/package/../build-area/. This places the build area inside the SVN check-out directory creating lots of files in the trunk directory which can get confusing since that directory is already quite large.

The solution is to put one line in a file called trunk/package/.svn/deb-layout. This file is automatically created by svn-buildpackage but we can place our defaults there before it starts. The line reads:

    buildArea=~/debian/perl/pkg-perl/build-area
Some tools to check your package before building

Config::Model provides some tools to check Debian package. For more information, see https://sourceforge.net/apps/mediawiki/config-model/index.php?title=Using_Config-Model#Debian_packaging


Version

$Id$


Authors


Contributors


License

Copyright (c) 2004-2012 by the individual authors and contributors noted above. All rights reserved. This document is free software; you may redistribute it and/or modify it under the same terms as Perl itself

Perl is distributed under your choice of the GNU General Public License or the Artistic License. On Debian GNU/Linux systems, the complete text of the GNU General Public License can be found in `/usr/share/common-licenses/GPL' and the Artistic License in `/usr/share/common-licenses/Artistic'.