$Id: UPGRADE.txt,v 1.13 2005/04/18 16:38:44 mdruilhe Exp $


  =============================================================================

			Release notes for w-agora 4.2
  
  =============================================================================

=============
 I  CHANGES
=============

  * main changes in this version : 4.2.0
  --------------------------------------

  This release includes several changes in the database structure:
	- New fields added to the users, userforum tables
	- new tables added for the statistics/log management
	- new menus table (reserved for custom use)
  All database changes will be applied to your existing release by running the upgrade script.
  
  Notice that the upgrading script doesn't make any change to your online templates, as a result, if you want 
  to take advantage of some new features, you will have to edit your templates, using the admin panel.
  The following features need templates updates:
	- auto-login feature (keepalive cookie) : add {keepalive_checkbox} in your login_form template
	- threads un-subscription : add {subscribe_threads_list} to your subscribe_form template
	- let user upload / choose an avatar : the folowing variables can be used in your register_form template:
		- {label_avatar} : localized text  LABEL_AVATAR;
		- {show_picture} : the current avatar set by the user
		- {label_change_avatar} : localized text LABEL_CHANGE_AVATAR
		- {choose_picture_field} : field / button to choose/upload an avatar

  * NOTES / KNOWN BUGS

  - statistics: currently, statistics functions have only been tested with mysql, and willprobably  not work 
  with other RDMBS. This will be fixed in a next update.

  - wysiwyg editor: As of w-agora 4.2 htmlarea (the HTML WYSIWYG editor) is no longer included in the distribution, 
  although it is still supported by w-agora. As a result:
	- If you are running a previous version that includes htmlarea, there will be no change on this
	- If you are installing w-agora for the 1rst time and want htmlarea support, you must get the software
	from the htmlarea website (http://www.dynarch.com/projects/htmlarea/)

  - Problem downloading attachments: By default, w-agora uses the PATH_INFO variable in order to uses 
  friendly URLs for the attachments. If for some reason this is not working properly, you can change the 
  variable $use_pathinfo in the globals.inc file:
  $use_path_info = 0;

  - In order to use the thread sorting feature you can add the 'sort' parameter to your list.php url. 
  eg: list.php?sort=thread,d
  In addition, the default sort order can be defined in the globals.inc file, eg:
  $default_threads_order = "newest DESC";	// sort by Last posting date
  $default_threads_order = "thread DESC";	// sort Reverse thread starting date


                     Please, read the ChangeLog file for more details.
                     -------------------------------------------------

============================
 II  MIGRATING INSTRUCTIONS
============================

  Before installing the new package, you can check your current version by calling :
  http://www.yoursite.com/w-agora/index.php?about

  -------------------------------------------
  II.1. Migrating from 4.1.x version to 4.2
  -------------------------------------------
  1. As usual, backup your old w-agora installation (both the w-agora tree and the database)

  2. Unpack the new w-agora distribution over the current installation (see the README)
  All your existing settings (configuration, templates) will be preserved, since they are stored into 
  directories that are empty in the distribution. Notice that it doesn't apply to the globals.inc file, 
  so if you did changes to this file in your previous release, you will have to edit it again.

  3. Depending on your previous w-agora version, you may have to run the following upgrade scripts:

     w-agora_dir/tools/upgrade_412.php3 (4.1.1 -> 4.1.2)
     w-agora_dir/tools/upgrade_413.php3 (4.1.2 -> 4.1.3)
     w-agora_dir/tools/upgrade_42.php3  (4.1.3+ -> 4.2)
     
     Read the instructions below :
  
     - Upgrading 4.1.3 and greater => 4.2
     --------------------------------------
     run the script tools/upgrade_42.php3.
     eg. (read the NOTICE below) :
     http://www.yoursite.com/w-agora/tools/upgrade_42.php 

     - Upgrading 4.1.2 or 4.1.2a => 4.2
     ------------------------------------
     you will first have to run upgrade_413.php first and AFTER THAT you can run the upgrade_42.php script 
     to upgrade your database to the latest format.
     eg. (read the NOTICE below) :
     http://www.yoursite.com/w-agora/tools/upgrade_413.php 
     http://www.yoursite.com/w-agora/tools/upgrade_42.php 

     - Upgrading 4.1.0 or 4.1.1 => 4.2
     ---------------------------------
     you will first have to run the following migrations scripts in that order (see the Notice below )
     http://www.yoursite.com/w-agora/tools/upgrade_412.php 
     http://www.yoursite.com/w-agora/tools/upgrade_413.php
     http://www.yoursite.com/w-agora/tools/upgrade_42.php 

  
  -------------------------------------
  II.2  Migrating from 4.0.x versions :
  -------------------------------------

  If you are running old versions of w-agora4 (4.0b1 to 4.0.3), you should not 
  have any difficulty to run w-agora 4.2

  1. As usual, backup your existing installation (both the w-agora tree and the database)

  2. untar the package over the current installation (see the README)

  3. run the following migrations scripts in that order (see Notice(*) )
	tools/upgrade_401.php3 (versions older than 4.0.1)
	tools/upgrade_402.php3 (versions older than 4.0.2)
	tools/upgrade_403.php3 (versions older than 4.0.3)

	tools/upgrade_410.php3 (4.0.3 -> 4.1.0)
	tools/upgrade_412.php3 (4.1.1 -> 4.1.2)
	tools/upgrade_413.php3 (4.1.2 -> 4.1.3)
	tools/upgrade_42.php3  (4.1.3+ -> 4.2)

  For example: if you were previously running v4.0.2a, you have to run IN THAT ORDER:
        upgrade_403, upgrade_410, upgrade_412, upgrade_413, upgrade_42

  * NOTICE
  --------
  For security reason the tools/ directory is protected against unauthorized WEB access.
  This is done using a .htaccess file located in that directory.
  Either edit or rename the .htaccess before running the scripts from this directory.


  -------------------------------------
  II.3  Migrating from versions 3.0.x :
  -------------------------------------
  This release is almost a complete rewrite of w-agora 3.0 and is not full compatible
  with existing installations of w-agora 3.0.

  Certainly, the best way would be to reinstall w-agora 4 from scratch.

  Nethertheless you should be able to migrate your existing forums, assuming you already 
  have w-agora 3 running over a mysql/postgres database.

     o Migrating mysql / postgres forums :
     -------------------------------------

  Here is the steps that you should follow.

  - export your database using mysqldump (or similar)
  - remove all the w-agora tables
  - backup your existing w-agora installation
  - install the new package, then recreate empty forums with the same names and settings
  - import the saved tables in the appropriate new created tables

     o Migrating DBM forums :
     ----------------------

   Obviously, you should have mysql or postgres enabled and running at your website.

   Here is some suggestions

   1. Create a new postgreSQL/mysql site / forum using w-agora 3.x 
     (DO NOT use 'agora' as site name but whatever you want)
   2. Copy your DBM forum to you newly created (mysql/postgres) forum using the 
   export script located in extras/copy_forum.php3
   3. Dump/export your table using a postgres/mysql tool
   4. Install w-agora 4.0 (setup, create site, create forum)
   5. Import your old forum in the newly created table.
