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>.
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 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:
The svn-buildpackage contains the following tools:
svn-inject is used to introduce the source of a package into the repository.
It operates on the .dsc file associated with the source files. It checks in
the package and upstream code in the correct locations in SVN. This tool
should be used when a new package is put in the care of the Perl Group.
The Perl Group now uses a SVN repository layout that is not the default used by
svn-inject. Pass "-l 2 --setprops" to svn-inject to make it use the right layout.
You may also add svn-setprops to ~/.svn-buildpackage.conf and
use "-l 2" for short.
At some point in time, the package will have to be uploaded for inclusion in unstable. The packages that reside in SVN have to be built for that. However, dpkg-buildpackage doesn't play nice with SVN check-out directories. Luckily, svn-buildpackage does. Use svn-buildpackage in a checked-out directory.
When a new version of the package has been released upstream, svn-upgrade can be used to bring the SVN repository up to date and prepare a new Debian upload easily.
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".
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.
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.
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.
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:
orig.tar.gz to branches/upstream/.
.diff.gz.
trunk/.
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.
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:
debian/changelog
../build-area/
.orig.tar.gz source tarball, or...
.orig source dir
../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.
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.
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.
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
Even shorter:
debcommit -r|--release
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
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.
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.
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.
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.
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:
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.
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.
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).
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.
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
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
$Id$
Copyright (c) 2004-2011 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'.