[Summary view] [Print] [Text view]

   1  
   2  This file provides an overview of the MediaWiki upgrade process. For help with
   3  specific problems, check
   4  
   5  * the documentation at https://www.mediawiki.org
   6  * the mediawiki-l mailing list archive at
   7    http://lists.wikimedia.org/pipermail/mediawiki-l/
   8  * the bug tracker at https://bugzilla.wikimedia.org
   9  
  10  for information and workarounds to common issues.
  11  
  12  == Overview ==
  13  
  14  Comprehensive documentation on upgrading to the latest version of the software
  15  is available at https://www.mediawiki.org/wiki/Manual:Upgrading.
  16  
  17  === Consult the release notes ===
  18  
  19  Before doing anything, stop and consult the release notes supplied with the new
  20  version of the software. These detail bug fixes, new features and functionality,
  21  and any particular points that may need to be noted during the upgrade
  22  procedure.
  23  
  24  === Backup first ===
  25  
  26  It is imperative that, prior to attempting an upgrade of the database schema,
  27  you take a complete backup of your wiki database and files and verify it. While
  28  the upgrade scripts are somewhat robust, there is no guarantee that things will
  29  not fail, leaving the database in an inconsistent state.
  30  
  31  https://www.mediawiki.org/wiki/Manual:Backing_up_a_wiki provides an overview of
  32  the backup process. You should also refer to the documentation for your
  33  database management system for information on backing up a database, and to
  34  your operating system documentation for information on making copies of files.
  35  
  36  === Perform the file upgrade ===
  37  
  38  Download the files for the new version of the software. These are available
  39  as a compressed "tar" archive from the Wikimedia Download Service
  40  (http://download.wikimedia.org/mediawiki).
  41  
  42  You can also obtain the new files directly from our Git source code
  43  repository.
  44  
  45  Replace the existing MediaWiki files with the new. You should preserve the
  46  LocalSettings.php file and the "extensions" and "images" directories.
  47  
  48  Depending upon your configuration, you may also need to preserve additional
  49  directories, including a custom upload directory ($wgUploadDirectory),
  50  deleted file archives, and any custom skins.
  51  
  52  === Perform the database upgrade ===
  53  
  54  As of 1.21, it is possible to separate schema changes (i.e. adding,
  55  dropping, or changing tables, fields, or indices) from all other
  56  database changes (e.g. populating fields).  If you need this
  57  capability, see "From the command line" below.
  58  
  59  ==== From the web ====
  60  
  61  If you browse to the web-based installation script (usually at
  62  /mw-config/index.php) from your wiki installation you can follow the script and
  63  upgrade your database in place.
  64  
  65  ==== From the command line ====
  66  
  67  From the command line, browse to the "maintenance" directory and run the
  68  update.php script to check and update the schema. This will insert missing
  69  tables, update existing tables, and move data around as needed. In most cases,
  70  this is successful and nothing further needs to be done.
  71  
  72  If you need to separate out the schema changes so they can be run
  73  by someone with more privileges, then you can use the --schema option
  74  to produce a text file with the necessary commands.  You can use
  75  --schema, --noschema, $wgAllowSchemaUpdates as well as proper database
  76  permissions to enforce this separation.
  77  
  78  === Check configuration settings ===
  79  
  80  The names of configuration variables, and their default values and purposes,
  81  can change between release branches, e.g. $wgDisableUploads in 1.4 is replaced
  82  with $wgEnableUploads in later versions. When upgrading, consult the release
  83  notes to check for configuration changes which would alter the expected
  84  behavior of MediaWiki.
  85  
  86  === Check installed extensions ===
  87  
  88  Extensions usually need to be upgraded at the same time as the MediaWiki core.
  89  
  90  In MediaWiki 1.14 some extensions were migrated into the core. Please see the
  91  HISTORY section "Migrated extensions" and disable these extensions in your
  92  LocalSettings.php
  93  
  94  === Test ===
  95  
  96  It makes sense to test your wiki immediately following any kind of maintenance
  97  procedure, and especially after upgrading; check that page views and edits work
  98  normally and that special pages continue to function, etc. and correct errors
  99  and quirks which reveal themselves.
 100  
 101  You should also test any extensions, and upgrade these if necessary.
 102  
 103  == Upgrading from 1.16 or earlier ==
 104  
 105  If you have a Chinese or Japanese wiki ($wgLanguageCode is set to one
 106  of "zh", "ja", or "yue") and you are using MySQL fulltext search, you
 107  will probably want to update the search index.
 108  
 109  In the "maintenance" directory, run the updateDoubleWidthSearch.php
 110  script.  This will update the searchindex table for those pages that
 111  contain double-byte latin characters.
 112  
 113  == Upgrading from 1.8 or earlier ==
 114  
 115  MediaWiki 1.9 and later no longer keep default localized message text
 116  in the database; 'MediaWiki:'-namespace pages that do not exist in the
 117  database are simply transparently filled-in on demand.
 118  
 119  The upgrade process will delete any 'MediaWiki:' pages which are left
 120  in the default state (last edited by 'MediaWiki default'). This may
 121  take a few moments, similar to the old initial setup.
 122  
 123  Note that the large number of deletions may cause older edits to expire
 124  from the list on Special:Recentchanges, although the deletions themselves
 125  will be hidden by default. (Click "show bot edits" to list them.)
 126  
 127  See RELEASE-NOTES for more details about new and changed options.
 128  
 129  == Upgrading from 1.7 or earlier ==
 130  
 131  $wgDefaultUserOptions now contains all the defaults, not only overrides.
 132  If you're setting this as a complete array(), you may need to change it
 133  to set only specific items as recommended in DefaultSettings.php.
 134  
 135  == Upgrading from 1.6 or earlier ==
 136  
 137  $wgLocalTZoffset was in hours, it is now using minutes.
 138  
 139  == Upgrading from 1.5 or earlier ==
 140  
 141  Major changes have been made to the schema from 1.4.x. The updater
 142  has not been fully tested for all conditions, and might well break.
 143  
 144  On a large site, the schema update might take a long time. It might
 145  explode, or leave your database half-done or otherwise badly hurting.
 146  
 147  Among other changes, note that Latin-1 encoding (ISO-8859-1) is
 148  no longer supported. Latin-1 wikis will need to be upgraded to
 149  UTF-8; an experimental command-line upgrade helper script,
 150  'upgrade1_5.php', can do this -- run it prior to 'update.php' or
 151  the web upgrader.
 152  
 153  NOTE that upgrade1_5.php does not work properly with recent version
 154  of MediaWiki. If upgrading a 1.4.x wiki, you should upgrade to 1.5
 155  first.  upgrade1_5.php has been removed from MediaWiki 1.21.
 156  
 157  If you absolutely cannot make the UTF-8 upgrade work, you can try
 158  doing it by hand: dump your old database, convert the dump file
 159  using iconv as described here:
 160  http://portal.suse.com/sdb/en/2004/05/jbartsh_utf-8.html
 161  and then reimport it. You can also convert filenames using convmv,
 162  but note that the old directory hashes will no longer be valid,
 163  so you will also have to move them to new destinations.
 164  
 165  Message changes:
 166  * A number of additional UI messages have been changed from HTML to
 167    wikitext, and will need to be manually fixed if customized.
 168  
 169  === Configuration changes from 1.4.x: ===
 170  
 171  $wgDisableUploads has been replaced with $wgEnableUploads.
 172  
 173  $wgWhitelistAccount has been replaced by the 'createaccount' permission
 174  key in $wgGroupPermissions. To emulate the old effect of setting:
 175    $wgWhitelistAccount['user'] = 0;
 176  set:
 177    $wgGroupPermissions['*']['createaccount'] = false;
 178  
 179  $wgWhitelistEdit has been replaced by the 'edit' permission key.
 180  To emulate the old effect of setting:
 181    $wgWhitelistEdit = true;
 182  set:
 183    $wgGroupPermissions['*']['edit'] = false;
 184  
 185  If $wgWhitelistRead is set, you must also disable the 'read' permission
 186  for it to take affect on anonymous users:
 187    $wgWhitelistRead = array( "Main Page", "Special:Userlogin" );
 188    $wgGroupPermissions['*']['read'] = false;
 189  
 190  Note that you can disable/enable several other permissions by modifying
 191  this configuration array in your LocalSettings.php; see DefaultSettings.php
 192  for the complete default permission set.
 193  
 194  If using Memcached, you must enabled it differently now:
 195    $wgUseMemCached = true;
 196  should be replaced with:
 197    $wgMainCacheType = CACHE_MEMCACHED;
 198  
 199  == Upgrading from 1.4.2 or earlier ==
 200  
 201  1.4.3 has added new fields to the sitestats table. These fields are
 202  optional and help to speed Special:Statistics on large sites. If you
 203  choose not to run the database upgrades, everything will continue to
 204  work in 1.4.3.
 205  
 206  You can apply the update by running maintenance/update.php, or
 207  manually run the SQL commands from this file:
 208    maintenance/archives/patch-ss_total_articles.sql
 209  
 210  
 211  == Upgrading from 1.4rc1 or earlier betas ==
 212  
 213  The logging table has been altered from 1.4beta4 to 1.4beta5
 214  and again in 1.4.0 final. Copy in the new files and use the web
 215  installer to upgrade, or the command-line maintenance/update.php.
 216  
 217  If you cannot use the automated installers/updaters, you may
 218  update the table by manually running the SQL commands in these
 219  files:
 220     maintenance/archives/patch-log_params.sql
 221     maintenance/archives/patch-logging-title.sql
 222  
 223  
 224  == Upgrading from 1.3 or earlier ==
 225  
 226  This should generally go smoothly.
 227  
 228  If you keep your LocalSettings.php, you may need to change the style paths
 229  to match the newly rearranged skin modules. Change these lines:
 230    $wgStylePath        = "$wgScriptPath/stylesheets";
 231    $wgStyleDirectory   = "$IP/stylesheets";
 232    $wgLogo             = "$wgStylePath/images/wiki.png";
 233  
 234  to this:
 235    $wgStylePath        = "$wgScriptPath/skins";
 236    $wgStyleDirectory   = "$IP/skins";
 237    $wgLogo             = "$wgStylePath/common/images/wiki.png";
 238  
 239  As well as new messages, the processing of some messages has changed.
 240  If you have customized them, please compare the new format using
 241  Special:Allmessages or the relevant LanguageXX.php files:
 242  
 243  * copyrightwarning
 244  * dberrortext
 245  * editingcomment  (was named commentedit)
 246  * editingsection  (was named sectionedit)
 247  * numauthors
 248  * numedits
 249  * numtalkauthors
 250  * numtalkedits
 251  * numwatchers
 252  * protectedarticle
 253  * searchresulttext
 254  * showhideminor
 255  * unprotectedarticle
 256  
 257  Note that the 1.3 beta releases included a potential vulnerability if PHP
 258  is configured with register_globals on and the includes directory is
 259  served to the web. For general safety, turn register_globals *off* if you
 260  don't _really_ need it for another package.
 261  
 262  If your hosting provider turns it on and you can't turn it off yourself,
 263  send them a kind note explaining that it can expose their servers and their
 264  customers to attacks.
 265  
 266  
 267  == Upgrading from 1.2 or earlier ==
 268  
 269  If you've been using the MediaWiki: namespace for custom page templates,
 270  note that things are a little different. The Template: namespace has been
 271  added which is more powerful -- templates can include parameters for
 272  instance.
 273  
 274  If you were using custom MediaWiki: entries for text inclusions, they
 275  will *not* automatically be moved to Template: entries at upgrade time.
 276  Be sure to go through and check that everything is working properly;
 277  you can move them manually or you can try using moveCustomMessages.php
 278  in maintenance/archives to do it automatically, but this might break things.
 279  
 280  Also, be sure to pick the correct character encoding -- some languages were
 281  only available in Latin-1 on 1.2.x and are now available for Unicode as well.
 282  If you want to upgrade an existing wiki from Latin-1 to Unicode you'll have
 283  to dump the database to SQL, run it through iconv or another conversion tool,
 284  and restore it. Sorry.
 285  
 286  
 287  == Upgrading from 1.1 or earlier ==
 288  
 289  This is less thoroughly tested, but should work.
 290  
 291  You need to specify the *admin* database username and password to the
 292  installer in order for it to successfully upgrade the database structure.
 293  You may wish to manually change the GRANTs later.
 294  
 295  If you have a very old database (earlier than organized MediaWiki releases
 296  in late August 2003) you may need to manually run some of the update SQL
 297  scripts in maintenance/archives before the installer is able to pick up
 298  with remaining updates.