* Modified to show most of the changes that were in the Wiki

* Changed some wording around, one command, and added the 1.0.5 preference
  warnings.

git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@1314 7612ce4b-ef26-0410-bec9-ea0150e637f0

diff --git a/UPGRADE b/UPGRADE
index 88463cd6e4cf0b67a27a41eb30cc9fc7e74f32dd..5be5a27d6b32cf58daf47da40702619497a68492 100644 (file)
--- a/UPGRADE
+++ b/UPGRADE
@@ -11,46 +11,84 @@ are not in all versions of PHP4. You will need at least PHP4 beta2. If you
 need to upgrade please go ahead and install the latest release version of
 PHP4.
 
 need to upgrade please go ahead and install the latest release version of
 PHP4.
 

-1.  Backups
-===========
+
+1.  Backup old install
+======================

 
 Make a backup of your current SquirrelMail directory.  If you use "cp", be
 sure to use the "-Rp" options.  -R means recursive, and -p will save the
 
 Make a backup of your current SquirrelMail directory.  If you use "cp", be
 sure to use the "-Rp" options.  -R means recursive, and -p will save the

-permissions in the directory.  In this example, we assume that your httpd
-document directory is /home/httpd/html.
+permissions in the directory.
+
+In this example, we assume that your httpd document directory is 
+/home/httpd/html, that your SquirrelMail install is located at
+/home/httpd/html/squirrelmail-0.4, and that your new SM version is 0.5.
+Substitute version numbers and names as required.

 
   $ cd /home/httpd/html
   $ cp -Rp squirrelmail-0.4 squirrelmail-0.4.bak
 
 
 
   $ cd /home/httpd/html
   $ cp -Rp squirrelmail-0.4 squirrelmail-0.4.bak
 
 

-2.  Unarchives Squirrelmail-0.5.tar.gz
-======================================
-Make sure that you're in your httpd document directory (/home/httpd/html)
-and then unarchive the squirrelmail archive (whatever the filename is): 
+2.  Unarchive new SquirrelMail
+==============================
+Make sure that you are in your httpd document directory (/home/httpd/html)
+and then unarchive the SquirrelMail archive (whatever the filename is): 

 
   $ tar -zxvf squirrelmail-0.5.tar.gz
 
 
 
   $ tar -zxvf squirrelmail-0.5.tar.gz
 
 

-3.  Copy backups in place
-=========================
-Here is the main part.  There are two parts to this step: copy preferences,
-and copy config details.  The preference files are backwards compatible, so
-it is fine to copy the old user preferences into the new directory.
-However, the configuration file has changed quite a bit, so you will want to
-be sure to run the configure script (conf.pl) to set up any new config
-details.
+3.  Copy important files from old install
+=========================================
+The important files to copy are:
+  A.  Preferences
+  B.  Config details
+  C.  Plugins
+  D.  Themes (if you've edited or added any of them)
+  
+A.  Preferences

 
 

-First, copy the files in place:
+First, copy your preference data over to the new directory.  Usually this is
+ok, but if you are upgrading from to 1.0.5 or later from anything less than
+1.0.5, we strongly suggest you let your users reset their preferences.
+There were important security upgrades in 1.0.5 regarding preference files.

   
   $ cp squirrelmail-0.4.bak/data/* squirrelmail-0.5/data
   
   $ cp squirrelmail-0.4.bak/data/* squirrelmail-0.5/data

+  
+B.  Config details
+
+If at all possible, start the configuration process from scratch.  It is 
+much less prone to missing configuration options than copying your old
+configuration.  Ideally, you should just run conf.pl to reconfigure
+SquirrelMail.  If you decide to copy your old config.php over, we strongly
+recommend that you run conf.pl to make sure things are correct and then save
+the config file.
+

   $ cp squirrelmail-0.4.bak/config/config.php squirrelmail-0.5/config
 
   $ cp squirrelmail-0.4.bak/config/config.php squirrelmail-0.5/config
 

-Note that if at all possible, start the configuration process from scratch.
-It is less prone to missing configuration options than copying your old
-configuration.  The ideal solution would be to copy your users' preference
-files, and then run conf.pl to re-configure SquirrelMail (without using the
-old config file).  If you do copy the config.php file, you will want to run
-conf.pl and check for new options.
+C.  Copy plugins
+
+Like SquirrelMail, plugins are fequently updated for improvements, as well
+as to make them compatible with new SquirrelMail releases.  It is suggested
+that you download a new plugins archive at the same time you download your
+SquirrelMail install, and that you install your plugins fresh (it's easy,
+don't panic!).
+
+If you prefer to just copy your old plugins over (if it's the same version
+or if you are lazy), you may do so.  If you notice irregularities with the
+plugins under the new SquirrelMail, try installing new versions of the
+plugins.
+
+  $ cp -Rp squirrelmail-0.4.bak/plugins/* squirrelmail-0.5/plugins
+  
+D.  Copy themes
+
+If you've created or modified themes, you should copy just those to the new
+SquirrelMail themes direcory.  To just copy them all over to the new
+SquirrelMail installation, you can run one command.
+
+  $ cp squirrelmail-0.4.bak/themes/* squirrelmail-0.5/themes/
+
+(While you are at it, you should send them to us!  We might add them to the
+themes in the standard install!)

 
 
 4.  Change permissions
 
 
 4.  Change permissions


@@ -61,10 +99,23 @@ as is often the case with Apache.
 
   $ cd squirrelmail-0.5
   $ chown -R nobody.nobody data
 
   $ cd squirrelmail-0.5
   $ chown -R nobody.nobody data

+  
+See INSTALL for alternate userid/groupid pairs.  Additionally, if "chown
+user.group" doesn't work, you can use "chown user" and "chgrp group"
+instead.  See the man pages for these commands for more information.
+
+
+5.  Run conf.pl
+===============
+Run config/conf.pl to see the new configuration options available with the
+new version, as well as to verify that all of your old options are set
+properly.

 
 
 
 

-5.  DONE!
+6.  DONE!

 =========
 That should be all!  The most important part is copying your users'
 preference files back into the new data directory.  This will insure that
 =========
 That should be all!  The most important part is copying your users'
 preference files back into the new data directory.  This will insure that

-your users will have their old preferences.
+your users will have their old preferences.  Remember to do so with caution,
+especially if you are upgrading from a version before 1.0.5 to version 1.0.5
+or later.