UPGRADE

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