UPGRADE

   1 == The basic theory ==
   2
   3 Generally, within a stable release series (e.g. 1.4.0, 1.4.1, etc) there
   4 are no required database changes, and upgrading should require no more
   5 than copying the new source files over the old ones.
   6
   7 If there are larger changes, such as upgrading from one release series
   8 to another (e.g. from 1.3.12 to 1.4.3), then you may need to update the
   9 database schema and configuration.
  10
  11 Basically, to upgrade a wiki you:
  12 * Back up your data! (See Backups! below)
  13 * Extract the new archive. If you can do this in a clean directory that's
  14   great, but it should work to extract over the old files too. This may
  15   be easier if you have images etc in place and don't want to move them
  16   around, but remember to back up first!
  17 * Run the installer to upgrade the database schema (if necessary).
  18
  19
  20 == IMPORTANT: Upgrading to 1.5 ==
  21
  22 Major changes have been made to the schema from 1.4.x. The updater
  23 has not been fully tested for all conditions, and might well break.
  24
  25 DO NOT ATTEMPT TO UPGRADE A LIVE, PUBLIC SITE TO 1.5 AT THIS TIME.
  26 NEVER EVER ATTEMPT TO PERFORM AN UPGRADE WITHOUT BACKING UP FIRST!
  27
  28 On a large site, the schema update might take a long time. It might
  29 explode, or leave your database half-done or otherwise badly hurting.
  30
  31 Among other changes, note that Latin-1 encoding (ISO-8859-1) is
  32 no longer supported. Latin-1 wikis will need to be upgraded to
  33 UTF-8; an experimental command-line upgrade helper script,
  34 'upgrade1_5.php', can do this -- run it prior to 'update.php' or
  35 the web upgrader.
  36
  37 Message changes:
  38 * A number of additional UI messages have been chagned from HTML to
  39   wikitext, and will need to be manually fixed if customized.
  40
  41
  42 === Configuration changes from 1.4.x: ===
  43
  44 $wgDisableUploads has been replaced with $wgEnableUploads.
  45
  46 $wgWhitelistAccount has been replaced by the 'createaccount' permission
  47 key in $wgGroupPermissions. To emulate the old effect of setting:
  48   $wgWhitelistAccount['user'] = 0;
  49 set:
  50   $wgGroupPermissions['*']['createaccount'] = false;
  51
  52 $wgWhitelistEdit has been replaced by the 'edit' permission key.
  53 To emulate the old effect of setting:
  54   $wgWhitelistEdit = true;
  55 set:
  56   $wgGroupPermissions['*']['edit'] = false;
  57
  58 If $wgWhitelistRead is set, you must also disable the 'read' permission
  59 for it to take affect on anonymous users:
  60   $wgWhitelistRead = array( "Main Page", "Special:Userlogin" );
  61   $wgGroupPermissions['*']['read'] = false;
  62
  63 Note that you can disable/enable several other permissions by modifying
  64 this configuration array in your LocalSettings.php; see DefaultSettings.php
  65 for the complete default permission set.
  66
  67
  68 === Web installer ===
  69
  70 You can use the web-based installer wizard if you first remove the
  71 LocalSettings.php (and AdminSettings.php, if any) files; be sure to
  72 give the installer the same information as you did on the original
  73 install (language/encoding, database name, password, etc). This will
  74 also generate a fresh LocalSettings.php, which you may need to customize.
  75
  76 You may change some settings during the install, but be very careful!
  77 Changing the encoding in particular will generally leave you with a
  78 lot of corrupt pages, particularly if your wiki is not in English.
  79
  80 === Command-line upgrade ===
  81
  82 Additionally, as of 1.4.0 you can run an in-place upgrade script from
  83 the command line, keeping your existing LocalSettings.php. This requires
  84 that you create an AdminSettings.php giving an appropriate database user
  85 and password with privileges to modify the database structure.
  86
  87 Once the new files are in place, go into the maintenance subdirectory and
  88 run the script:
  89
  90   php update.php
  91
  92 See caveats below on upgrading from 1.3.x or earlier.
  93
  94
  95 == Backups! ==
  96
  97 To upgrade an existing MediaWiki installation, first BACK UP YOUR WIKI!
  98 If something goes wrong, you want to be able to start again.
  99
 100 Your image files, configuration, etc can simply be copied or archived as
 101 you would any other files. (Make sure that the contents of your
 102 LocalSettings.php are not accidentally made public, as this contains
 103 a database password.)
 104
 105 To back up the database, use the tools provided by your service provider
 106 (if applicable) or the standard mysqldump program.
 107
 108 For general help on mysqldump:
 109 http://dev.mysql.com/doc/mysql/en/mysqldump.html
 110
 111 WARNING: If using MySQL 4.1.x, mysqldump's charset conversion may in
 112 some cases damage data in your wiki. If necessary, set the charset
 113 option to 'latin1' to avoid the conversion. Fore more info see:
 114 http://mail.wikipedia.org/pipermail/wikitech-l/2004-November/026359.html
 115
 116
 117 == Caveats ==
 118
 119
 120 === Upgrading from 1.4.2 or earlier ===
 121
 122 1.4.3 has added new fields to the sitestats table. These fields are
 123 optional and help to speed Special:Statistics on large sites. If you
 124 choose not to run the database upgrades, everything will continue to
 125 work in 1.4.3.
 126
 127 You can apply the update by running maintenance/update.php, or
 128 manually run the SQL commands from this file:
 129   maintenance/archives/patch-ss_total_articles.sql
 130
 131
 132 === Upgrading from 1.4rc1 or earlier betas ===
 133
 134 The logging table has been altered from 1.4beta4 to 1.4beta5
 135 and again in 1.4.0 final. Copy in the new files and use the web
 136 installer to upgrade, or the command-line maintenance/update.php.
 137
 138 If you cannot use the automated installers/updaters, you may
 139 update the table by manually running the SQL commands in these
 140 files:
 141    maintenance/archives/patch-log_params.sql
 142    maintenance/archives/patch-logging-title.sql
 143
 144
 145 === Upgrading from 1.3.x ===
 146
 147 This should generally go smoothly.
 148
 149 If you keep your LocalSettings.php, you may need to change the style paths
 150 to match the newly rearranged skin modules. Change these lines:
 151   $wgStylePath        = "$wgScriptPath/stylesheets";
 152   $wgStyleDirectory   = "$IP/stylesheets";
 153   $wgLogo             = "$wgStylePath/images/wiki.png";
 154
 155 to this:
 156   $wgStylePath        = "$wgScriptPath/skins";
 157   $wgStyleDirectory   = "$IP/skins";
 158   $wgLogo             = "$wgStylePath/common/images/wiki.png";
 159
 160 As well as new messages, the processing of some messages has changed.
 161 If you have customized them, please compare the new format using
 162 Special:Allmessages or the relevant LanguageXX.php files:
 163   copyrightwarning
 164   dberrortext
 165   editingcomment  (was named commentedit)
 166   editingsection  (was named sectionedit)
 167   numauthors
 168   numedits
 169   numtalkauthors
 170   numtalkedits
 171   numwatchers
 172   protectedarticle
 173   searchresulttext
 174   showhideminor
 175   unprotectedarticle
 176
 177 Note that the 1.3 beta releases included a potential vulnerability if PHP
 178 is configured with register_globals on and the includes directory is
 179 served to the web. For general safety, turn register_globals *off* if you
 180 don't _really_ need it for another package.
 181
 182 If your hosting provider turns it on and you can't turn it off yourself,
 183 send them a kind note explaining that it can expose their servers and their
 184 customers to attacks.
 185
 186
 187 === Upgrading from 1.2.x ===
 188
 189 If you've been using the MediaWiki: namespace for custom page templates,
 190 note that things are a little different. The Template: namespace has been
 191 added which is more powerful -- templates can include parameters for
 192 instance.
 193
 194 If you were using custom MediaWiki: entries for text inclusions, they
 195 will *not* automatically be moved to Template: entries at upgrade time.
 196 Be sure to go through and check that everything is working properly;
 197 you can move them manually or you can try using moveCustomMessages.php
 198 in maintenance/archives to do it automatically, but this might break things.
 199
 200 Also, be sure to pick the correct character encoding -- some languages were
 201 only available in Latin-1 on 1.2.x and are now available for Unicode as well.
 202 If you want to upgrade an existing wiki from Latin-1 to Unicode you'll have
 203 to dump the database to SQL, run it through iconv or another conversion tool,
 204 and restore it. Sorry.
 205
 206
 207 === Upgrading from 1.1.x or earlier ===
 208
 209 This is less thoroughly tested, but should work.
 210
 211 You need to specify the *admin* database username and password to the
 212 installer in order for it to successfully upgrade the database structure.
 213 You may wish to manually change the GRANTs later.
 214
 215 If you have a very old database (earlier than organized MediaWiki releases
 216 in late August 2003) you may need to manually run some of the update SQL
 217 scripts in maintenance/archives before the installer is able to pick up
 218 with remaining updates.
 219
 220
 221 === Upgrading from UseModWiki or old "phase 2" Wikipedia code ===
 222
 223 There is a semi-maintained UseModWiki to MediaWiki conversion script at
 224 maintenance/importUseModWiki.php; it may require tweaking and customization
 225 to work for you.
 226
 227 Install a new MediaWiki first, then use the conversion script which will
 228 output SQL statements; direct these to a file and then run that into your
 229 database.
 230
 231 You will have to rebuild the links tables etc after importing.