	##############################################
   ### MySource ------------------------------###
  ##- Upgrading Instructions -----------------##
 #-- Copyright Squiz.net ---------------------#
##############################################

Herein lie instructions for upgrading one version of MySource to the
next.

====
Note
====

To be safe, you should always delete every file in your cache
directory after upgrading MySource. You may also need to manually
reparse your site designs if there have been changes to the way
these are processed.

==============
2.3.9 or 2.4.x
==============

Refer to the "2.2.x to 2.3.9" section for the usual  upgrading
instructions. Following this there are some special changes
between 2.3.9 and 2.4.x

The way MySource logs error and hit/visit statistics for pages
has changed between versions 2.3.9 and 2.4, and will not log
these by default. See the section "About Hit and Error Logging"
in the INSTALL file for information on how to setup your system
correctly.

When performing this upgrade, be sure to log in before starting
and keep your cache directory intact while running the upgrade
script. If your session file is lost you will not be able to
log in again due to a change to the user database. If everything
goes wrong, you can manually repair the database with the
MySQL command:

ALTER TABLE user ADD COLUMN created_date date NOT NULL AFTER web_status;

==============
2.2.x to 2.3.9
==============

To upgrade from MySource version 2.2.x to any MySource version
2.3.x (BETA) or 2.4.x (Stable), extract the new tgz over the
top of your MySource directory; or extract it to a different
one and copy your conf and data folders over, after which you
will need to reconfigure Apache to point to the new folder.

Visit the .../_edit/upgrade_2.2.0_2.4.0.php script in your web
browser before doing anything else. You will need to be logged in as
root. This script should handle any housekeeping for you.

Note that you can do partial upgrades from, for example, 2.3.4
to 2.3.9 - however you will see database errors when running the
upgrade script. These errors are simply due to the system being
already partially upgraded from version 2.2.x - you do not need
to worry about them.


==============
2.0.2 to 2.2.0
==============

To upgrade from MySource version 2.0.2 BETA to version 2.2.0, either
extract the new tgz over the top of your MySource directory; or
extract it to a different one and copy your conf and data folders
over, after which you will need to reconfigure Apache to point to
the new folder.

Visit the .../_edit/upgrade_2.0.2_2.2.0.php script in your web
browser before doing anything else. You will need to be logged in as
root. This script should handle any housekeeping for you.


==============
0.9.5 to 2.0.2
==============

For the upgrade from MySource 0.9.5 to 2.0.2 (there were no public 
releases between these two versions) an upgrade script has been included 
to make life easier for you.

This release involves a number of database  and files system changes to 
accomodate certain new features including:

    * Reorganised data/ directory, maintaining security but increasing 
    response time.
	* Page status logging and the ability to schedule 
    page status changes into the future.
	* Added functionality to the 
    Custom Form and Redirect page templates, as well as all-new Pull 
    Content template.

Create a new directory outside your existing MySource directory and 
xxtract the TGZ file into it. From your existing MySource directory copy 
the 'cache', 'conf' and 'data' directories into your new one. If you 
can, dump your MySQL database(s) to a file, for backup purposes; in case 
this upgrade just isn't for you. You shouldn't need it though, don't 
worry. To dump a MySQL database:

mysqldump -u <user> --password=<password> <db_name> >  backup.sql

You can find the values of <user>, <password> and <db_name> in your 
conf/mysource.conf file, or by looking in the Config tab in the backend.

Alter your Apache configuration, or symlinks, so that you can access the 
new MySource directory in a web browser rather than the old one. Try to 
avoid *actually* accessing it (unless you want to see a pile of ugly red 
errors), and just got straight to the upgrade script:

http://myhost/path/to/mysource/_edit/upgrade_0.9.5_2.0.2.php

..or equivilant. This will require you to log in as root - hope you 
remember that root password! It will also remind you to back up your 
system, which if you've followed these instructions you already have 
(since you dumped the database and copied the 'data' directory). Hit Yes 
and sit patiently while the script gets your database and file system up 
to scratch. When it is finished, hit the link and you should find 
yourself in your backend. Don't run that script again.

Now there are a few more details left to organise. Part of performance 
improvements in the new release come from fewer files being piped 
through MySource and being instead sent directly by Apache.

This is where the process splits in two. If you ARE using MySource's 
Virtual Paths feature and have set up AliasMatch lines in your Apache 
configuration file (see INSTALL), you will need to add three more before 
MySource 2.0.2 will function correctly. If you have, for example:

