r2242 - website

Julian Mehnle jmehnle-guest at costa.debian.org
Mon Feb 27 00:23:53 UTC 2006


Author: jmehnle-guest
Date: 2006-02-27 00:23:52 +0000 (Mon, 27 Feb 2006)
New Revision: 2242

Modified:
   website/subversion.pod
Log:
website/subversion.pod
* Rewrapped and cleaned up.


Modified: website/subversion.pod
===================================================================
--- website/subversion.pod	2006-02-26 23:31:36 UTC (rev 2241)
+++ website/subversion.pod	2006-02-27 00:23:52 UTC (rev 2242)
@@ -4,14 +4,13 @@
 
 =head1 INTRODUCTION
 
-This guide describes the procedures that the Debian Perl Group
-developers use to upload packages to the Subversion (SVN) repository
-Debian provides to them.
+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.
+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
+This is a work in progress.  Please send any comments or ideas to
 <debian-perl at lists.debian.org>.
 
 =head1 INDEX
@@ -20,7 +19,7 @@
 
 =item 1. The Tools
 
-=item 2. Repository Anatomy.
+=item 2. Repository Anatomy
 
 =item 3. Initial Upload
 
@@ -30,19 +29,18 @@
 
 =item 6. Upstream Upgrade
 
-=item 7. Hints and tricks
+=item 7. Hints and Tricks
 
 =back
 
 =head1 1. The Tools
 
-This section will describe what tools are available and what they do.
-This section is a work in progress. Please send any comments or ideas
-on how to improve this section to <debian-perl at lists.debian.org>.
+This section will describe what tools are available and what they do.  This
+section is a work in progress.  Please send any comments or ideas on how to
+improve this section to <debian-perl at lists.debian.org>.
 
 Most of the tools you will be using will come from either the
-B<svn-buildpackage> or the B<subversion> packages. These are their
-contents:
+B<svn-buildpackage> or the B<subversion> packages.  These are their contents:
 
 =over 4
 
@@ -54,32 +52,30 @@
 
 =item * svn-inject
 
-Like we said, B<svn-inject> is used to insert 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.
+Like we said, B<svn-inject> is used to insert the source of a package into the
+repository.  It operates on the C<.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.
 
-=item * svn-buildpackage - Like dpkg-buildpackage, only SVN aware.
+=item * svn-buildpackage -- Like dpkg-buildpackage, only SVN aware.
 
-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
-checkout directories. Luckily, B<svn-buildpackage> does. Use
-svn-buildpackage in a checkedout directory.
+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,
+B<svn-buildpackage> does.  Use svn-buildpackage in a checked-out directory.
 
-=item * svn-upgrade - Used to upgrade a checkout to a new upstream version.
+=item * svn-upgrade -- Used to upgrade a check-out to a new upstream version.
 
 TODO
 
 =back
 
-=item subversion
+=item Subversion
 
-The tool you will mostly be using is the B<svn> tool which resides
-here. This is the tool similar to B<cvs> in that it is used to add
-files, remove files, move files, etc. It is also used for checkout,
-export and commit commands, amongst others.
+The tool you will mostly be using is B<svn>.  This is the tool similar to
+B<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.
 
 =back
 
@@ -87,50 +83,50 @@
 
 The structure of a standard Subversion repository is a follows:
 
- trunk/
- tags/
- branches/
+    trunk/
+    tags/
+    branches/
 
-Obviously, trunk/ is where the trunk lives, tags/ is where tags live
+Obviously, C<trunk/> is where the trunk lives, C<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.
+L<http://svnbook.red-bean.com>), and C<branches/> is where branches live.
 
-We will have quite a few perl modules over time, so we will start of
-with splitting our repository into subrepositories:
+We will have quite a few Perl modules over time, so we will start of with
+splitting our repository into subrepositories:
 
- libfile-touch-perl/trunk/
- libfile-touch-perl/tags/
- libfile-touch-perl/branches/
- libperl6-export-perl/trunk/
- libperl6-export-perl/tags/
- libperl6-export-perl/branches/
+    libfile-touch-perl/trunk/
+    libfile-touch-perl/tags/
+    libfile-touch-perl/branches/
+    libperl6-export-perl/trunk/
+    libperl6-export-perl/tags/
+    libperl6-export-perl/branches/
 
