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 or checkout 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.

Step-by-step

1. Registration

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 ./pseudo-install.pl all 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:
cd /var/www/foswiki
# 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
cd core
./pseudo-install.pl -A
# Install all the extensions you just downloadad:
./pseudo-install.pl all
# Change the ownership of all files according to the configuration of
# user and group of your webserver:
cd ..
chown -R www-data:www-data .

To install only one specific extension, enter ./pseudo-install.pl NameOfSpecificExtension.
To uninstall one specific extension, enter ./pseudo-install.pl -uninstall NameOfSpecificExtension.
To uninstall all extensions, enter ./pseudo-install.pl -uninstall all.

Now call configure 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.

ALERT! If you decide to do a Subversion installation from the trunk (see SubversionBasedInstall), 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 smile

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 http://svn.foswiki.org/trunk/. Directly within there, there are two types of directories: The core directory, that includes all core features, and all the other directories, that hold extensions (plugins, contribs, etc.). So the trunk looks something like that:
http://svn.foswiki.org/trunk/
                    |
                    |- AccessStatsPlugin
                    |- ActionTrackerPlugin
                    |- AddDBMGroupPlugin
                    |- AdvertsPlugin
                    |- AgentPlugin
                    |- ...
                    |- core (holding the core features)

BuildContrib 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:

cd /var/www/foswiki/core
perl create_new_extension.pl FooPlugin
mkdir ../tmp
mv FooPlugin ../tmp

The create_new_extension.pl takes the name of an extension (it must end in Plugin, Skin or Contrib) and creates the correct initial directory structure. Then we should move the directory to an empty directory ( ../tmp 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 svn import command. BUT: For tracking and control, the Subversion requests you to do two things:
  1. You have to add a comment to any change you commit to the Subversion server, summing up what you are submitting.
  2. 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 FooPlugin 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:

cd /var/www/foswiki
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 root user - just skip it with [Enter]. Now enter your user name (confirm it with [Enter]) 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

ALERT! You are now directly contributing to development! Be aware that this brings along some additional responsibilities, so please review DeveloperResponsibilities carefully.

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 and BuildContribCookbook.

Once you generated some files for your new extension (and they are listed in the MANIFEST file), you can include them into your Subversion based installation. Just:
# Change to the core directory of your installation:
cd /var/www/foswiki/core
# Install your new extension:
./pseudo-install.pl FooPlugin
# Make sure the ownership of all files is still set correctly and according
# to the configuration of user and group of your webserver :
cd ..
chown -R www-data:www-data .

TIP For a trunk installation it might be required to configure apache, so it will support symlinks in core/pub/System:
<Directory "/path/to/trunk_directory/core/pub/System">
    Options FollowSymLinks
</Directory>

TIP 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!

cd /var/www/foswiki/FooPlugin
svn commit -m "Item2233: Checking in beta release of FooPlugin"

You want to see what has changed since your last update? Check it!
cd /var/www/foswiki/FooPlugin
svn status

You want to update your local copy with the changes someone else did on some files?
cd /var/www/foswiki/FooPlugin
svn update

8. Release your extension

To release it read on in BuildContrib.
Topic revision: r14 - 16 Dec 2011, FlorianSchlichting
 
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. see CopyrightStatement. Creative Commons License