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