Request for Comments: SVN externals

• Version: 1.0
• Date: 2008-07-01
• Author: Gwynne Raskind gwynne@php.net
• Status: Under Discussion
• First Published at: http://wiki.php.net/rfc/svnexternals

This RFC discusses the ways in which the old CVS modules can be translated into SVN externals.

CVS uses a modules file in CVSROOT to provide aliases and directory grouping. When converting to SVN, there is no immediate equivelant for some of the constructs the old repository uses. There are various alternative possibilities, enumerated here.

The most common use of the modules file was creating the “php-src” directory using the php-src module, the TSRM module, and the Zend or ZendEngine2 modules. This is accomplished effectively using an svn:externals property set on the php-src/trunk directory in the SVN repository. Different branches of php-src may use different externals, such as PHP 4 making use of Zend while PHP 5 makes use of ZendEngine2, and PHP 6 may in the future make use of a ZendEngine3 or similar. In practical terms there will never be a need for separate Zend modules in SVN and it might be sensible to merge them together, pasting ZendEngine2's newer data atop Zend's older files and continuing to use a single Zend module.

The other common use of modules was the creation of pseudo-modules such as phpdoc-ja-only from the phpdoc-ja module, and even more the phpdoc-all module which includes all doc language modules. There is no equivelant to such modules in SVN, but there are several ways to achieve a similar effect:

1. Create empty directories in the repository which link to the modules that they contain using svn:externals.
   • Pros
     • Most like the current system
   • Cons
     • Ugly, unsupported, and unnecessary.
2. Use a single combined phpdoc module and require client checkouts to use SVN 1.5's Sparse Directories feature.
   • Pros
     • Very clean, keeps the repository neat
   • Cons
     • Clients must remember to specify the appropriate --depth options or they'll check out much more than intended; sparseness can not be set on the server side
3. Maintain the documentation buildsystem and each set of language files separately.
   • Pros
     • Possibly the cleanest solution possible
     • Falls in line with the current line of development for the documentation build system, PhD
   • Cons
     • Represents a considerable change to the way things currently work
     • Requires support from the buildsystem before it can be implemented

Here is a summary of decisions that need making:

• Whether or not to merge ZendEngine2 into Zend and use a single Zend module (1/0)
• Which method to use to replace pseudo-modules (1: 0/0; 2: 0/0; 3: 1/0)

2008-07-01: Created