-Currently, branches/ is where the upstream code resides. Various tools
-use this branch to download original tarballs to generate .diff.gz
-files when building.  This is also the only branch we will be using
-for now, but time will tell.
+Currently, C<branches/> is where the upstream code resides.  Various tools use
+this branch to download original tarballs to generate C<.diff.gz> files when
+building.  This is also the only branch we will be using for now, but time will
+tell.
 
-In tags/, we tag all of our releases like we do in CVS, like so:
+In C<tags/>, we tag all of our releases like we do in CVS, like so:
 
- libfile-touch-perl/tags/debian_version_0_04-1/
+    libfile-touch-perl/tags/0.04-1/
 
-If we would want to checkout libfile-touch-perl_0.04-1, we could
-simply checkout the location of the tag. More on that in the SVN
-documentation and in this document later on.
+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.
 
 =head1 3. Initial Upload
 
-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:
+The upload procedure is simple.  Once you have the source to the package
+(C<.orig.tar.gz>, C<.diff> and C<.dsc>), all you have to do is:
 
- svn-inject \
-   libfile-touch-perl_0.04-1.dsc \
-   svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/
+    svn-inject \
+        libfile-touch-perl_0.04-1.dsc \
+        svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/
 
-You might want to upload your public DSA key to the svn server before
-starting this procedure, see hints and tricks below.
+You might want to upload your public DSA key to the SVN server before starting
+this procedure, see L</"7. Hints and Tricks">.
 
-Note: B<Do not forget the /packages/ suffix>.
+Note: B<Do not forget the C</packages/> suffix>.
 
 svn-inject will now start doing the following:
 
@@ -138,23 +134,23 @@
 
 =item 1. Start a new package tree in SVN.
 
-=item 2. Upload the orig.tar.gz to C<branches/upstream>.
+=item 2. Upload the C<orig.tar.gz> to C<branches/upstream/>.
 
-=item 3. Checkout this upstream version into a working directory.
+=item 3. Check out this upstream version into a working directory.
 
-=item 4. Patch the working directory version with your .diff.gz.
+=item 4. Patch the working directory version with your C<.diff.gz>.
 
-=item 5. Upload this new debianized version to C<trunk>.
+=item 5. Upload this new debianized version to C<trunk/>.
 
 =back
 
-If the imported release is already in the debian archive you might want to
-tag that release, using the follow command. It is not really required,
-though, as long as "our" releases are tagged properly.
+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://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/trunk/ \
-   svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/tags/debian_version_0_04-1
+    svn copy \
+        svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/trunk/ \
+        svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/tags/0.04-1
 
 More about tagging later.
 
@@ -162,167 +158,160 @@
 
 =head2 4.1 Building trunk
 
-If we would want to checkout a release for building, we would carry
-out the following command:
+If we wanted to check out a release for building, we would carry out the
+following command:
 
-svn checkout svn://svn.debian.org/pkg-perl/packages/libcgi-safe-perl/trunk/ .
+    svn co svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libcgi-safe-perl/trunk/ .
 
-This checks out the trunk in to the current directory. Now, type:
+This checks out the trunk into the current directory.  Now, type:
 
- svn-buildpackage [-rfakeroot] [-kyourkey] [-uc] [-us]
+    svn-buildpackage [-rfakeroot] [-kyourkey] [-uc] [-us]
 
-This will try to build the package and will try the following trying 
-to do so:
+This will try to build the package and, in doing so, will perform the following
+steps:
 
 =over 4
 
-=item 1. Extract the current version from debian/changelog
+=item 1. Extract the current version from C<debian/changelog>
 
-=item 2. Export the current checkout to ../build-area/package-version
+=item 2. Export the current check-out to C<../build-area/>
 
-=item 3a. Check for the availability of .orig.tar.gz source tarball
+=item 3a. Check for the availability of the C<.orig.tar.gz> source tarball, or...
 
-=item 3b. Check for the availability of .orig sourcedir
+=item 3b. Check for the availability of C<.orig> source dir
 
