Re: Managing Debian packages with Subversion
#include <hallo.h>
* Fabian Fagerholm [Fri, Aug 29 2003, 12:44:02PM]:
> On Thu, 2003-08-28 at 22:24, Fabian Fagerholm wrote:
> > How do I manage a new Debian package with Subversion?
>
> Thanks to jcollins@asgardsrealm.net and joeyh@debian.org for their
> insight into this issue. I will try to summarize everything in this
> reply to myself.
>
> Managing Debian packages with Subversion
>
> The following assumes you have basic knowledge of Subversion (SVN). If
> you need to read up on its installation and usage, please consult the
> Subversion Book by Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael
> Pilato, available from the Subversion site at
> http://subversion.tigris.org/ or the book's site
> http://svnbook.red-bean.com/.
>
> What are we trying to accomplish?
>
> We want to manage Debian packages with Subversion.
>
> In other words, we want to store all the files related to a Debian
> "source package" in a Subversion repository, including the upstream
> source. When making changes to the packaging, or when updating the
> package to a new upstream version, we want to check out our "project"
> (our package) from the repository, make the required changes, and then
> commit the changes back into the repository. Also, when we are satisfied
> with the state of the packaging and want to release a new version, we
> want to automate certain steps such as tagging the current state of the
> repository with an appropriate name and version number (corresponding to
> the debian package version), exporting this tag and building the
> package.
>
> Where appropriate, we want to use the "Subversion way" of doing these
> things, meaning we want to take full advantage of the features provided
> by Subversion.
>
> Choosing your repository structure
>
> While there are several ways of structuring your repository, common
> practise is to have trunk/, branches/ and tags/ directories and divide
> the content among these. Two questions arise:
> * Should the repository have trunk/, branches/ and tags/ at the
> top level, each containing project directories -- or should the
> top level be divided by project, and each project directory
> contain trunk/, branches/ and tags/?
> * Should there be an additional top-level directory called
> vendor/, containing the upstream source -- or should the
> upstream source be treated as just another branch?
>
> We thus have 2x2 choices:
> A. Use vendor/ for upstream source.
> A. Per-project trunk/, branches/, tags/ and vendor/.
> B. Repository-wide trunk/, branches/, tags/ and vendor/.
> B. Use a regular branch for upstream source.
> A. Per-project trunk/, branches/ and tags.
> B. Repository-wide trunk/, branches/ and tags/.
>
> Choosing one is largely a matter of taste. The repository will look
> clean and structured to newcomers if the top-level directory is divided
> by project (sub-option A). It might also add to ease of comprehension to
> have upstream sources in vendor/ (option A). But there are some
> technical considerations if you want to use the svn:externals property
> (see the Subversion Book for details) to pull in several project
> directories at once. (TODO: explain this further)
>
> Option A.A.: Per-project trunk/, branches/, tags/ and vendor/
>
> The repository will have the following structure:
>
> projectA/
> trunk/
> branches/
> tags/
> vendor/
> projectB/
> trunk/
> branches/
> tags/
> vendor/
> ...
>
> The idea of this layout is to reflect the logical structure in the
> repository. Internally, Subversion makes no distinction between a
> directory called trunk and a directory called tags. Only your use of
> these directories dictate their meaning. To Subversion, it's all the
> same.
>
> Option A.B.: Repository-wide trunk/, branches/, tags/ and vendor/
>
> The repository will have the following structure:
>
> trunk/
> projectA/
> projectB/
> ...
> branches/
> projectA/
> projectB/
> ...
> tags/
> projectA/
> projectB/
> ...
> vendor/
> projectA/
> projectB/
> ...
>
> The advantage of this might be that the svn:externals property might
> work better. (TODO: verify, why)
>
> Option B.A.: Per-project trunk/, branches/ and tags/
>
> The repository will have the following structure:
>
> projectA/
> trunk/
> branches/
> tags/
> projectB/
> trunk/
> branches/
> tags/
> ...
>
> Here, the logical structure is reflected in the repository, but the
> upstream sources are considered just another branch. Vendor tags are
> considered just another set of tags. This approach is fine, but there is
> no technical reason to do so. Subversion doesn't care.
>
> Option B.B.: Repository-wide trunk/, branches/ and tags/
>
> The repository will have the following structure:
>
> trunk/
> projectA/
> projectB/
> ...
> branches/
> projectA/
> projectB/
> ...
> tags/
> projectA/
> projectB/
> ...
>
> As in B.A., upstream sources and tags are not treated specially. This
> might also work better with svn:externals. (TODO: check, why)
>
> As noted before, the choice is largely a matter of taste. However, take
> into account that Subversion doesn't care how you structure your
> repository. The only tehcnical consideration is when using the
> svn:externals property. (TODO: verify this and add the explanation
> above, then adjust this to reflect the explanation) In the following, we
> will simply refer to the option name (A.A., A.B., etc.) when explaining
> the differences between the options.
>
> Populating your project
>
> When starting to package a new Debian package, the following steps are
> performed:
> * Download the upstream source and unpack it.
> * Enter the upstream source directory and import it (svn import)
> into the appropriate directory:
> * A.A. projectX/vendor/current
> * A.B. vendor/projectX/current
> * B.A. projectX/branches/upstream
> * B.B. branches/projectX/upstream
> * Tag the state of what you just imported (svn copy):
> * A.A. projectX/vendor/<version>
> * A.B. vendor/projectX/<version>
> * B.A. projectX/tags/upstream/<version>
> * B.B. tags/projectX/upstream/<version>
> * Populate trunk/ from the imported upstream source (svn copy):
> * A.A. projectX/trunk
> * A.B. projectX/trunk
> * B.A. trunk/projectX
> * B.B. trunk/projectX
> * Check out the trunk you just created into a directory called
> project-<version> (svn co).
> * Debianize by dh_make. Note for people who have just read the New
> Maintainer's Guide: skip the -f flag. If you have the
> environment variable EMAIL set up correctly, you can skip the -e
> flag as well. You just need to run dh_make in the newly created
> directory.
> * Add the new debian/ directory to subversion's control (svn add).
> * Adjust packaging scripts as needed. Don't do any big changes
> yet, you just want to modify the control and README.Debian
> files, and perhaps some of the most obvious files in debian/.
> Try to think about the most initial state of packaging you want
> to start with.
> * Finally, commit the changes (svn commit).
>
> Working with the project
>
> There is nothing special about working with the Debian package from a
> Subversion point of view. You just follow these steps:
> * Check out HEAD (the latest version) of your trunk (svn co) or
> update the trunk directory (svn update).
> * Make the required changes.
> * Commit (svn commit).
> Try to structure the changes. Think about what you are going to do, and
> define one task. Carry out the task, then commit. Pick another task,
> carry it out, commit. And so on. This way, each commit will take the
> package from one defined state to the next, and the commit changelog
> will help you find the change that broke your package. You'll be able to
> say "I made a mistake in revision 123, I'll have to undo it". Then you
> can go back to the state before the mistake was made, and undo it in the
> next revision. Several Subversion commands help you here -- see the
> Subversion book for details.
>
> Updating to a new upstream version
>
> Having populated your repository in the manner described above, the
> following procedure will allow you to move your packaging to a new
> upstream version, resolving any conflicts between your modified version
> and the new upstream version. (This section is largely based on the
> Subversion Book)
> * Download the new upstream source and unpack it.
> * Use the svn_load_dirs tool to update the current upstream
> version and tag it (this will be committed immediately):
> * A.A. svn_load_dirs -t <version>
> url://host/repos/projectX/vendor current
> /path/to/new/version
> * A.B. svn_load_dirs -t <version>
> url://host/repos/vendor/projectX current
> /path/to/new/version
> * B.A. svn_load_dirs -t tags/upstream/<version>
> url://host/repos/projectX/ branches/upstream
> /path/to/new/version
> * B.B. svn_load_dirs -t tags/projectX/upstream/<version>
> url://host/repos/ branches/projectX/upstream
> /path/to/new/version
> * (TODO: verify that all of the above are correct)
> * The above might produce conflicts between the versions. You must
> resolve these conflicts, so it may be neccessary to familiarize
> yourself with the changes introduces by upstream between the
> versions. (You should do so in any case...)
> * Check out HEAD (the latest version) of your trunk (svn co).
> * Merge the differences between the previous upstream version and
> the current (new) upstream version into your trunk (svn merge):
> svn merge url://to/previous/version url://to/current/version
> trunk
> * You must again resolve any resulting conflicts.
> * Commit the new version (svn commit).
>
> Remember, if you follow the advice below about tagging your releases,
> then you have well-defined checkpoints to roll back to if anything goes
> wrong.
>
> Making a release
>
> When you are ready to make a release of your package, you should tag the
> current state of trunk with the appropriate version number:
> * A.A. projectX/tags/<version>
> * A.B. projectX/tags/<version>
> * B.A. tags/projectX/<version>
> * B.B. tags/projectX/<version>
>
> Then export (svn export) the current tag and build the package. You also
> need to export the upstream source and turn it into an .orig.tar.gz.
Nice excerpt. Today I have created svn-inject (derived from cvs-inject
but not the broken svn-inject fork that was in early versions of
subversion package).
http://people.debian.org/~blade/misc/svn-inject
MfG,
Eduard.
--
Es ist schlimm, daß man vor lauter heißerer Liebe zu Freunden ihnen
gerade das Bestimmteste über ihre ganze Lage zu sagen wagt.
-- Jean Paul
Reply to: