Merge "More parameter stripping tests: nested and single-line"

[lhc/web/wiklou.git] / UPGRADE

diff --git a/UPGRADE b/UPGRADE
index 07767be..46f5e65 100644 (file)
--- a/UPGRADE
+++ b/UPGRADE
@@ -1,111 +1,187 @@
-== The basic theory ==

 
 

-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.
+This file provides an overview of the MediaWiki upgrade process. For help with
+specific problems, check

 
 

-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.
+* the documentation at http://www.mediawiki.org
+* the mediawiki-l mailing list archive at
+  http://lists.wikimedia.org/pipermail/mediawiki-l/
+* the bug tracker at https://bugzilla.wikimedia.org

 
 

-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).
+for information and workarounds to common issues.

 
 

+== Overview ==

 
 

-== IMPORTANT: Upgrading to 1.5 ==
+Comprehensive documentation on upgrading to the latest version of the software
+is available at http://www.mediawiki.org/wiki/Manual:Upgrading.

 
 

-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.
+=== Consult the release notes ===

 
 

-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!
+Before doing anything, stop and consult the release notes supplied with the new
+version of the software. These detail bug fixes, new features and functionality,
+and any particular points that may need to be noted during the upgrade
+procedure.

 
 

-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.
+=== Backup first ===

 
 

-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.
+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.

 
 

-Message changes:
-* A number of additional UI messages have been chagned from HTML to
-  wikitext, and will need to be manually fixed if customized.
+http://www.mediawiki.org/wiki/Manual:Backing_up_a_wiki provides an overview of
+the backup process. You should also refer to the documentation for your
+database management system for information on backing up a database, and to
+your operating system documentation for information on making copies of files.

 
 

+=== Perform the file upgrade ===

 
 