AliasMatch "^/steve/mysource_test(/.*)?/_edit(.*)$" 
"MYSOURCE_PATH/web/edit$2" AliasMatch "^/steve/mysource_test(/.*)?$" 
"MYSOURCE_PATH/web/index.php"

in your httpd.conf, change this to:

AliasMatch "^/steve/mysource_test(/.*)?/__lib(.*)$" 
"MYSOURCE_PATH/web/__lib$2" AliasMatch 
"^/steve/mysource_test(/.*)?/__squizlib(.*)$" "MYSOURCE_PATH/squizlib$2" 
AliasMatch "^/steve/mysource_test(/.*)?/__data(.*)$" 
"MYSOURCE_PATH/data/unrestricted$2" AliasMatch 
"^/steve/mysource_test(/.*)?/_edit(.*)$" "MYSOURCE_PATH/web/edit$2" 
AliasMatch "^/steve/mysource_test(/.*)?$" "MYSOURCE_PATH/web/index.php"

The __data (note: two (2) underscores (_'s)), __squizlib and __lib 
aliases allow browser direct access to public content: that is, public 
site designs, files attached to live, public pages, and common files 
that come with MySource.

If you ARE NOT using AliasMatching, and simply have a symlink pointing 
to your web directory, you will need to set up some more symlinks.

[Note: if you are no using AliasMatching OR Symlinks and simply have 
your MySource directory in the DocumentRoot you are invalidating 
MySource's security settings, granting people access to your entire data 
directory, whether the data is restricted or not. MySource v2.0.2 cannot 
function without the use of AliasMatching or symlinks.]

Set up the symlinks (relative to the MySource root) 'web/__squizlib' 
pointing to 'squizlib' and '__data' pointing to 'data/unrestricted'. 
E.g.:

[/home/mysource]$ cd web [/home/mysource/web]$ ln -s ../squizlib 
__squizlib [/home/mysource/web]$ ln -s ../data/unrestricted __data

__lib will take care of itself.

And that's it! Your new MySource system should be functioning like 
normal. Be sure to organise your Apache configuration or linking so that 
your new system appears at the old URLs.


==============
0.9.4 to 0.9.5
==============

There are two major changes that need to be taken into account when
upgrading from MySource 0.9.4 to 0.9.5: the new menuing system; and
the new internationalisation options.

You can extract MySource 0.9.5 over the top of your old version; but
you must ensure your database is upgraded. To do this, open
db/web_ChangeLog.sql  You'll notice there is an entry for the upgrade
from 0.9.4 to 0.9.5. Simply copy these lines and paste them into your
MySQL client - make sure you are currently using your MySource web
database.

You must then reparse your site design. This is because of changes to
the menuing system. If you're using the sample designs, simply upload
the appropriate parse.html from the doc/samples/site_design directory
into the Web -> Designs section of the backend.

==============
0.9.3 to 0.9.4
==============

The upgrade from 0.9.3 to 0.9.4 is insigificant, data-wise - involving
mostly interface enhancements and bug fixes. However, there have been
improvements to the site design areas that are not completely
backwards-compatible.

You will need to recreate your site design, or create a new one. Use
the ferns_gif design if you want it to work in Netscape 4, or the PNG
one if you hate GIFs. You can safely extract the tgz over the top of
a 0.9.2 or .3 installation. To upgrade from an earlier 0.9x version,
see the 0.9.1 to 0.9.2 section.

==============
0.9.2 to 0.9.3
==============

The upgrade from 0.9.2 to 0.9.3 is trivial, involving only a number of
important, but not drastic bug fixes. You can safely extract the tgz
over the top of a 0.9.2 installation. To upgrade from an earlier 0.9x
version, see the 0.9.1 to 0.9.2 section.

==============
0.9.1 to 0.9.2
==============

There have been some changes to the web database between these
releases. After unpacking the tgz file over your old MySource
directory, you can  get rid of those pesky error messages, by looking
in the the file db/web_ChangeLog.sql. Here you will find the
appropriate SQL commands to upgrade the web database.

To utilize Virtual Paths you will need to enable it under the Config
tab and then create appropriate labels for all your pages. Don't
worry, any pages you create from then on will have virtual paths
assigned to them automatically.

==============
0.9 to 0.9.1
==============

To upgrade MySource from version 0.9 to 0.9.1 all you need do is
unpack the tgz file over the top of your existing MySource
directory.
 
 