-=item 4. build the package using dpkg-buildpackage
+=item 4. Build the package using B<dpkg-buildpackage>
 
-=item 5. Clean the build tree and delete the exported checkout
+=item 5. Clean the build tree and delete the exported check-out
 
-=item 6. Things will be done in ../build-area/
+=item 6. Things will be done in C<../build-area/>
 
 =back
 
-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 you build directory (manually or just using apt-get source).
-If you upload the the first and subsequent packages of an upstream
-version, you don't have to worry about this.
+Note that if there were previous uploads with the same upstream version to the
+Debian archive that were not built with B<svn-buildpackage>, the Debian archive
+scripts would most likely complain if you build your package with the
+C<.orig.tar.gz> that B<svn-buildpackage> creates from the SVN repository.  To
+avoid this, put the C<.orig.tar.gz> file from the Debian archive in your build
+directory (manually, or using C<apt-get source>).  If you make the first and
+subsequent uploads of an upstream version, you don't have to worry about this.
 
-If you are satisfied with the package, and want to build the final package
-(the one that is going to be uploaded to the archive), use
+If you are satisfied with the package, and want to build the final package (the
+one that is going to be uploaded to the archive), use
 
- svn-buildpackage --svn-tag [-rfakeroot] [-kyourkey] [-uc] [-us]
+    svn-buildpackage --svn-tag [-rfakeroot] [-kyourkey] [-uc] [-us]
 
-to make svn-buildpackage create a tag of this release. You should
-hardly ever need to tag a release by yourself.
+to make svn-buildpackage create a tag of this release.  You should hardly ever
+need to tag a release manually.
 
-
 =head2 4.2 Building an already tagged release
 
-This is a little trickier than building the trunk. First check out the tag:
+This is a little trickier than building the trunk.  First check out the tag:
 
- svn co svn://svn.debian.org/pkg-perl/packages/libcgi-safe-perl/tags/debian_version_0_04-1 \
-   libcgi-safe-perl_0.04-1
+    svn co svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libcgi-safe-perl/tags/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:
+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
+C<libcgi-safe-perl_0.04-1/.svn/deb-layout>:
 
-upsCurrentUrl=svn://svn.debian.org/pkg-perl/packages/libnet-imap-simple-perl/branches/upstream/0.93
+    upsCurrentUrl=svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libnet-imap-simple-perl/branches/upstream/0.93
 
 This enables svn-buildpackage to find upstream sources correctly.
 
-If you sign the key, the package is ready for upload with dput et. al.
+If you sign the key, the package is ready for upload with B<dput> et al.
 
 =head1 5. Tagging and Releasing
 
-We will need to be able to fetch the source to 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 debian_version_0.1-1 
-and version 1.1.2 is aliased debian_version_0.1-2, for example. In 
-SVN, this works differently.
+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 copy the state of the B<tree> to a new directory called 
-tags. This way, file revisions aren't aliased, we simply copy the tree 
-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 copied tree doesn't take up any extra space on 
-disk.
+In SVN, we simply copy the C<trunk/> directory to a new directory called
+C<tags/>.  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.
 
 Note that using our usual workflow, the tags will be created by
 
- svn-buildpackage --svn-tag
+    svn-buildpackage --svn-tag
 
-when building the final version of the package that is going to be uploaded
-to the archive. Only exception might be the initial upload of a package
-with a version already in the archive (though it might be arguable if we
-actually need this version as a tag).
+when building the final version of the package that is going to be uploaded to
+the archive.  The only exception might be the initial upload of a package with
+a version already in the archive (though it is arguable if we actually need
+this version as a tag).
 
-Anyways, it works like this:
+Anyway, it works like this:
 
- svn copy \
-   svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/trunk/ \
-   svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/tags/debian_version_0.04-1
+    svn copy \
+        svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/trunk/ \
+        svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/tags/0.04-1
 
-You don't need a checkout 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 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.
 
-Whenever you would feel like checking out one debian release, just 
-check out the directory you copied earlier.
+Whenever you would feel like checking out one Debian release, just check out
+the directory you copied earlier.
 
