UPGRADING

    Upgrading from one version of TWIG to another falls in to three categories:

	- sub point releases (x.y.?, eg. 2.1.1)
	- point releases     (x.?.0, eg. 2.2.0)
	- major releases     (?.0.0, eg. 2.0.0)

    For all of the above you will want to get the TWIG distribution file and 
    extract it to a temporary directory that you can work with.

    Like any upgrade, make sure you back up your data and software before 
    starting, there have been no instances of major problems with TWIG 
    upgrades but making sure you can back out the changes is sound 
    administrative practice.

    Since the setup/upgrade directory structure has proved to be a bit 
    confusing to new TWIG users, here is a quick break down:

	- You only need to use the SQL upgrade scripts when moving from
	  one point release to another (ie. from 2.1.0 to 2.2.0) never
 	  use these scripts when upgrading between sub point releases
 	  (ie. 2.1.0 to 2.1.1).

	- When a new point release is completed, the SQL upgrade scripts
  	  from the last release are moved in to a sub directory labeled
	  as the previous release (ie. when 2.2.0 was released a directory
 	  called setup/upgrade/2.1.0 was created to hold the old SQL 
 	  scripts).

	  This is done so that if you wish to upgrade from an older 
	  version of twig (ie. from 2.0.1 to 2.2.0) you only need the
	  2.2.0 archive, not the 2.1.0 and 2.2.0 archives.

	- The SQL scripts in setup/upgrade will only take you from the last
	  point release to the next point release, if you are upgrading from
 	  more than one point release difference then you will need to apply
	  multiple SQL scripts in order to accomplish the upgrade.

	  For example, if you are upgrading from 2.0.1 to 2.2.0 you would
	  have to first apply setup/upgrade/2.1.0/twig.table-upgrade.xxx
	  and then apply setup/upgrade/twig.table-upgrade.xxx.

	  Or if you are upgrading from 1.0.3 to 2.2.0 you would need to 
 	  first apply setup/upgrade/2.0.0/twig.table-upgrade.xxx, then
	  setup/upgrade/2.1.0/twig.table-upgrade.xxx and finally
	  setup/upgrade/twig.table-upgrade.xxx.

SUB POINT RELEASE

    Sub point releases are the easiest to upgrade, they tend to be bug fixes 
    or minor feature additions.

    There are two ways you can upgrade these releases, either by downloading
    full package and making any required changes to the config file, or you 
    can download the patch and apply it:

	patch -p1 < twig-2.1.1.diff

    You should extract the patch to the root directory of the copy of TWIG you
    want to patch and run the above command from the same directory.

    In general it is recommended that you get the full release since any changes
    changes to binary files (like gif files) will not be reflected in the 
    patch.

    Sub point releases NEVER make changes to the databases and you will not 
    need to run any SQL scripts.

POINT RELEASE    

    Point releases tend to make major changes in a feature or require changes
    to the database files that make these upgrades more difficult.

    While patch files are supplied for these releases, their use is discouraged
    and are primarily supplied for consistency in the release cycle.

    Since major changes may have happened it is recommended that you test point
    releases before implementing them on your production servers.

    When you are ready to upgrade your production environment, do the following
    steps:

	- ensure that no one is on the system
	- BACKUP your data and TWIG installations
	- apply the db changes as found in setup/upgrade/twig.table-upgrade.xxx
	- install the new TWIG code base
 	- update the new configuration files as required

    NOTE: The upgrade scripts upgrade the database tables in place, they do not
    make copies or backup any data.

MAJOR RELEASES

    Major releases tend to be complete rewrites of the underling structure of 
    TWIG and by definition will require specific instructions to the upgrade.
    However since there have only been two of these releases in TWIG's history
    (0.3.0 and 2.0.0) and there are no plans at this time for any more, this
    section is left pretty much empty.