How to start extension development in Subversion
What is Subversion?
"Subversion is a free/open-source version control system. That is, Subversion manages files and directories, and the changes made to them, over time. This allows you to recover older versions of your data, or examine the history of how your data changed" (Collins-Sussman, B., et al. (2007). What is Subversion?
[Electronic version]. Version control with Subversion
.). This said, Subversion is considered an ideal development environment and should be used if you are seriously thinking about developing Foswiki extensions - or any other kind of software.
Note that checkin/submit
refers to uploading
(=checkin) information to or downloading
(=checkout) information from a Subversion server. If you haven't used source code control before, or are simply unfamiliar with Subversion, read the open book about Subversion
, and later on SvnRepository
, so that you get familiar with the general concepts before getting on with this guide.
First of all you have to be registered on foswiki.org
because your username and password will be requested once you start trying to work with Subversion.
2. Check-in access Subversion
In addition to that, you need to be able to submit to the Subversion server at http://svn.foswiki.org/
. Normally you can only checkout files from there. To do so, read GettingStarted
and after that RequestAccessToSubversion
. Your application will be reviewed and it may take some days until you get access granted, but it's very rare that is is refused.
3. Installation based on Subversion
Now to the harder part:
There is a detailed tutorial for an installation based on Subversion at SubversionBasedInstall
. This type of installation is not required for extension development, but recommended as it simplifies the installation of extensions and their testing. The main idea of this setup is to "simulate" the installation of extensions instead of really
installing them and therefore incorporating associated files into an existing installation. As you surely will be doing modifications to your new extension, uninstall might be difficult on a conventional installation, but very easy on a installation based on Subversion. Use
for virtually installing all extensions and
./pseudo-install.pl -uninstall all
for uninstalling them again.
To give you an example, let's assume the following:
So, the following steps would be necessary for the setup:
# Change to the directory where you are going to install:
# Check out the core from SVN:
svn co http://svn.foswiki.org/trunk/core core
# Check out the standard extensions, one by one:
svn co http://svn.foswiki.org/trunk/BehaviourContrib BehaviourContrib
svn co http://svn.foswiki.org/trunk/ClassicSkin ClassicSkin
svn co http://svn.foswiki.org/trunk/CommentPlugin CommentPlugin
# autoconfigure a simple default LocalSite.cfg
# Install all the extensions you just downloadad:
# Change the ownership of all files according to the configuration of
# user and group of your webserver:
chown -R www-data:www-data .
To install only one specific extension, enter
To uninstall one specific extension, enter
./pseudo-install.pl -uninstall NameOfSpecificExtension
To uninstall all extensions, enter
./pseudo-install.pl -uninstall all
to make sure you have your new installation running (standard configuration should be enough - do not waste too much time on customizing your setup) before you go on with the next step.
If you decide to do a Subversion installation from the
), it might happen that the guys working on the core broke something and the installation of the latest revision does not work. In this case, try going back to previous revisions or just have some patience until they have fixed everything. Do not doubt your IT skills - sometimes it is not your fault
4. Create the initial directory for your new extension!
Before we get into further details, maybe you already figured out how your Subversion installation works. If not, here is how it goes:
All development work is done in the trunk, which is located at
. Directly within there, there are two types of directories: The
directory, that includes all core features, and all the other directories, that hold extensions (plugins, contribs, etc.). So the trunk looks something like that:
|- core (holding the core features)
helps a lot with extensions development, from the initial directory tree and files creation until the upload to Foswiki:Extensions
. So, let's create the initial directory tree:
perl create_new_extension.pl FooPlugin
mv FooPlugin ../tmp
takes the name of an extension (it must end in
) and creates the correct initial directory structure. Then we should move the directory to an empty directory (
for example). This step is essential to the following section.
5. Submit your new directory to Subversion
Now you could submit your new directory to SVN
, using the
For tracking and control, the Subversion requests you to do two things:
- You have to add a comment to any change you commit to the Subversion server, summing up what you are submitting.
- The comment has to begin with
Item1234: where Item1234 corresponds to an existing, open bug report in the Tasks web.
How to get an item number? Well, just create a new task
indicating in the summary a short description of the extension you are developing, that it is being worked on and that this item is waiting for you. Remember the bug number that will be automatically assigned to your new item because this is what you need for your comment.
Now try it once more. Let's say you are developing the
and the item number assigned to your bug report is 2233, then the command for submitting the new directory to the Subversion server would look like this:
svn import tmp/ http://svn.foswiki.org/trunk/ -m "Item2233: Creation of initial directory for FooPlugin"
You will be requested to enter a password for a
user - just skip it with
. Now enter your user name (confirm it with
) and after that your password. Congratulations - your new directory should have been submitted!
Now obtain a working copy of your extension:
svn co http://svn.foswiki.org/trunk/FooPlugin
rm -rf tmp/ # Your old directory is not necessary anymore
You are now directly contributing to development! Be aware that this brings along some additional responsibilities, so please review DeveloperResponsibilities
6. Start developing your extension!
The basic commands are:
perl build.pl release to prepare all files necessary for the release of FooPlugin, including the installer script.
perl build.pl test to run unit tests on your extension.
perl build.pl upload to upload your extension to the foswiki website.
For detailed information, have a look at BuildContrib
Once you generated some files for your new extension (and they are listed in the
file), you can include them into your Subversion based installation. Just:
# Change to the core directory of your installation:
# Install your new extension:
# Make sure the ownership of all files is still set correctly and according
# to the configuration of user and group of your webserver :
chown -R www-data:www-data .
For a trunk installation it might be required to configure apache, so it will support symlinks in
Using standard cgi will allow to run the trunk setup on the same machine like some other Foswiki installation, even if e.g. the other installation may use an accelerator like ModPerlEngineContrib
. Using trunk and another installation with an accelerator at the same time causes issues. Maybe special setups are possible but it doesn't work as described in a "standard" apache setup with ModPerlEngineContrib
7. Keep on working!
You want to submit the files you developed
on your local computer to Subversion so that other people can help you fixing bugs or improving it? Ok, commit them!
svn commit -m "Item2233: Checking in beta release of FooPlugin"
You want to see what has changed
since your last update? Check it!
You want to update your local copy
with the changes someone else did on some files?
8. Release your extension
To release it read on in BuildContrib