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