Add XFILE to allow for more than one source file, add float as valid mysql type.

[lhc/web/wiklou.git] / UPGRADE

diff --git a/UPGRADE b/UPGRADE
index 07767be..70ccbad 100644 (file)
--- a/UPGRADE
+++ b/UPGRADE
@@ -1,43 +1,111 @@
-== 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).
+== Overview ==

 
 

+Documentation on upgrading to 1.7 can also be found at
+http://www.mediawiki.org/wiki/Manual:Upgrading_to_1.7.

 
 

-== 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 1.6 wikis ==
+
+$wgLocalTZoffset was in hours, it is now using minutes.
+Link autonumbering got fixed (#5918) for protocols other than http.
+ - 'irc://irc.server.tld/' render as a link with a chat icon
+ - '[irc://irc.server.tld]' render as an autonumbered link: [1]
+
+== 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.
 
 
 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.
 
 Among other changes, note that Latin-1 encoding (ISO-8859-1) is
 no longer supported. Latin-1 wikis will need to be upgraded to
 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.
 
 Among other changes, note that Latin-1 encoding (ISO-8859-1) is
 no longer supported. Latin-1 wikis will need to be upgraded to

-UTF-8, however the updater has not yet been updated to support
-this automatically.
+UTF-8; an experimental command-line upgrade helper script,
+'upgrade1_5.php', can do this -- run it prior to 'update.php' or
+the web upgrader.
+
+If you absolutely cannot make the UTF-8 upgrade work, you can try
+doing it by hand: dump your old database, convert the dump file
+using iconv as described here: 
+http://portal.suse.com/sdb/en/2004/05/jbartsh_utf-8.html
+and then reimport it. You can also convert filenames using convmv,
+but note that the old directory hashes will no longer be valid,
+so you will also have to move them to new destinations.

 
 Message changes:
 * A number of additional UI messages have been chagned from HTML to
   wikitext, and will need to be manually fixed if customized.
 
 
 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.
 === Configuration changes from 1.4.x: ===
 
 $wgDisableUploads has been replaced with $wgEnableUploads.


@@ -46,11 +114,27 @@ $wgWhitelistAccount has been replaced by the 'createaccount' permission
 key in $wgGroupPermissions. To emulate the old effect of setting:
   $wgWhitelistAccount['user'] = 0;
 set:
 key in $wgGroupPermissions. To emulate the old effect of setting:
   $wgWhitelistAccount['user'] = 0;
 set:

-  $wgGroupPermissions['*'] = array( 'read' ); // without createaccount
+  $wgGroupPermissions['*']['createaccount'] = false;
+
+$wgWhitelistEdit has been replaced by the 'edit' permission key.
+To emulate the old effect of setting:
+  $wgWhitelistEdit = true;
+set:
+  $wgGroupPermissions['*']['edit'] = false;
+
+If $wgWhitelistRead is set, you must also disable the 'read' permission
+for it to take affect on anonymous users:
+  $wgWhitelistRead = array( "Main Page", "Special:Userlogin" );
+  $wgGroupPermissions['*']['read'] = false;

 
 

-If $wgWhitelistRead is set, things need to be funked around. This needs work.
+Note that you can disable/enable several other permissions by modifying
+this configuration array in your LocalSettings.php; see DefaultSettings.php
+for the complete default permission set.

 
 

-bla bla bla
+If using Memcached, you must enabled it differently now:
+  $wgUseMemCached = true;
+should be replaced with:
+  $wgMainCacheType = CACHE_MEMCACHED;

 
 
 === Web installer ===
 
 
 === Web installer ===