Subversion

SUBVERSION IS NOW READ ONLY See GitRepository for development information.

See ProjectOverview for an overview of the development process, and how we do revision control. This document is all about the nitty-gritty details of how we use Subversion to implement that process.

We maintain our code using Subversion, SVN in short. If you are user or admin using Foswiki, you can download the latest code using the instructions on this page, but be aware that this is not a stable release version! You are recommended to use the official releases (see Downloads for the latest release).

This page is primarily meant for developers that want to track latest changes and contribute code back to our SVN repository.

Quick overview:

• Repository address: http://svn.foswiki.org
• Commit messages are sent to the DeveloperEventsMailingList.
• Want to contribute? RequestAccessToGit to introduce yourself and apply for access.
• Need help? Ask SvenDowideit (eastern hemisphere) or KoenMartens (western hemisphere) or get live support our IRC support channel.

Subversion URLs

Repository	URL
SVN browsable repository	http://svn.foswiki.org/
Release 1.1.x versions	http://svn.foswiki.org/branches/Release01x01/
Trunk (bleeding edge, not for production use)	http://svn.foswiki.org/trunk/

Older releases

Repository	URL
Release 1.0.x versions	http://svn.foswiki.org/branches/Release01x00/

What is Subversion?

Subversion is a free revision control system. It records all the source code, and tracks changes to that source code.

It can be downloaded from http://subversion.tigris.org/. A Windows shell extension client is available at http://tortoisesvn.tigris.org/, and a cross-platform GUI at http://rapidsvn.tigris.org/. There is also a book about Subversion usage online at http://svnbook.red-bean.com/

How does Foswiki use Subversion?

The Foswiki project has a subversion server at http://svn.foswiki.org/ that we use to store and track changes to the Foswiki source code, and the source code of many extensions. You don't have to use subversion to contribute to Foswiki, but you'd have to have a pretty strong reason not to.

The trunk is used to check in all bug fixes and new code targeted at the next major release. It is a requirement that the code on the trunk always works , and most developers rely on it always working for their development environments. So you have to take great care checking code into the trunk.

Due to the nature of development code, major bugs or issues will occasionally be encountered in this code.

When a Foswiki release is made, then release branches are created to track minor fixes and security fixes to that code, so that the trunk can move ahead without getting dragged down by old releases. Developers can also create other branches in the /scratch area if they want to try out new ideas.

The code checked into the trunk will be used to drive a Foswiki at http://trunk.foswiki.org/, which is used to serve the bugs database. This checkout area is kept up to date by cron job that runs every 10 minutes. In the best case, the person doing the checkin will be able to almost immediately check the correct functioning of their checkin.

The trunk is also used for Foswiki extensions, which sometimes follow the same release cycle as the core code, but often don't. Extension developers can use the trunk without fear of breaking the bugs database, as long as they:

1. Don't check into any of the 'standard' plugins that are installed by default with a Foswiki release (see core/lib/MANIFEST).
2. Check only into Extension named subdirectories (e.g. MyNewPlugin)

How to check out the trunk

To check out the trunk including the core and all extensions

mkdir foswiki
cd foswiki
svn co http://svn.foswiki.org/trunk .
A AccessStatsPlugin/
A ActionTrackerPlugin/
A AddDBMGroupPlugin/
 ......
A core
  ... 

In the case you are using svn behind a proxy server

If you leave out the "." at the end of the svn co command, it will create a directory named trunk for you.

This will check out everything on the trunk - including every extension that has ever been checked in. if you don't want this, and only want to check out a subset of the bits you need, see Checking Out a Subset

See SubversionBasedInstall for practical advice on using a SVN checkout as a live install.

How to check out a release branch

There is a branch for each release. There may be other developer branches as well, depending on what is going on.

See http://svn.foswiki.org/branches/ for the branches.

To check out the Release branch including the core and the default extensions

mkdir foswiki
cd foswiki
svn co http://svn.foswiki.org/branches/Release .
A index.html/
A bin/
A bin/
 ......
A lib/
  ...

then, if you want to add a non-core plugin, check out that extension from the trunk into the directory, and then use ./pseudo-install.pl to link it into your system

svn co http://svn.foswiki.org/trunk/WidgetSkin
A data/
 ...... 
A lib/
  ... 
./pseudo-install.pl WidgetSkin 

The list of tags can be found at http://svn.foswiki.org/tags/.

How to check in

Remember to run

