Tags:
create new tag
, view all tags

How to start plugin development in Subversion (SVN)

Motivation

I just tried to develop a new Plugin in SVN and it took me a while to figure out how to do it. There are several different documents involved, so I am going to try to get all into one, hoping that the kick-off for new plugin-developers becomes a little easier.

What means SVN or Subversion?

SVN is an abbreviation for 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, SVN is considered an ideal development environment and there should be used if you are seriously thinking about developing plugins or any other kind of software.

When I am talking in the following of checkin/submit or checkout, this refers to uploading (=checkin) information to or downloading (=checkout) information from a SVN server. If you do not have any idea at all about Subversion, I strongly recommend you to read into an open book about Subversion and later on SubversionReadme so that you get familiar with the general concepts before getting on with this guide.

Step-by-step

1. Registration

First of all (and I am convinced that anyone who found his way through to this document has already done this), you have to be registered on TWiki.org because your username and password will be requested once you start putting and updating your plugins on SVN.

2. Check-in access to TWiki SVN

In addition to that, you need to be able to submit to the TWiki SVN server at http://svn.twiki.org/. Normally you can only checkout files from there. To do so, read SoYouWantToBeATWikiDeveloper and after that RequestAccessToSubversion. Your application will be reviewed and it may take some days until you get access granted, but as I managed to get it, I am positive that you will be able to do so, too. smile

3. TWiki installation based on SVN

Now to the harder part:
There is a detailed tutorial for a TWiki installation based on SVN at SubversionBasedTWikiInstall. This type of TWiki installation is not required for Plugin development, but recommended as it simplifies the installation of Plugins and its testing. The main idea of this setup is to "simulate" the installation of Plugins instead of really installing them and therefore incorporating associated files into an existing TWiki installation. As you surely will be doing modifications to your new plugin, uninstall might be difficult on a conventional TWiki installation, but very easy on a TWiki installation based on SVN. Use perl pseudo-install.pl all for virtually installing all extensions and perl pseudo-install -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 TWiki:
cd /var/www/twiki
# Check out the core from TWiki SVN:
svn co http://svn.twiki.org/svn/twiki/trunk/core core
# Check out the standard extensions, one by one:
svn co http://svn.twiki.org/svn/twiki/trunk/BehaviourContrib BehaviourContrib
svn co http://svn.twiki.org/svn/twiki/trunk/ClassicSkin ClassicSkin
svn co http://svn.twiki.org/svn/twiki/trunk/CommentPlugin CommentPlugin
...
# Install all the extensions you just downloadad:
cd core
perl 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 perl pseudo-install.pl NameOfSpecificExtension.
To uninstall one specific extension, enter perl pseudo-install.pl -uninstall NameOfSpecificExtension.
To uninstall all extensions, enter perl pseudo-install.pl -uninstall all.

Now call configure to make sure you have TWiki running (standard configuration should be enough - do not waste too much time on customizing your TWiki setup) before you go on with the next step.

ALERT! If you decide to do a TWiki SVN installation from the trunk (see SubversionBasedTWikiInstall), it might happen that the guys working on the TWiki core just messed up once more some of TWiki's core features and that therefore the installation from a current revision does not work (sorry, core guys wink I know you are always trying to improve and fix things!). In this case, try going back to previous revisions or just have some patience until they fixed everything. Do not doubt immediately your IT skills - sometimes it is not your fault smile

4. Create the initial directory for your new plugin!

Before we get into further details, maybe you already figured out how plugins and TWiki itself are working on SVN. If not, here is how it goes:

All development work is done in the trunk, which is located at http://svn.twiki.org/svn/twiki/trunk/. Directly within there, there are two types of directories: The core directory, that includes all TWiki core features, and all the other directories, that hold extensions (plugins, contribs, etc.). So the trunk looks something like that:

http://svn.twiki.org/svn/twiki/trunk/
                    |
                    |- AccessStatsPlugin
                    |- ActionTrackerPlugin
                    |- AddDBMGroupPlugin
                    |- AdvertsPlugin
                    |- AgentPlugin
                    |- ...
                    |- core (holding the core features)

Normally, on a TWiki SVN installation, you would just checkout the trunk plus the extensions you need and pseudo-install them (see SubversionBasedTWikiInstall). So in this case, you do not have a complete checkout of the trunk. Therefore, you can only do changes to files or directories you checked out, not to the trunk directory!

