Source control procedures

The FSP Drupal site code is under version control. All items contributing to site functionality outside of the "files" subdirectory, and outside the database are kept in the source repository. Specifically included are:

All files provided with the Drupal software distribution.
All contributed modules from third parties.
All custom modules.
All theme files and supporting collateral (logo's, visual elements, style sheets, etc.).
All configuration files.

Source and Release Control

All releases of code are made from the source repository. Changes directly to the site are deprecated.

In the rare event where there was no alternative to making an emergency change directly on the site, the FSP IT group mailing list has to be notified immediately, with a description of the change and a list of files changed. The changes will then be accomodated after the change, and the emergency release tagged after the fact. Needless to say, this should be avoided, as it can lead to changes being lost with resultant time wasted.

Repository Access

The source code repository is maintained with subversion, and the subversion server can be accessed at http://svn2.assembla.com/svn/fsp. A local svn client (see the support section below) will be needed to access the repository, and a valid username/password combination will be needed (mail a request to the FSP IT mailing list to get one).

Repository Structure

The structure was chosen because it lends itself to a loosely-coupled environment like the FSP IT group. The main features of the structure are:

A source tree "trunk" where all changes are eventually merged to, and where all releases are made from. This represents the source code in the production environment.
All development and non-trivial defect fixes are made on branches - one branch for each line of development or defect. This allows several contributors to work at their own pace on unrelated functions, and then have their contributions released without influencing the timeline of other releases.
All branch points, merge points, and releases are tagged.

Inside the repository, there is the high-level structure below:

www	Holds all Drupal-related code
www/trunk	The main development trunk. The trunk is where branches are merged to and releases made from. Only relatively small fixes are made directly on the trunk.
www/branches	Contains branches. A branch is created whenever the development of a new set of functionality is started, or when a defect fix is started. Unrelated changes should get branches of their own, in order not to influence other changes needlessly.
www/branches/fix_missing_block	A hypothetical defect fix branch to fix a very specific problem. All defect branches should follow the naming convention (fix_...).
www/branches/dev_organic	A hypothetical development branch. All development for this function is checked in on this branch until it is ready for release. The naming convention should be followed (dev_...).
www/tags	Tags of important states in the history of the source code. E.g. release tags, branch creation tags, etc.
www/tags/release_X.Y	Hypothetical release tag for release X.Y.
www/tags/dev_organic_start	A tag indicating where the (hypothetical) branch dev_organic was started from. Tagging branch starts and ends makes things a lot easier when merging code, and all branch start points should be tagged like this, with the naming convention [branch_name}_start.
www/tags/fix_missing_block_premerge www/tags/fix_missing_block_postmerge www/tags/fix_missing_block_mergesrc	When a branch is merged back to the trunk, pre- and post-merge tags on the trunk indicate where these changes were merged. Merge tags, like branch tags, are very useful. For reference, the merge source point on the branch is tagged too. Note the naming convention {branch_name]_premerge/postmerge/mergesrc.

Examples

Here are a couple of examples using the command-line version of subversion. In the examples, $FSVN is used as shorthand for the repository URL given above.

Creating a new branch & checking it out

First, create the starting point tag for the branch (useful to compare changes to where the branch started from):

svn cp $FSVN/www/trunk $FSVN/www/tags/dev_organic_start -m "Created dev_organic branch start tag"

Then, create the branch itself:

svn cp $FSVN/www/tags/dev_organic_start $FSVN/www/branches/dev_organic -m "Created dev_organic branch"

And finally check it out locally:

svn co $FSVN/www/branches/dev_organic

Checking out the trunk, merging a branch, and creating a release

First get the current trunk, which is usually equal to what's in production:

svn co $FSVN/www/trunk

Then, merge the branch, using the branch start tag and current tip:

cd trunk
svn merge $FSVN/www/tags/dev_organic_start $FSVN/www/branches/dev_organic .

Review the merged changes, ensure there are no conflicts, and confirm that they make sense:

svn diff | less

Then tag the pre-commit point, commit the changes, and tag the post-commit point:

svn cp $FSVN/www/trunk $FSVN/www/tags/dev_organic_premerge -m "dev_organic pre-merge tag"
svn commit -m "Merged dev_organic branch"
svn cp $FSVN/www/trunk $FSVN/www/tags/dev_organic_postmerge -m "dev_organic post-merge tag"

Learn More

There is a subvrsion book available at svnbook.red-bean.com. The main subversion site is at subversion.tigris.org, where a list of clients for various platforms can be obtained, including TortoiseSVN at tortoisesvn.net, which is a popular GUI client.