---+ 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 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 depolyed 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.
     <br> 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
	<br> =path/file mode comment=
      * =DEPENDENCIES= in the cpan form:
	<br> =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 instaed of storing them on 
     twiki/twikiplugins.
     <br> 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:

<verbatim>

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
</verbatim>

---+++ twiki-deploy-local 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.

<verbatim>
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

</verbatim>
