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.12 to 0.13
=================

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)

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

  1. Upgrade the database: $ kforge-admin upgrade db
  2. Upgrade data files: $ kforge-admin upgrade data

In this release we have moved to a single host setup for KForge. We have also
reworked the apache configuration generation so that rather than generating a
full virtual host it only generates the configuration needed by KForge. This
allows a user more flexibility in incorporating KForge in their existing apache
setup. The simplest way to upgrade is as follows:

  3. Backup your existing KForge apache configuration.
    * Remove any symlinks which pointed to this config file.
  4. Generate a new KForge apache config: $ bin/kforge-admin www rebuild
  5. Create a new vhost apache config for your KForge site (you might want to
     base this on the admin vhost config in your old kforge file backed up in
     step 3).
  6. Use an apache Include directive to include the new 
    * If you would like backwards compatibility with your old setup (i.e. so
      all the old urls still work) just use a ServerAlias e.g.
      
      ServerName kforge.mydomain.com
      ServerAlias admin.kforge.mydomain.com project.kforge.mydomain.com

Finally
-------

  1. Restart service (restart/reload webserver)


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.
