UPGRADE

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