#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 [EMAIL PROTECTED] and [EMAIL PROTECTED] 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
