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

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.

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


== IMPORTANT: Upgrading to 1.5 ==

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


=== 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;


=== Web installer ===

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.

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.

=== Command-line upgrade ===

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.

Once the new files are in place, go into the maintenance subdirectory and
run the script:

  php update.php

See caveats below on upgrading from 1.3.x or earlier.


== Backups! ==

To upgrade an existing MediaWiki installation, first BACK UP YOUR WIKI!
If something goes wrong, you want to be able to start again.

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

To back up the database, use the tools provided by your service provider
(if applicable) or the standard mysqldump program.

For general help on mysqldump:
http://dev.mysql.com/doc/mysql/en/mysqldump.html

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


== Caveats ==


=== 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
choose not to run the database upgrades, everything will continue to
work in 1.4.3.

You can apply the update by running maintenance/update.php, or
manually run the SQL commands from this file:
  maintenance/archives/patch-ss_total_articles.sql


=== 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
installer to upgrade, or the command-line maintenance/update.php.

If you cannot use the automated installers/updaters, you may
update the table by manually running the SQL commands in these
files:
   maintenance/archives/patch-log_params.sql
   maintenance/archives/patch-logging-title.sql


=== Upgrading from 1.3.x ===

This should generally go smoothly.

If you keep your LocalSettings.php, you may need to change the style paths
to match the newly rearranged skin modules. Change these lines:
  $wgStylePath        = "$wgScriptPath/stylesheets";
  $wgStyleDirectory   = "$IP/stylesheets";
  $wgLogo             = "$wgStylePath/images/wiki.png";

to this:
  $wgStylePath        = "$wgScriptPath/skins";
  $wgStyleDirectory   = "$IP/skins";
  $wgLogo             = "$wgStylePath/common/images/wiki.png";

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

Note that the 1.3 beta releases included a potential vulnerability if PHP
is configured with register_globals on and the includes directory is
served to the web. For general safety, turn register_globals *off* if you
don't _really_ need it for another package.

If your hosting provider turns it on and you can't turn it off yourself,
send them a kind note explaining that it can expose their servers and their
customers to attacks.


=== Upgrading from 1.2.x ===

If you've been using the MediaWiki: namespace for custom page templates,
note that things are a little different. The Template: namespace has been
added which is more powerful -- templates can include parameters for
instance.

If you were using custom MediaWiki: entries for text inclusions, they
will *not* automatically be moved to Template: entries at upgrade time.
Be sure to go through and check that everything is working properly;
you can move them manually or you can try using moveCustomMessages.php
in maintenance/archives to do it automatically, but this might break things.

Also, be sure to pick the correct character encoding -- some languages were
only available in Latin-1 on 1.2.x and are now available for Unicode as well.
If you want to upgrade an existing wiki from Latin-1 to Unicode you'll have
to dump the database to SQL, run it through iconv or another conversion tool,
and restore it. Sorry.


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

This is less thoroughly tested, but should work.

You need to specify the *admin* database username and password to the
installer in order for it to successfully upgrade the database structure.
You may wish to manually change the GRANTs later.

If you have a very old database (earlier than organized MediaWiki releases
in late August 2003) you may need to manually run some of the update SQL
scripts in maintenance/archives before the installer is able to pick up
with remaining updates.


=== 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
to work for you.

Install a new MediaWiki first, then use the conversion script which will
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.
