Update the UPGRADE docs; adapted information I placed on MediaWiki.org, and link to a MediaWiki 1.5 -> 1.6 specific guide1.6.1

1 files changed, 71 insertions, 20 deletions

diff --git a/UPGRADE b/UPGRADE
index ece64ecadf4b..bec8c55002b1 100644
--- a/UPGRADE
+++ b/UPGRADE
@@ -1,31 +1,83 @@
-== The basic theory ==
+This file provides an overview of the MediaWiki upgrade process. For help with
+specific problems, check
 
-Generally, within a stable release series (e.g. 1.4.0, 1.4.1, etc) there
-are no required database changes, and upgrading should require no more
-than copying the new source files over the old ones.
+* the documentation at http://meta.wikimedia.org
+* the documentation at http://www.mediawiki.org
+* the mediawiki-l mailing list archive at
+  http://mail.wikipedia.org/pipermail/mediawiki-l
+* the bug tracker at http://bugzilla.wikimedia.org
 
-If there are larger changes, such as upgrading from one release series
-to another (e.g. from 1.3.12 to 1.4.3), then you may need to update the
-database schema and configuration.
+for information and workarounds to common issues.
 
-Basically, to upgrade a wiki you:
-* Back up your data! (See Backups! below)
-* Extract the new archive. If you can do this in a clean directory that's
-  great, but it should work to extract over the old files too. This may
-  be easier if you have images etc in place and don't want to move them
-  around, but remember to back up first!
-* Run the installer to upgrade the database schema (if necessary,
-  see sections below for details).
+== Overview ==
 
+* Documentation on upgrading from 1.5 to 1.6 can also be found at
+http://www.mediawiki.org/wiki/Help:Upgrading_to_1.6
 
-== IMPORTANT: Upgrading to 1.5 ==
+=== Consult the release notes ===
+
+Before doing anything, stop and consult the release notes supplied with the new
+version of the software. This detail bug fixes, new features and functionality,
+and any particular points that may need to be noted during the upgrade
+procedure.
+
+=== Backup first ===
+
+It is imperative that, prior to attempting an upgrade of the database schema,
+you take a complete backup of your wiki database and files and verify it. While
+the upgrade scripts are somewhat robust, there is no guarantee that things will
+not fail, leaving the database in an inconsistent state.
+
+Refer to the MySQL documentation for information on backing up a database. For
+information on making copies of files, consult the documentation for your
+operating system.
+
+=== Perform the file upgrade ===
+
+Having downloaded the desired new version of the software, either as a package
+from SourceForge, or via an export from Subversion, decompress the files as
+needed, and replace the existing MediaWiki files with the new.
+
+You should preserve:
+
+* The LocalSettings.php file
+* The AdminSettings.php file, where it exists
+* The extensions directory
+* The images directory
+
+If using an alternative uploads directory, preserve this; and if using custom
+skins, preserve these too. The core code is now updated.
+
+=== Perform the database upgrade ===
+
+You will need an AdminSettings.php file set up in the correct format; see
+AdminSettings.sample in the wiki root for more information and examples.
+
+From the command line, browse to the maintenance directory and run the 
+update.php script to check and update the schema. This will insert missing
+tables, update existing tables, and move data around as needed. In most cases,
+this is successful and nothing further needs to be done.
+
+=== Check configuration settings ===
+
+The names of configuration variables, and their default values and purposes,
+can change between release branches, e.g. $wgDisableUploads in 1.4 is replaced
+with $wgEnableUploads in later versions. When upgrading, consult the release
+notes to check for configuration changes which would alter the expected
+behaviour of MediaWiki.
+
+=== Test ===
+
+It makes sense to test your wiki immediately following any kind of maintenance
+procedure, and especially after upgrading; check that page views and edits work
+normally and that special pages continue to function, etc. and correct errors
+and quirks which reveal themselves.
+
+== Upgrading from pre-1.5 wikis ==
 
 Major changes have been made to the schema from 1.4.x. The updater
 has not been fully tested for all conditions, and might well break.
 
-DO NOT ATTEMPT TO UPGRADE A LIVE, PUBLIC SITE TO 1.5 AT THIS TIME.
-NEVER EVER ATTEMPT TO PERFORM AN UPGRADE WITHOUT BACKING UP FIRST!
-
 On a large site, the schema update might take a long time. It might
 explode, or leave your database half-done or otherwise badly hurting.
 
@@ -47,7 +99,6 @@ Message changes:
 * A number of additional UI messages have been chagned from HTML to
   wikitext, and will need to be manually fixed if customized.
 
-
 === Configuration changes from 1.4.x: ===
 
 $wgDisableUploads has been replaced with $wgEnableUploads.