- svn export \
-   svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/tags/debian_version_0.04-1 \
-   libfile-touch_0.04-1
+    svn export \
+        svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/tags/0.04-1 \
+        libfile-touch_0.04-1
 
 Now, dpkg-buildpackage away!
 
-B<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/whatever.
+B<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.
 
-You can tag an older revision by using the -r switch:
+You can tag an older revision by using the C<-r> switch:
 
- svn copy -r 53 svn://.../pkg-perl/packages/libfile-touch-perl/trunk/ \
-   svn://.../pkg-perl/packages/libfile-touch-perl/tags/tag_we_forgot
+    svn copy -r 53 \
+        svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/trunk/ \
+        svn+ssh://user@svn.debian.org/svn/pkg-perl/packages/libfile-touch-perl/tags/tag_we_forgot
 
 =head1 6. Upstream upgrade
 
 TODO
 
-=head1 7. Hints and tricks
+=head1 7. Hints and Tricks
 
 =over 4
 
 =item How to have svn-buildpackage not ask for a password so often
 
-One of the annoying things about svn-buildpackage is that when you
-checkout a package using svn+ssh, it will ask your password pretty
-often when building, say 25 times. This tends to be annoying by the
-second time you type in your password. This will save you some
-password typing:
+One of the annoying things about B<svn-buildpackage> is that when you check out
+a package using the C<svn+ssh> protocol, it will ask your password pretty often
+when building, say 25 times.  This tends to get annoying by the second time you
+have to type in your password.  This will save you some password typing:
 
- ssh-copy-id [-i] user at svn.debian.org
+    ssh-copy-id [-i identity.pub] user at svn.debian.org
 
-Beware that the Alioth maintainers delete the authorized_keys 
-automatically after an hour or so.
+Beware that the Alioth maintainers delete the C<authorized_keys> automatically
+after an hour or so.
 
-If you're really 1337, you can use the web interface on Alioth to
-copy your ssh public key permanently. Use the following URI to do that:
-https://alioth.debian.org/account/editsshkeys.php
+If you're really 1337, you can use the web interface on Alioth to install your
+SSH public key permanently.  Use the following URI to do that:
+L<https://alioth.debian.org/account/editsshkeys.php>
 
-You can also consider the use of an ssh-agent (see ssh-agent(1),
-included in the ssh package, for more information).
+You can also consider the use of an ssh-agent (see L<ssh-agent(1)>, included in
+the C<ssh> package, for more information).
 
-=item How to not build directly under trunk/../build-area
+=item How to not build directly under C<trunk/../build-area/>
 
-Often, you'll check out an entire package with trunk, branches and
-tags. Or, you'll inject a package using svn-inject and want to build
-the package later. The standard location for svn-buildpackage will be
-../build-area/. However, if working from trunk/, this places the build
-area inside the svn checkout directory, polluting the checkout.
+Often, you'll check out an entire package with C<trunk/>, C<branches/> and
+C<tags/>.  Or, you'll inject a package using B<svn-inject> and want to build
+the package later.  The standard location for B<svn-buildpackage> will be
+C<trunk/../build-area/>.  However, if working from C<trunk/>, this places the
+build area inside the SVN check-out directory, polluting the check-out.
 
-The solution is to put one line in a file called
-trunk/.svn/deb-layout. This file is automatically created by 
-svn-buildpackage but we can place our defaults there before it starts. 
-The line reads:
+The solution is to put one line in a file called C<trunk/.svn/deb-layout>.
+This file is automatically created by B<svn-buildpackage> but we can place our
+defaults there before it starts.  The line reads:
 
- buildArea=/usr/src/debian/perl/pkg-perl/build-area 
+    buildArea=~/debian/perl/pkg-perl/build-area 
 
 =back
 
@@ -338,15 +327,14 @@
 
 =head1 LICENSE
 
-Copyright (c) 2004, 2005 Debian Perl Group.  All rights reserved. This document is
-free software; you may redistribute it and/or modify it under the same
-terms as Perl itself
+Copyright (c) 2004-2006 Debian Perl Group.  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'.
+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'.
 
 =for comment
-vim:tw=80
+vim:tw=79




More information about the Pkg-perl-cvs-commits mailing list