svn diff

before commiting!

Please run PerlTidy on your code before checking in, eg:

find . -name '*.pm' -exec perltidy -b '{}' \; 

We now enforce that .pm and .pl files are run through =perltidy= for some extensions, such as Foswiki's core/default extensions. See TIDY

For documentation topics, remove any stray Ctrl-M's, and ensure that the TOPICINFO metadata is set to author="ProjectContributor" and version="$Rev$" before checking in the file.

Rules for checkins

Please keep these rules in sync with the error message coded into core/tools/develop/pre-commit.pl b/tools/develop/pre-commit.pl

Trunk will reject commits if they don't meet the following rules. Checkins must:

1. Have a comment...
2. ...with relevant ItemNNN topics in the first line, example:

   Item12345: Item12346: fixed foo, updated release notes

3. Use ItemNNN topics which are open at the time of checkin,
   1. E. not one of: Closed, Waiting For Release, No Action
4. Have "tidied" source code if the TIDY control file in the root of the extension calls for it, see: http://foswiki.org/Development/TIDY

This is to make sure that we have traceability of all changes. These comments are used to update the linkage between items in the Tasks web and checkins in Subversion, so you should try hard to make sure they are accurate and complete.

Branches don't have trigger scripts, so there is no constraint on what message you use when you check in.

If you have been given write access to the repository, you should use the same login and password as your Foswiki.org WikiName.

Generating Patches

Even if you can't check in, you can still contribute. Make your changes in your checkout area, and then cd to the root directory of the checkout area and:

svn update
svn diff > mypatch.diff

Attach the file mypatch.diff to the relevant topic in Tasks web (there should be one topic for each change) and ask someone with checkin rights to merge it.

Please ensure the FoswikiUnitTests are run if possible, and always run through the tests in the TestCases web in your checkout area.

Watching

Check-ins are automatically mailed to the Foswiki-svn mailing list. See Foswiki-svn@lists.sourceforge.net.

Scratch area in SVN

http://svn.foswiki.org/scratch is an area for Developers to try out ideas, either a temporary branch, or new foswiki related ideas. Anyone with checkin access can create new branches.

To create a new branch of the core code (derived from the trunk) under scratch,

svn copy http://svn.foswiki.org/trunk/core http://svn.foswiki.org/scratch/NewBranchName 

For doing the copy, you will be asked for a commit message. You should include an Item number from the Bugs web e.g.

Item90210: Branch for doing performance experiments. 

Then go back to checking out a branch, substituting the URL of the new branch.

Checking Out a Subset

The trunk checkout instructions above will check out the Foswiki core and every extension. Often you will want to check out just a subset of the code specific to what you are working on or testing. This can save an awful lot of disc space, as well as making subversion commands much faster and more manageable.

The best way to do this is to create a root directory for all your Foswiki work. For example, "~/httpdocs/foswiki". Then check out the core from the trunk (or whatever release branch you are working on):

cd ~/httpdocs/foswiki
svn co http://svn.foswiki.org/trunk/core core

This will checkout the core to the core subdirectory. Now you can checkout the subset of extensions you want to have available:

svn co http://svn.foswiki.org/trunk/TopicUserMappingContrib TopicUserMappingContrib
svn co http://svn.foswiki.org/trunk/CommentPlugin CommentPlugin
svn co http://svn.foswiki.org/trunk/EditRowPlugin EditRowPlugin

(note: if you intend to build a Foswiki release, you will need to checkout all the extensions listed in core/lib/MANIFEST)

Now you can use core/pseudo-install.pl to soft-link (Linux/BSD etc) or copy (Windows) the extensions into the core. For example:

cd ~/httpdocs/foswiki/core
./pseudo-install.pl default

(some day someone will write a script to do all this in one step. Some day....)

FAQ

Subversion already has rich FAQs, and Google is your friend, so this FAQ is restricted to questions that relate to the Foswiki project's specific use of subversion.

git

This is not really a frequently asked question, but it seems to fit.

So how can one use git to work on Foswiki? Everything should be explained on how to use git.

Notes

Proxy Server

In the case you need to use svn behind a proxy it's enough to edit your ~/.subversion/servers and uncomment/modify these variables:

# http-proxy-host = defaultproxy.whatever.com
# http-proxy-port = 12345
# http-proxy-username = defaultusername
# http-proxy-password = defaultpassword
# http-proxy-exceptions = *.exception.com, www.internal-site.org