=head1 NAME SVN Howto =head1 Description A short description how to use SVN to access the mod_perl and related projects source distributions (also applies to the documentation project). Just as cvs access to the Apache development tree, the mod_perl code pulled from cvs is not guaranteed to do anything, especially not compile or work. But, that's exactly why we are using cvs, so everyone has access the latest version and can help see to it that mod_perl does compile and work on all platforms, with the various versions and configurations of Perl and Apache. Patches are always welcome and simply testing the latest snapshots is just as, if not more helpful. It's recommended to subscribe to the L list, which is the place cvs commit logs and diffs are mailed to; at least if you're going to work on the code. =head1 Getting SVN http://subversion.tigris.org/ =head2 Checking Out To checkout a fresh copy of modperl-2.0 run the following commands from the directory you want the sources to stay in: % svn co https://svn.apache.org/repos/asf/perl/modperl/trunk/ mod_perl-2.0 After svn has finished downloading the files you will find a new directory called I in the current working directory. Now you need to chdir into that directory: % cd modperl-2.0 before you can start changing things. =head2 keeping your copy up to date To keep your local copy in sync with the repository, do % svn update -dP in the top directory of the project. You should run update evertime before you start working on the project. =head2 Sending Patches To send a patch, first run: % svn diff -u in the top directory of the project. The output of diff will be sent to STDOUT, so it might be better to redirect the output to a file: % svn diff -u > patch If you added files or directories to the project, do a diff against I: % diff -u /dev/null newdir/newfilename When this patch is applied, the new dir and the new file will be automatically created. On Windows-based systems, you can do % diff -u NUL newdir/newfilename instead. Then send your patch to the maintainer of the project, or the appropriate mailing list. =head1 Getting SVN snapshots In case you can't get SVN access to work (or don't want to), there is another possibility: at http://cvs.apache.org/snapshots/ , there are snapshots of the interesting SVN repositories you might want to download. These snapshots are extracted from SVN every 6 hours, so might not contain the I changes, but you'll get pretty close. The file names contain the date and time, which you can also see in the directory listing. So just grab the latest one by date, which will get you the latest version. See the list of interesting repositories L to find out which snapshots you might want to download. =head1 Inspecting the SVN server with ViewCVS ViewCVS is installed on the Apache SVN server. You can reach it at http://svn.apache.org/viewcvs.cgi/. From there you can browse the list of available projects, look at the files contained in those projects, their logs, and do colored diffs between versions. This is information you can get from your SVN client (through C, C and friends), but the web interface makes it much easier to get a good overview of the different files. =head1 SVN access for mod_perl committers mod_perl committers need to first login to svn.apache.org and run svnpasswd command. Then the first time you want to commit you will be asked for a password, which is then will be stored in ~/.subversion. Since all the commits require https:// checkouts, no password can be sniffed during the commit when it's sent to the server via an encrypted channel. =head2 Getting the Client =head2 Working with SVN For example let's say you want to work with the I svn repository. To check out the repository do: % svn co http://svn.apache.org/repos/asf/perl/modperl/docs/trunk modperl-docs If it's a first time you ssh to svn.apache.org, it will ask if you want to allow the host I. Answer I. Then you are asked for your password; type it in. Now you will get a freshly checked out copy of the I repository. If you get permission problems, most likely your Unix group wasn't adjusted. Contact the person who gave you the svn access. To bring your repository's copy up to date, run: % svn update -dP or the shortcut: % svn up -dP The C<-d> option builds directories (if any were added since last update), like checkout does. The C<-P> option prunes empty directories if any. You can put these and other handy options into the rc file. For example with C and C clients, this is I<~/.svnrc>. Usually we have the following in this file. svn -z9 update -dP diff -u The first line tells to use the best compression level when communicating with the server. The last line will do a unified I when C is used. If you have done some changes, which weren't committed, it's possible that while trying to merge the differences the client will report about collisions which happens when you've happened to change something that was changed and committed by somebody else. You will have to resolve the conflicts by manual editing of the files in question. Normally, most changes should go through peer review first. It might be a good idea to discuss the intricacies of a change on the appropriate mailing list before committing anything. Then, to commit: % svn commit filename(s) or the shortcut: % svn ci filename(s) But first run C to avoid any problems with out of date versions of files. If you get any conflicts because of it, these must be changed before doing C, which will incorporate any changes into the repository. To commit only a single file, do: % svn commit path/to/file If a file or a directory is not under svn control you have to add it to the svn first and then commit it: % svn add path/to/file % svn ci path/to/file Usually svn recognizes binary files by their extensions (e.g. images), but if you commit a file with some unusual extension tell your svn client that it's a binary file with C<-kb> option: % svn add -kb path/to/binary/file Then, to add it permanently, you will have to commit it. =head2 A Special Note to modperl-docs Committers One B important note before (ab)using your powers: the mod_perl documentation project makes use of an automatic build system. This means that any changes committed will be periodically rebuilt to create the new site (so you don't have to login and do the manual update/rebuild). This is great, but a side-effect of this is that if someone commits anything that doesn't work, the build will fail, and might break parts of the site. To avoid these problems, please make sure to run C on your working copy to test I committing. Also, make sure to run C to check that you have added all files to the repository; it's easy to forget adding the files you have created, and C will work fine your side, but will fail for others because of the missing files the build depends on. =head2 Avoiding Typing in the Password After awhile you will get tired of typing the password for every svn operation that you do. You can avoid that using the public key authentication and the ssh authentication agent. Refer to your ssh client's manpage for more information. For example for the C and C clients, the C utility can be used to enter the password once for your private key and then it'll do the public key authentication for you every time you work with svn over ssh (as long as C is running). Refer to the relevant manpage for more info (I in this case). =head1 mod_perl and Related Projects on svn.apache.org =over =item modperl sources for mod_perl 1.0, for use with apache-1.3 =item apache-1.3 the Apache 1.3 HTTP Server =item modperl-2.0 the new version of mod_perl, for use with httpd-2.0. See the L for more information about downloading the 2.0 components and installing them. =item httpd-2.0 the new Apache 2.0 HTTP Server =item apr needed for modperl-2.0 =item apr-util needed for modperl-2.0 =item modperl-docs the mod_perl documentation (i.e. this site). See the L for information on how to download, build and submit patches to the documentation. =back Or see http://svn.apache.org/viewcvs.cgi/ for a list of all projects. =head1 See also =over =item * http://cvsbook.red-bean.com/ Open Source Development with CVS is a book published by Coriolis Inc. as part of the Coriolis OpenPress series. Chapters 2, 4, 6, 8, 9, and 10 -- comprising a complete introduction, tutorial and reference to CVS -- are being released free under the terms of the GNU General Public License. =item * http://www.cvshome.org/docs/manual/ Version Management with CVS by Per Cederqvist et al is the "official" manual for CVS. Commonly known as "the Cederqvist," the manual covers repositories, branches, and file maintenance, and includes reference material for both CVS users and CVS repository administrators. =back =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. =over =item * the L =back =head1 Authors =over =item * Thomas Klausner Edomm (at) zsi.atE =item * Doug MacEachern =item * Per Einar Ellefsen Eper.einar (at) skynet.beE =back Only the major authors are listed above. For contributors see the Changes file. =cut