Tags:
create new tag
, view all tags
ALERT! Note: We switched from CVS to SVN and moved all PluginsInSubversion. This topic here needs to be refactored, relevant content needs to be moved to PluginsInSubversion. -- PeterThoeny - 02 Aug 2005


In 2001 discussions for setting up a cvs repository for plugin development began. The idea is that a larger plugin dev group can maintain plugins in CVS independently from the TWiki CoreTeam. It is much more efficient and more in the spirit of a wiki to have plugins, addons and skins in cvs, with permissions to let people make changes (as opposed to uploading zipfiles and diffs).

Plugins, Contribs, Skins and Add-ons

Just to clear up the terminology:
  • a Plugin is a code module that strictly observes the TWiki Plugins and Func APIs.
  • a Skin is a module of template files and tailored topics. A skin may or may not ship with an accompanying Plugin, Contrib or Add-on
  • a Contrib (ContribPackage) is a code module that extends the TWiki core, but bypasses the standard Plugins and Func APIs, calling core functions directly. As such, Contribs are not as portable between release, and should be avoided unless there is no other choice.
  • an AddOn is an additional code module that may directly patch the core code. Add-ons are even less portable than Contribs.
For simplicity we refer to all of these as "plugins" in the text below.

Plugins in CVS

The nature of CVS and SourceForge dictates that all plugin authors have write access to the whole repository. Therefore a seperate sourceforge project, http://twikiplugins.sourceforge.net/ was created so plugin authors, many of them new to programming and/or perl, wouldn't inadvertantly stomp on the core.

It was decided to create a separate module for the plugins, with each plugin going in its own sub-directory - each one in effect mirroring the twiki directory structure:

PluginName/bin
PluginName/lib
PluginName/data
etc.
This simplifies developing build scripts and writing tests. The primary reason for the SF project is the CVS repository. Most of the plugin collaboration happens here in the Plugins web, so the SF based web site is just a pointer to Plugins.WebHome.

One of the beauties of the Plugins web is that it allows a deliciously chaotic style of development. Someone has an idea, does something about it, posts what they've done. The 'project leader' for that plugin is the original author.

There isn't a place for a single guru of the plugins, or a even council of elders, because there is no central theme or strategy behind plugins development that can be steered. People do stuff because it's useful to them, and then share it.

By default, plugin developments are one-man jobs published by uploading zips to the Plugins web.

Whoever creates a plugin gains the right to access the twikiplugins CVS as developer. To get cvs write access: send email to PeterThoeny, give him your sourceforge username (you'll need to create an account if you don't already have one) and the name of the Plugin(s) you are developing.

There is no PluginsCoreTeam, there is only the current community of plugin developers. Proposals for API changes are discussed on the Plugins and Codev webs openly, with the final outcome decided by the core developers.

