[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ next ]

svn-buildpackage - maintaining Debian packages with Subversion
Chapter 1 - Introduction

1.1 Purpose

This short document is only intended to give a short help in converting packages to Subversion management. It is primarily intended for developers not really familiar with Subversion or CVS management and/or converting from maintaining their packages using common tools (dpkg-dev, devscripts) only to version control system Subversion.

1.2 Why a version control system?

But the first question may be: why use a version control system at all? Look at how the source is handled by the Debian package. First, we have the pure upstream source, which is often maintained by another person. The upstream author has his own development line and releases the source in snapshots (often called releases or program versions).

The Debian maintainer adds an own set of modifications, leading to an own version of the upstream package. The difference set between this two version finally ends in Debian's .diff.gz files, and this patchset is often appliable to future upstream versions in order to get the "Debian versions".

So the obvious way to deal with source upgrades/changes is using local copies, patch, different patchutils and scripts to automate all this, eg. uupdate. However, it often becomes nasty and uncomfortable, and there is no way to undo changes that you may do by mistakes.

At this point, the Subversion system can be used to simplify that work. It does the same things that you normaly would do by-hand but keeps it in an own archive (a repository). It stores the development lines of Upstream and Debian source, keeping them in different directories (different branches). The branches are wired internally (the VCS "knows" the history of the file and tracks the differences between the Upstream and Debian versions). When a new upstream version is installed, the differences between the old and new upstream versions and the Debian version are merged together.

You can create snapshots of your Debian version ("tag" it) and switch back to a previous state, or see the changes done in the files. You can store when commiting the file to the repository or place custom tags on the files ("properties") serving various purposes.

1.3 Features

svn-buildpackage and other scripts around it has been created to do follow things:

keep Debian package under revision control, which means storing different versions of files in a Subversion repository

allow easy walking back trough time using svn command

easy retrieval of past versions

keep track of upstream source versions and modified Debian versions

easy installation of new upstream versions, merging the Debian changes into it when needed (similar to the uupdate program)

automated package building in clean environment, notifying about uncommited changes

create version tags when requested to do the final build and update changelog when needed

allow co-work of multiple Debian developers on the same project

auto-configure the repository layout, making it easy to use by people without knowing much about Subversion usage (mostly you need only the add, rm and mv commands of svn)

allow to store only the Debian specific changes in the repository and merge them into the upstream source in the build area (which nicely completes build systems like dpatch or dbs)

If wished, keep the upstream tarballs inside of the repository

1.4 Contents overview

There are currently three scripts provided by the svn-buildpackage package:

svn-inject: script used to insert an existing Debian package into a Subversion repository, creating the repository layout as needed.

svn-buildpackage: exports the contents of the directory associated with the starting directory from the Subversion repository to the clean environment and build the package there

svn-upgrade: similar to uupdate, upgrades the trunk to a new upstream version, preserving and merging Debian specific changes

1.5 Popular repository layouts

There are different ways to store the packages in the repositories (or in multiple repositories at your choice). svn-buildpackage normaly expects a directory structure similar to the one well described in the Subversion Book, which looks like:

     packageA/
        trunk/
        branches/
        branches/upstream
        tags/
     
     projectB/
        trunk/
        branches/
        branches/developerFoo
        tags/

packageA above may be a typical upstream-based source package and a projectB may be a Debian native package with a separate branch created by developerFoo for his own experiments. See Subversion Book/Branches for more details about using Subversion branches.

Also note that Tags work quite different than those in CVS. Subversion does not maintain magic tags associated with some files. Instead, it tracks the file state and moves, so Tagging something means creating a copy (inside of the Repository, harddisk-space efficient) of a certain version of the file set. So the Debian branch of the released package source is contained in trunk/ and is tagged by copying (mirroring) the trunk tree to tags/DEBIAN-REVISION. The same happens for the upstream releases. In addition, the most recent upstream version is mirrored to branches/upstream/current. After few package upgrade cycles, the directory tree may look so:

     # svn ls -R file:///home/user/svn-repo/dev/translucency 
     branches/
     branches/upstream/
     branches/upstream/0.5.9/
     branches/upstream/0.5.9/AUTHORS
     branches/upstream/0.5.9/COPYING
     ...
     branches/upstream/0.6.0/
     branches/upstream/0.6.0/AUTHORS
     branches/upstream/0.6.0/COPYING
     ...
     branches/upstream/current/
     branches/upstream/current/AUTHORS
     branches/upstream/current/COPYING
     ... same stuff as in 0.6.0 ...
     tags/
     tags/0.5.9-1/
     ...
     tags/0.5.9-1/debian/
     tags/0.5.9-1/debian/README.Debian
     ...
     tags/0.6.0-1/
     tags/0.6.0-1/AUTHORS
     ...
     tags/0.6.0-1/debian/
     tags/0.6.0-1/debian/README.Debian
     tags/0.6.0-1/debian/changelog
     ...
     trunk/
     trunk/AUTHORS
     trunk/COPYING
     ... trunk where 0.6.0-2 is beeing prepared ...

svn-buildpackage also supports the second repository layout suggested in the Subversion Book (function/package) but svn-inject prefers the one documented above. Both svn-buildpackage and svn-upgrade should be able to auto-detect the repository layout and the location of package files.

In theory, you do not have to follow that examples and place the trunk, branches and tags directory on the locations you like more. But svn-buildpackage and other scripts won't locate the files automaticaly so you will need to edit the .svn/deb-layout file in your working directory and set paths. See the old abstract about how auto-detection works and the config example.

Finaly, the working directory structure on your development system may look so:

     dev/ # base directory, may be under version control or not
     dev/foo # trunk directories of various packages
     dev/bar # contents correspond to trunk, see above
     dev/tarballs # where "orig" tarballs are stored, may be under VC or not
     dev/build-area # where the packages are exported temporarily and built