Upgrade Instructions
********************

A KForge environment may need to be upgraded before it can be used with a new 
version of KForge.

NB: environment upgrades are not required between minor upgrades, i.e. from
a.b.x to a.b.y, unless specially noted.

From 0.11 to 0.12
=================

Preliminaries
-------------

  1. Stop site that is running on KForge
  2. [recommended] Backup (for help run $ kforge-admin backup help)

Upgrade the KForge system
-------------------------

  1. [recommended] Remove existing system
  2. Install new one (see instructions in INSTALL)

    * There are some major changes in the package structure in KForge 0.12 so
      this step is absolutely essential.
    * In particular, KForge 0.12 core code has been factored out into a
      separate package called domainmodel which you will need to install
      separately and the version of Django we use has been updated to the most
      recent available stable release (0.95). Please see the INSTALL file for
      full details.

Upgrade Environment
-------------------

In this release we have changed the configuration setup.

1. Create a new configuration file (follow instructions in INSTALL)

  * **do not** just copy across your old file start but rather copy the
    template and then modify it
  * note that we no longer use the KFORGEHOME environment variable but instead
    use a variable called KFORGE_SETTINGS which should point to your
    configuration file.

Finally
-------

  1. Rebuild webserver configuration
    $ bin/kforge-admin www rebuild
  2. Restart service (restart/reload webserver)
    $ bin/kforge-admin www reload

From 0.10 to 0.11
=================

Let <kforgehome> be the location of the KForge environment you are upgrading
Let <kforgesystem> be the location of the KForge system

Preliminaries
-------------

  1. Stop site that is running on KForge
  2. [recommended] Backup (see bin/kforge-admin backup help for details)

Upgrade the KForge system
-------------------------

  1. [recommended] Remove existing system
  2. Install new one (see instructions in INSTALL)

Upgrade Environment
-------------------

This upgrades involves upgrading the configuration file so it must be broken
into two steps.
  
  1. Upgrade data: $ bin/kforge-admin upgrade data
    * this will install the new configuration file at <base>etc/kforge.conf
    and leave your old configuration file in kforge.conf.old 
    * if you have made changes to your configuration file (as is likely) you
    will need to merge these changes in by hand
  2. Upgrade db
    $ bin/kforge-admin upgrade db

Finally
-------

  1. Rebuild webserver configuration
    $ bin/kforge-admin www rebuild
  2. Restart service (restart/reload webserver)
    $ bin/kforge-admin www reload


From 0.9 to 0.10
================

Let <kforgehome> be the location of the kforge environment you are upgrading

  0. Stop site that is running on KForge
  1. Backup: $ bin/kforge-backup <backup-dir>
  2. Update the KForge code
    * First remove existing code: $ rm -Rf <kforghome>/lib
    * Install new code: $ python setup.py install --home <kforgehome>
  3. Upgrade configuration
    * cd <kforgehome>
    * backup original: $ mv etc/kforge.conf etc/kforge.conf.old
    * install new: mv etc/kforge.conf.new etc/kforge.conf
    * edit new to integrate old configuration data
  4. Run upgrade script to update database
    * $ bin/kforge-upgrade
  5. Rebuild configuration:
    * $ bin/kforge-config-rebuild
  6. Restart service (restart/reload webserver)

Pre 0.9
=======

Upgrading from pre-0.9 versions are not supported.

From GForge to KForge
=====================

See bin/kforge-gforge-migrate.py

This is rather rough and ready code and and will only migrate a restricted set
of data (see file comments for details). It has been successfully used to
migrate a GForge 4.0 track database to KForge 0.9.