But, as you want to add a new directory to the trunk, you will have to checkout the whole trunk at least once so that you are able to create the new, initial directory. You can either do that in the same directory that you use for your TWiki SVN installation or you do it in a seperate directory that you create only for this purpose. Personally, I prefer the second solution. Switch to this directory, checkout the whole trunk and create the new directory to your local checkout.

So let's again assume the following:

  • You are going to checkout the whole trunk in a separate directory, located at /var/www/temp
  • The extension you are going to develop is called !FooPlugin and therefore, the directory you are going to develop it in will be called FooPlugin, too.

So, the following steps would be necessary to create the new directory:

# Change to your temporary directory:
cd /var/www/temp
# Check out the whole trunk to this directory:
svn co http://svn.twiki.org/svn/twiki/trunk .
# Create a new directory through SVN called FooPlugin:
svn mkdir FooPlugin

The name of the directory must be the same one you are going to use for your extension. And it should either end in Contrib or Plugin, depending on its type. See also ReadmeFirst, TWikiPlugins and ContribPackageHowTo.

5. Submit your new directory to SVN

Now you could submit your new directory to SVN, using the svn commit command. BUT: For tracking and control, the TWiki SVN requests two things
  1. You have to add a comment to any change you commit to the SVN 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 TWiki Bugs web.

How to get an item number? Well, just go to the TWiki Bugs web, file a new bug report (although you are not exactly reporting a bug) 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 TWiki SVN server would look like this:

svn commit -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 TWiki user name (confirm it with [Enter]) and after that your password. Congratulations - your new directory should have been submitted!

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

6. Include the FooPlugin directory into your SVN based TWiki installation

The complete trunk you checked out in step 4 will now no longer be necessary, so just delete it. Now, as on TWiki SVN there is a directory where you can submit to, head back to your original TWiki installation and check out the new directory from SVN.

This might look like that:

# Change to your TWiki installation:
cd /var/www/twiki
# Check out your FooPlugin directory from SVN
svn co http://svn.twiki.org/svn/twiki/trunk/FooPlugin FooPlugin

You just obtained a local copy of the (still empty) FooPlugin directory and can now start developing your extension there!

7. Start developing your extension!

The easiest way to start developing a new extension is using the BuildContrib. It can be used to create the basic files necessary for new extensions, prepare all files necessary for a release (based on what you developed), generate an installer script for your extension and even upload your finished (and hopefully tested!) extension to the TWiki site.

The basic commands are:

  • perl create_new_extension.pl FooPlugin to create the basic files for your new extension, including the correct sub-directory structure.
  • 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 TWiki website.

For detailed information, have a look at BuildContrib and BuildContribCookbook.

Once you generated some files for your new extension, you can include them into your SVN based TWiki installation. Just:

# Change to the core directory of your installation:
cd /var/www/twiki/core
# Install your new extension:
perl 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 .

8. Keep on working!

You want to submit the files you developed on your local computer to TWiki SVN so that other people can help you fixing bugs or improving it? Ok, commit them!

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

You want to see what other people have worked on since your last update? Check it!

cd /var/www/twiki/FooPlugin
svn status

IDEA! Always check the status of your local files against the ones on the TWiki SVN server! This way you avoid that somebody else worked on the same file as you did and that you overwrite his work by submitting blindly your file to TWiki SVN.

You want to update your local copy with the changes someone else did on some files?

cd /var/www/twiki/FooPlugin
svn update

End of the story

I hope this document gets some stones out of the way for anyone who is motivated to contribute his work to TWiki, but does not know how to. At least it covers the stumbling stones I found when I started contributing. And if you believe that I left out something important - go ahead. This is what a discussion is there for!

-- Contributors: SebastianKlus - 06 Aug 2008

Discussion

Please don't forget to mention the BuildContrib, which provides the create_new_extension.pl script, as well as:

  • perl build.pl release and
  • perl build.pl upload

Sven recently suggested adding perl pseudo-install.pl developer which would automatically install the extra non-core modules used for development i.e.

-- CrawfordCurrie - 07 Aug 2008

Done! thumbs up

-- SebastianKlus - 07 Aug 2008

Edit | Attach | Watch | Print version | History: r9 < r8 < r7 < r6 < r5 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r9 - 2008-08-20 - KennethLavrsen
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.