Feature enhancements to a plugin (other than by the plugin's main developers) should first be discussed on the plugin's 'Dev' page.

Bug fixes for plugins are welcome from any developer (but respect the ContactAuthorFirst flag). Just attach a patch (a context diff is usually best) to the Dev topic for the plugin.

Make sure you list additional plugin requirements above and beyond the requirements listed in the main documentation TWiki.TWikiDocumentation

Each plugin has it's directory structure below the root for easy separation:

twikiplugins
   /README
   /TWikiDrawPlugin
   /lib
   /TWiki
   /Plugins
   /TWikiDrawPlugin.pm
   /pub
   /TWiki
   /TWikiDrawPlugin
   /*.gif
   /data
   /TWiki
   /TWikiDrawPlugin.txt
   /XpTrackerPlugin
   /lib
   /etc
   /SeeSkin
   /etc
   /GenHTMLAddon

Put in CVS everything one needs to create the plugin zip file (perl code, templates, plugin description and eventually manuals). The burden on the repository is small, and it's much easier to manage and package. You will usually have:

  • lib/TWiki/Contrib/SomeContrib.pm the contrib module, if this is a contrib
  • lib/TWiki/Plugins/SomePlugin.pm the plugin module, if this is a plugin
  • data/TWiki/SomePlugin.txt the plugin topic
  • pub/TWiki/SomePlugin/* if you have attachments to the plugin topic
  • bin/Plugins/SomePlugin/* if you have added scripts
  • other needed stuff
Data in the pub and data dir may be edited in twiki itself, and committed to CVS only when approaching a new release.

Plugins for production use should be attached to the Plugin's topic in the Plugins web, regardless if the code is in CVS or not.

The Plugin author can opt for current non-CVS dev & packaging, or for CVS based dev & packaging

The final stable Plugin package, regardless of dev process, is a Plugin description topic and an attached ZIP file (with no version numbers).

Most important of all, we should have fun developing plugins. So lets define how to contribute a plugin without many road blocks; with some process but not too much.

How to import your files into TWikiPlugins CVS repository:

  • This example outlines how: (feel free to improve it)
 export TWIKIROOT=/var/www/html/twiki
 mkdir stage
 cd $TWIKIROOT/stage
 export CVSROOT=USERID@cvs.sourceforge.net:/cvsroot/twikiplugins
 mkdir sm
 cd sm
 wget http://twiki.org/p/pub/Plugins/SiteMinderPlugin/SiteMinderPlugin.zip
 unzip SiteMinderPlugin.zip
 ls
 cvs import -m "Use TWiki with siteminder" twikiplugins/SiteMinderPlugin mrjc start

Use of BuildContrib

Extensions can be bundled with a BuildContrib build.pl script. See BuildContrib for details.

cp BuildContrib/lib/TWiki/Contrib/Build/build.pl YourPlugin/lib/TWiki/Plugins/YourPlugin/build.pl

Then edit it, replacing:

< { package BuildBuild;
---
> { package XBuild;
32c32
<   @BuildBuild::ISA = ( "TWiki::Contrib::Build" );
---
>   @XBuild::ISA = ( "TWiki::Contrib::Build" );
36c36
<     return bless( $class->SUPER::new( "BuildContrib", "Build" ), $class );
---
>     return bless( $class->SUPER::new( "X", "Build"), $class );
50c50
< $build = new BuildBuild();
---
> $build = new XBuild();

Where X is the name of your plugin.

Note to CodevCommunity: we need to change the the EmptyPlugin to incorporate a blank build.pl file

How to make a release

A plugin, addon or skin is released by bulding up a ZIP file and attaching it to a topic in the TWiki Plugins web (here).

Plugins use a variety of approaches to building release zips, some using sophisticated build files and others no build files at all. But really, you should at least write a build file that executes the tests you have written (see MakeStrategy). If you have such a build file, you can extend it with rules that zip up the files for a release fairly trivially. If your plugin has such a build file, you can simply write

make release
or
ant release
SharedCode includes a build environment designed to take care of things like building zips for plugins. Consider using it.

If you don't have a build file things get a bit more complicated. You can't just zip up the directory containing the plugin, because you'd end up zipping all the CVS files as well, and any other cruft that's lying around. So, write a build file. Again, repeat after me, write a build file.

One note on releasing. Do not, under any circumstances, name your zip file anything other than PluginName.zip. Several authors have in the past tried to put version numbers into zip names, which is unnecessary and breaks automatic tools.

Another approach to writing a build file is described in PluginCvsToolsAddOn.

Using the Eclipse IDE

We are using EclipseIDE for developing JavaPasteAddOn. It should work with the settings listed below:
  • :extssh:yoursfid@cvs.sourceforge.net:/cvsroot/twikiplugins
In addition, when you check in your AddOn or Plugin, you need to specify, for example:
  • twikiplugins/JavaPasteAddOn
Not just
  • JavaPasteAddOn
Otherwise you'll make the mistake I did. big grin

If you need to debug CVS under Eclipse, see this to get the cvsprotocol chat output.

http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-vcm-home/docs/online/cvs_features2.0/cvs-faq.html#misc_6b

Getting the repository

If you want to work with multiple people on a plugin, you need a local copy of the plugins repository.

Quick steps:

  1. You need a SourceForge account.
  2. Follow SourceForge's instructions to create a private/public key pair: Guide to Generation and Posting of SSH Keys
  3. Go to the file ~/.ssh/id_dsa.pub, and copy the contents.
  4. Go to your SF account management page: http://sourceforge.net/account/, and to the link [Edit SSH Keys for Shell/CVS]
  5. Paste the id_dsa.pub contents in the input box, Update and wait for ten minutes.
  6. In a terminal, type ssh username@cvs.sourceforge.net
  7. Add to known hosts, and type ssh username@cvs.sourceforge.net again
  8. If you have a CVS GUI client, use these settings:
    • Host: cvs.sourceforge.net
    • Port: 22
    • Root: /cvsroot/twikiplugins
    • User: your SourceForge account name
    • Password: the passphrase for your key

FAQ

How do I create a test environment for my plugin development?

Use the approach of maintaining separate twiki installations and symlinking common data and pub directories into them. This allows one to have multiple installations of twiki using the same data areas. Of course your knickers get in a twist occasionally, but in general this approach works well (it's used here on twiki.org all the time).

You might also look into using the PerlUnit unit test framework for creating unit tests for your plugin that manage their own environment (see the attached example and SharedCode).

I goofed up and created an incorrect directory. How do I get rid of it?

Removing directories from cvs requires someone to submit a request to sourceforge staff. The -P (prune) option doesn't physically remove a directory from the repository -- it's used to remove empty directories from your workspace (cvs update) or on checkout.

The path http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/twikiplugins/twikiplugins/ looks, erm, redundant. Couldn't that be fixed to just one /twikiplugins/ ?

It is a bit weird, but the first twikiplugins is the cvs root on sourceforge and the second is the cvs module name that then allows you to get all the plugins using one cvs checkout. It looks funny, but its better than having to do a checkout for each plugin (or to have to maintain the module aliases)

See also RestructurePluginsDevelopment.


AndreaSterbini, PeterThoeny, NicholasLee, DennisDaniels, SteveRoe, CrawfordCurrie, JohnCavanaugh, RichardDonkin, MartinCleaver, GrantBow, SvenDowideit, MattWilkie, AndreaBacchetta, AnthonPang, PeterKlausner, ArthurClemens, WillNorris
Topic attachments
I Attachment History Action Size Date Who Comment
Texttxt build.pl.txt r1 manage 1.3 K 2004-06-12 - 12:25 CrawfordCurrie Example build file from CommentPlugin
Edit | Attach | Watch | Print version | History: r38 < r37 < r36 < r35 < r34 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r38 - 2005-08-02 - PeterThoeny
 
  • 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.