-=== Configuration changes from 1.4.x: ===
+Download the files for the new version of the software. These are available
+as a compressed "tar" archive from the Wikimedia Download Service
+(http://download.wikimedia.org/mediawiki).

 
 

-$wgDisableUploads has been replaced with $wgEnableUploads.
+You can also obtain the new files directly from our Subversion source code
+repository, via a checkout or export operation.

 
 

-$wgWhitelistAccount has been replaced by the 'createaccount' permission
-key in $wgGroupPermissions. To emulate the old effect of setting:
-  $wgWhitelistAccount['user'] = 0;
-set:
-  $wgGroupPermissions['*'] = array( 'read' ); // without createaccount
+Replace the existing MediaWiki files with the new. You should preserve the
+LocalSettings.php file and the "extensions" and "images" directories.
+
+Depending upon your configuration, you may also need to preserve additional
+directories, including a custom upload directory ($wgUploadDirectory),
+deleted file archives, and any custom skins.
+
+=== Perform the database upgrade ===
+
+==== From the web ====
+
+If you browse to the web-based installation script (usually at
+/mw-config/index.php) from your wiki installation you can follow the script and
+upgrade your database in place.
+
+==== From the command line ====

 
 

-If $wgWhitelistRead is set, things need to be funked around. This needs work.
+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.

 
 

-bla bla bla
+=== 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.

 
 

-=== Web installer ===
+=== Check installed extensions ===

 
 

-You can use the web-based installer wizard if you first remove the
-LocalSettings.php (and AdminSettings.php, if any) files; be sure to
-give the installer the same information as you did on the original
-install (language/encoding, database name, password, etc). This will
-also generate a fresh LocalSettings.php, which you may need to customize.
+Extensions usually need to be upgraded at the same time as the MediaWiki core.

 
 

-You may change some settings during the install, but be very careful!
-Changing the encoding in particular will generally leave you with a
-lot of corrupt pages, particularly if your wiki is not in English.
+In MediaWiki 1.14 some extensions were migrated into the core. Please see the
+HISTORY section "Migrated extensions" and disable these extensions in your
+LocalSettings.php

 
 

-=== Command-line upgrade ===
+=== Test ===

 
 

-Additionally, as of 1.4.0 you can run an in-place upgrade script from
-the command line, keeping your existing LocalSettings.php. This requires
-that you create an AdminSettings.php giving an appropriate database user
-and password with privileges to modify the database structure.
+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.

 
 

-Once the new files are in place, go into the maintenance subdirectory and
-run the script:
+You should also test any extensions, and upgrade these if necessary.

 
 

-  php update.php
+== Upgrading from 1.16 or earlier ==

 
 

-See caveats below on upgrading from 1.3.x or earlier.
+If you have a Chinese or Japanese wiki ($wgLanguageCode is set to one
+of "zh", "ja", or "yue") and you are using MySQL fulltext search, you
+will probably want to update the search index.

 
 

+In the "maintenance" directory, run the updateDoubleWidthSearch.php
+script.  This will update the searchindex table for those pages that
+contain double-byte latin characters.

 
 

-== Backups! ==
+== Upgrading from 1.8 or earlier ==

 
 

-To upgrade an existing MediaWiki installation, first BACK UP YOUR WIKI!
-If something goes wrong, you want to be able to start again.
+MediaWiki 1.9 and later no longer keep default localized message text
+in the database; 'MediaWiki:'-namespace pages that do not exist in the
+database are simply transparently filled-in on demand.

 
 

-Your image files, configuration, etc can simply be copied or archived as
-you would any other files. (Make sure that the contents of your
-LocalSettings.php are not accidentally made public, as this contains
-a database password.)
+The upgrade process will delete any 'MediaWiki:' pages which are left
+in the default state (last edited by 'MediaWiki default'). This may
+take a few moments, similar to the old initial setup.

 
 

-To back up the database, use the tools provided by your service provider
-(if applicable) or the standard mysqldump program.
+Note that the large number of deletions may cause older edits to expire
+from the list on Special:Recentchanges, although the deletions themselves
+will be hidden by default. (Click "show bot edits" to list them.)

 
 

-For general help on mysqldump:
-http://dev.mysql.com/doc/mysql/en/mysqldump.html
+See RELEASE-NOTES for more details about new and changed options.

 
 

-WARNING: If using MySQL 4.1.x, mysqldump's charset conversion may in
-some cases damage data in your wiki. If necessary, set the charset
-option to 'latin1' to avoid the conversion. Fore more info see:
-http://mail.wikipedia.org/pipermail/wikitech-l/2004-November/026359.html
+== Upgrading from 1.7 or earlier ==

 
 

+$wgDefaultUserOptions now contains all the defaults, not only overrides.
+If you're setting this as a complete array(), you may need to change it
+to set only specific items as recommended in DefaultSettings.php.

 
 

-== Caveats ==
+== Upgrading from 1.6 or earlier ==

 
 

+$wgLocalTZoffset was in hours, it is now using minutes.

 
 

-=== Upgrading from 1.4.2 or earlier ===
+== Upgrading from 1.5 or earlier ==
+
+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.
+
+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; 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 changed 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.
+
+$wgWhitelistAccount has been replaced by the 'createaccount' permission
+key in $wgGroupPermissions. To emulate the old effect of setting:
+  $wgWhitelistAccount['user'] = 0;
+set:
+  $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;
+
+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.
+
+If using Memcached, you must enabled it differently now:
+  $wgUseMemCached = true;
+should be replaced with:
+  $wgMainCacheType = CACHE_MEMCACHED;
+
+== Upgrading from 1.4.2 or earlier ==

 
 1.4.3 has added new fields to the sitestats table. These fields are
 optional and help to speed Special:Statistics on large sites. If you
 
 1.4.3 has added new fields to the sitestats table. These fields are
 optional and help to speed Special:Statistics on large sites. If you


@@ -117,7 +193,7 @@ manually run the SQL commands from this file:
   maintenance/archives/patch-ss_total_articles.sql
 
 
   maintenance/archives/patch-ss_total_articles.sql
 
 

-=== Upgrading from 1.4rc1 or earlier betas ===
+== Upgrading from 1.4rc1 or earlier betas ==

 
 The logging table has been altered from 1.4beta4 to 1.4beta5
 and again in 1.4.0 final. Copy in the new files and use the web
 
 The logging table has been altered from 1.4beta4 to 1.4beta5
 and again in 1.4.0 final. Copy in the new files and use the web


@@ -130,7 +206,7 @@ files:
    maintenance/archives/patch-logging-title.sql
 
 
    maintenance/archives/patch-logging-title.sql
 
 

-=== Upgrading from 1.3.x ===
+== Upgrading from 1.3 or earlier ==

 
 This should generally go smoothly.
 
 
 This should generally go smoothly.
 


@@ -148,19 +224,20 @@ to this:
 As well as new messages, the processing of some messages has changed.
 If you have customized them, please compare the new format using
 Special:Allmessages or the relevant LanguageXX.php files:
 As well as new messages, the processing of some messages has changed.
 If you have customized them, please compare the new format using
 Special:Allmessages or the relevant LanguageXX.php files:

-  copyrightwarning
-  dberrortext
-  editingcomment  (was named commentedit)
-  editingsection  (was named sectionedit)
-  numauthors
-  numedits
-  numtalkauthors
-  numtalkedits
-  numwatchers
-  protectedarticle
-  searchresulttext
-  showhideminor
-  unprotectedarticle
+
+* copyrightwarning
+* dberrortext
+* editingcomment  (was named commentedit)
+* editingsection  (was named sectionedit)
+* numauthors
+* numedits
+* numtalkauthors
+* numtalkedits
+* numwatchers
+* protectedarticle
+* searchresulttext
+* showhideminor
+* unprotectedarticle

 
 Note that the 1.3 beta releases included a potential vulnerability if PHP
 is configured with register_globals on and the includes directory is
 
 Note that the 1.3 beta releases included a potential vulnerability if PHP
 is configured with register_globals on and the includes directory is


@@ -172,7 +249,7 @@ send them a kind note explaining that it can expose their servers and their
 customers to attacks.
 
 
 customers to attacks.
 
 

-=== Upgrading from 1.2.x ===
+== Upgrading from 1.2 or earlier ==

 
 If you've been using the MediaWiki: namespace for custom page templates,
 note that things are a little different. The Template: namespace has been
 
 If you've been using the MediaWiki: namespace for custom page templates,
 note that things are a little different. The Template: namespace has been


@@ -192,7 +269,7 @@ to dump the database to SQL, run it through iconv or another conversion tool,
 and restore it. Sorry.
 
 
 and restore it. Sorry.
 
 

-=== Upgrading from 1.1.x or earlier ===
+== Upgrading from 1.1 or earlier ==

 
 This is less thoroughly tested, but should work.
 
 
 This is less thoroughly tested, but should work.
 


@@ -206,7 +283,7 @@ scripts in maintenance/archives before the installer is able to pick up
 with remaining updates.
 
 
 with remaining updates.
 
 

-=== Upgrading from UseModWiki or old "phase 2" Wikipedia code ===
+== Upgrading from UseModWiki or old "phase 2" Wikipedia code ==

 
 There is a semi-maintained UseModWiki to MediaWiki conversion script at
 maintenance/importUseModWiki.php; it may require tweaking and customization
 
 There is a semi-maintained UseModWiki to MediaWiki conversion script at
 maintenance/importUseModWiki.php; it may require tweaking and customization


@@ -217,3 +294,5 @@ output SQL statements; direct these to a file and then run that into your
 database.
 
 You will have to rebuild the links tables etc after importing.
 database.
 
 You will have to rebuild the links tables etc after importing.

+
+