This is the dev env I use for work and home development, uploaded here in hope to be helpful to others.

TWiki Dev Env

This directory holds my system to provide an unix development environment for TWiki, freetown (v.4.2.x) for allowing multiple people to co-develop and maintain multiple twiki sites

TWiki, with the advent of more professsional developers and a better organized team (with a release manager), provides a clearer and clearer separation between distributed code/data and local Tailoring and developments, and to separate the core from the extensions (plugins, skins, addons).

This is the system we use at ILOG to allow multiple people (developers, designers, integrators) to work on the same base that can be deployed and updated automatically on may dev/test/staging/production TWiki sites, local or remote.

The principles:

• You must store somewhere:
  • a copy of the official TWiki distribution (or one with your local modifications, maybe maintained in a source control system, or one of the TWiki SVN branches or trunk)
  • a copy (checkout) of the TWiki SVN repository (for the plugins)
• point to it (shell variable or symbolic link in homedir)
• use the current TWiki Dev Env (twde) system as a directory maintained in your company source control system of choice (CVS, SVN, hg, git)
• then the twde system, when deploying (i.e. installing or updating) a site will
  • copy the distrib (only perl code on updates)
  • install all the plugins declared in plugins/, by first installing the TWiki SVN version, then applying your overrides and patches
  • override the files by the ones it finds in local/ dir
  • apply locally developed patches from the patches/ directory

This way, things are clearly kept separate between TWiki official code and local modifications, in a simple way understable by all even if they do not known how to use CVS or SVN. The development flow runs like this:

• people want to change things in TWiki. They for instance just butcher Twiki.pm and put their copy in local/lib/TWiki.pm.
• when things have stabilized, the developer can transform this modified copy into a patch in patches/, or ask a developer to do it if he is just a designer who has butchered a template
• then, this patch can be transformed in a local plugin in plugins/ (that would be contributed back to twiki.org)
• or, incorporated into the twiki sources in order to propose it for the twiki.org MAIN trunk

It allows developers to test easily wild ideas in their local copy, as they will be deployed on their dev sites, and share with coworkers as soon as they commit it.

Details

The shell variables for pointing to twiki.org mirrors is: $TWIKI_FREETOWN_DIST that should point to a directory having specific subdirectories (that can be symbolic links, of course)

• MAIN the main twiki distribution
• twikiplugins the plugins

These directories can contain CVS or SVN admin dir/files, so you can use direct SVN mirrors of the twiki distribution.

If $TWIKI_FREETOWN_DIST is undefined, we will use a directory ~/.twiki_freetown_dist if present. you can use -d foo to use a ~/.twiki_foo_dist instead on deploy.

Our local modifications are kept in these directories:

• local Every file there will override or will be added to the site. You must put them into the proper subdirs: templates/view.myskin.tmpl for a skin, lib/TWiki/UI/Oops.pm to override it, cgi/log.cgi if you have added a cgi dir in your install to hold local scripts and have one such script log.cgi.
• patches holds directories holding our local modification as patches to apply to the above twiki dir by executing the file INSTALL in it. There can be also an UNINSTALL file. The idea is to rather add our local modifications packaged as patches here rather than full CVS-tracked changes.
  Patches can be disabled by renaming INSTALL into INSTALL.disabled (or anything other than INSTALL). INSTALL will be called in the twiki install dir with 2 arguments: the patch dir and the install dir. Documentation of the patches should be in a README.txt file, or can just be comments in the INSTALL file

• utils are scripts used to help development, testing, deployment of twiki in thiw twde system. They are run under the developper ID, and will not be installed on the web site.

• plugins are the plugins to be installed from the ones available in $TWIKI_FREETOWN_DIST/twikiplugins dir Each plugin XxxPlugin is just a directory, that can contain files overriding the ones in twiki/twikiplugins/XxxPlugin/lib/TWiki/Plugins/XxxPlugin namely:
  • MANIFEST the list of files of this plugin, one per line of the form
    path/file mode comment
  • DEPENDENCIES in the cpan form:
    perl::module,>=version,repository,comment
  • PREINSTALL script to run before install
  • POSTINSTALL script to run after install
  • PREUNINSTALL script to run before removing files to uninstall
  • POSTUNINSTALL script to run after removing files to uninstall
  • REMOVE if present will force the remove of the plugin if installed

• Thus, for most plugins, an empty XxxPlugin dir here would suffice. We recommend moving the Plugin_installer scripts that are added on the twiki.org web site here instead of storing them on twiki/twikiplugins.
  Note that the list of available plugins (with URLs and versions) can seen at TWIKI_URL/bin/configure?action=FindMoreExtensions but be careful not install by this web page, as it will fail.

Usage

deploy scripts below will install twiki, but also automatically configure it with decent defaults, enable automatically newly installed plugins, check plugins and CPAN dependencies, and provide complete removal of plugin files

twiki-deploy-local deploying on a local twiki site:

USAGE: twiki-deploy-local [options] INSTALL-DIR
For Freetown version (4.2.x)
install a TWiki distrib into the directory INSTALL-DIR
This script must be called from a working dir of CVS or SVN repository
exemple: ./utils/twiki-deploy-local -s wiki.ilog.fr -u / /www/wiki
options:
   -s server-name   defaults to  $HOSTNAME.
   -i               force rebuild of config files
   -u url-dir       the base URL of the wiki will be http://server-name/url-dir
                    defaults to the last component of INSTALL-DIR
   -e admin_email   email admin. defaults to $USER@$HOSTNAME
   -d distrib       a directory with 2 subdirectories: 
                    MAIN the TWiki official distribution
                    twikiplugins the MAIN/twikiplugins mirror of the twiki SVN
                    It can be  a directory or a string XXX if you have 
                    a directory ~/.twiki_XXX_dist
-s, -u, -e are only needed on first invocation or with -i
the PATH is set to /bin:/usr/bin, and /usr/local/bin-safe if it exists

twiki-deploy-remote deploying on a remote twiki site:

this will first install a working directory next to the destination twiki site, (via rsync to speed up updates), and perform a twiki-deploy-local there.

twiki-deploy-remote [options] [INSTALL-LOGIN@]INSTALL-HOST:INSTALL-DIR
For Freetown version (4.2.x)
install a TWiki distrib into the directory INSTALL-DIR on host INSTALL-HOST
under the login INSTALL-LOGIN (defaults to current one).
This script must be called from a working dir of a CVS or SVN distrib
exemple: ./utils/twiki-deploy-remote webcore@wiki.ilog.fr:/www/wiki
options:
   -s server-name   defaults to INSTALL-HOST
   -i               force rebuild of config files
   -u url-dir       the base URL of the wiki will be http://server-name/url-dir
                    defaults to the last component of INSTALL-DIR
   -e admin_email   email admin. defaults to $USER@$HOSTNAME
   -t tempdir       temporary directory used on the remote machine to perform
                    the actual installation via ./utils/twiki-deploy-local
                    defaults to INSTALL-DIR.INSTALL-LOGIN.setup
-s, -u, -e are only needed on first invocation or with -i
The script copies the needed files onto tempdir, then performs in it a 
./utils/twiki-deploy-local [options] INSTALL-DIR

-- Contributors: ColasNahaboo - 31 Jan 2008

Discussion

Note that you can get the latest version of this system directly from my Mercurial repository at http://hg.colas.nahaboo.net/twiki-colas/twde/ just click on the bz2 or gz grey buttons at the top to download a complete bzip-ed or gzip-ed tar archive.

-- ColasNahaboo - 08 Feb 2008