Preliminary Upgrade-Instructions
================================

This document describes the Phorum upgrading process. Please keep in mind, 
that these instructions are neither complete, nor final. If you find
problems in upgrading which are not described here or if you have 
useful additions, please let us know.

Table of contents:

1. Upgrading from a Phorum5 version to another Phorum5 version
   1.1 Upgrading the database
   1.1.1 Preparations
   1.1.2 From a webbrowser
   1.1.3 From a system console
   1.2 Upgrading templates and hacks
2. Upgrading from Phorum 3.4.x to Phorum5


1. Upgrading from a Phorum5 version to another Phorum5 version
-------------------------------------------------------------------------------


 1.1 Upgrading the database
 --------------------------


  1.1.1 Preparations
  -----------------------

   The upgrading process will preserve all of your active settings and
   modules, but will overwrite hacks and any changes made to the default
   template (in the directory {phorum dir}/templates/default). Other
   templates will be kept intact.

   Here are the steps for upgrading:

   - Backup your existing Phorum5 installation.
     Before doing an upgrade, it is always wise to make a good backup
     of your running system. Make a backup your Phorum install directory 
     and the database in which your Phorum tables are stored;

   - Download a newer Phorum5 package;
   
   - Extract the files and put them on top of the current installation;
   
   - Keep the database settings from {phorum dir}/include/db/config.php 
     the same;

   Now you can choose whether you want to upgrade from a webbrowser or 
   from a console. 


  1.1.2 From a webbrowser
  -----------------------
   
  Open your forum using your webbrowser. In case a database upgrade 
  is needed, you will be prompted to go to the admin page. In that case 
  open the {phorum url}/admin.php page, which will guide you through 
  the upgrade.


  1.1.3 From a system console
  ---------------------------

  In the scripts directory of your Phorum installation, you will find
  the script "console_upgrade.php". Go to the scripts directory and
  execute the script from there. On most systems, you can do this using
  the following command:

     # php console_upgrade.php

  If you want to run this script from a different locations, then edit
  the script and update the $PHORUM_DIRECTORY variable to match the
  location of your Phorum installation.


 1.2 Upgrading templates and hacks
 ---------------------------------
   
   For minor upgrades, the Phorum team has the policy that templates
   should not change. For example, if you are upgrading version 5.1.1
   to 5.1.2, you can simply keep the old templates.

   Template functionality might change between major Phorum releases.
   For example, templates that were made for Phorum 5.0.x are not
   compatible with the templates for Phorum 5.1.x. So to upgrade these,
   you'll have to build new templates, based on the new default template
   that is included in the distribution. Simply copying the old template
   will most probably result in errors and missing functionality.
   
   If you are doing a minor upgrade and you have to preserve changes that
   were made to the default template (which is not the recommended way
   of customizing Phorum, see creating_templates.txt), you can follow one
   of the following options:
   
   - Extract the new Phorum distribution to its own directory and reapply 
     your changes before putting it over the existing installation;
     
   - Create a backup of your existing installation. Install the new
     distribution on top of the old one and reapply the changes to 
     the new version while it is "live".
   

2. Upgrading from Phorum 3.4.x to Phorum5
-------------------------------------------------------------------------------

   - Download and unpack the Phorum5 package;
   
   - Follow the installation instructions in docs/install.txt. Install 
     Phorum5 is a new directory. 
   
   - Convert the old forum data:
   
     In the scripts directory of your Phorum5 distribution, you will find
     a script named phorum3to5convert.php. Instructions for using this
     script can be found at the top of this script itself. The script will
     convert your old forum to Phorum5. Everything, but permission levels,
     is converted.
   
   - Update the posted message counters for the users:
   
     In the scripts directory, you will also find a script named
     "update_postcount.php". This script can be used to update the number
     of posts for users to the right value. So if you want correct numbers
     to show up in the user profiles, just run this script once AFTER the
     conversion has been completed. To run it, you will have to copy it
     over to the main Phorum5 directory. After that you can either run
     it from the command line or by opening it from your webbrowser. See
     also the instructions in the script itself.