path: root/UPGRADE
diff options
authorPierre Schmitz <>2006-10-11 18:12:39 +0000
committerPierre Schmitz <>2006-10-11 18:12:39 +0000
commit183851b06bd6c52f3cae5375f433da720d410447 (patch)
treea477257decbf3360127f6739c2f9d0ec57a03d39 /UPGRADE
MediaWiki 1.7.1 wiederhergestellt
Diffstat (limited to 'UPGRADE')
1 files changed, 303 insertions, 0 deletions
diff --git a/UPGRADE b/UPGRADE
new file mode 100644
index 00000000..70ccbadf
--- /dev/null
@@ -0,0 +1,303 @@
+This file provides an overview of the MediaWiki upgrade process. For help with
+specific problems, check
+* the documentation at
+* the documentation at
+* the mediawiki-l mailing list archive at
+* the bug tracker at
+for information and workarounds to common issues.
+== Overview ==
+Documentation on upgrading to 1.7 can also be found at
+=== Consult the release notes ===
+Before doing anything, stop and consult the release notes supplied with the new
+version of the software. This detail bug fixes, new features and functionality,
+and any particular points that may need to be noted during the upgrade
+=== Backup first ===
+It is imperative that, prior to attempting an upgrade of the database schema,
+you take a complete backup of your wiki database and files and verify it. While
+the upgrade scripts are somewhat robust, there is no guarantee that things will
+not fail, leaving the database in an inconsistent state.
+Refer to the MySQL documentation for information on backing up a database. For
+information on making copies of files, consult the documentation for your
+operating system.
+=== Perform the file upgrade ===
+Having downloaded the desired new version of the software, either as a package
+from SourceForge, or via an export from Subversion, decompress the files as
+needed, and replace the existing MediaWiki files with the new.
+You should preserve:
+* The LocalSettings.php file
+* The AdminSettings.php file, where it exists
+* The extensions directory
+* The images directory
+If using an alternative uploads directory, preserve this; and if using custom
+skins, preserve these too. The core code is now updated.
+=== Perform the database upgrade ===
+You will need an AdminSettings.php file set up in the correct format; see
+AdminSettings.sample in the wiki root for more information and examples.
+From the command line, browse to the maintenance directory and run the
+update.php script to check and update the schema. This will insert missing
+tables, update existing tables, and move data around as needed. In most cases,
+this is successful and nothing further needs to be done.
+=== Check configuration settings ===
+The names of configuration variables, and their default values and purposes,
+can change between release branches, e.g. $wgDisableUploads in 1.4 is replaced
+with $wgEnableUploads in later versions. When upgrading, consult the release
+notes to check for configuration changes which would alter the expected
+behaviour of MediaWiki.
+=== Test ===
+It makes sense to test your wiki immediately following any kind of maintenance
+procedure, and especially after upgrading; check that page views and edits work
+normally and that special pages continue to function, etc. and correct errors
+and quirks which reveal themselves.
+== Upgrading from 1.6 wikis ==
+$wgLocalTZoffset was in hours, it is now using minutes.
+Link autonumbering got fixed (#5918) for protocols other than http.
+ - 'irc://irc.server.tld/' render as a link with a chat icon
+ - '[irc://irc.server.tld]' render as an autonumbered link: [1]
+== Upgrading from pre-1.5 wikis ==
+Major changes have been made to the schema from 1.4.x. The updater
+has not been fully tested for all conditions, and might well break.
+On a large site, the schema update might take a long time. It might
+explode, or leave your database half-done or otherwise badly hurting.
+Among other changes, note that Latin-1 encoding (ISO-8859-1) is
+no longer supported. Latin-1 wikis will need to be upgraded to
+UTF-8; an experimental command-line upgrade helper script,
+'upgrade1_5.php', can do this -- run it prior to 'update.php' or
+the web upgrader.
+If you absolutely cannot make the UTF-8 upgrade work, you can try
+doing it by hand: dump your old database, convert the dump file
+using iconv as described here:
+and then reimport it. You can also convert filenames using convmv,
+but note that the old directory hashes will no longer be valid,
+so you will also have to move them to new destinations.
+Message changes:
+* A number of additional UI messages have been chagned from HTML to
+ wikitext, and will need to be manually fixed if customized.
+=== Configuration changes from 1.4.x: ===
+$wgDisableUploads has been replaced with $wgEnableUploads.
+$wgWhitelistAccount has been replaced by the 'createaccount' permission
+key in $wgGroupPermissions. To emulate the old effect of setting:
+ $wgWhitelistAccount['user'] = 0;
+ $wgGroupPermissions['*']['createaccount'] = false;
+$wgWhitelistEdit has been replaced by the 'edit' permission key.
+To emulate the old effect of setting:
+ $wgWhitelistEdit = true;
+ $wgGroupPermissions['*']['edit'] = false;
+If $wgWhitelistRead is set, you must also disable the 'read' permission
+for it to take affect on anonymous users:
+ $wgWhitelistRead = array( "Main Page", "Special:Userlogin" );
+ $wgGroupPermissions['*']['read'] = false;
+Note that you can disable/enable several other permissions by modifying
+this configuration array in your LocalSettings.php; see DefaultSettings.php
+for the complete default permission set.
+If using Memcached, you must enabled it differently now:
+ $wgUseMemCached = true;
+should be replaced with:
+ $wgMainCacheType = CACHE_MEMCACHED;
+=== Web installer ===
+You can use the web-based installer wizard if you first remove the
+LocalSettings.php (and AdminSettings.php, if any) files; be sure to
+give the installer the same information as you did on the original
+install (language/encoding, database name, password, etc). This will
+also generate a fresh LocalSettings.php, which you may need to customize.
+You may change some settings during the install, but be very careful!
+Changing the encoding in particular will generally leave you with a
+lot of corrupt pages, particularly if your wiki is not in English.
+=== Command-line upgrade ===
+Additionally, as of 1.4.0 you can run an in-place upgrade script from
+the command line, keeping your existing LocalSettings.php. This requires
+that you create an AdminSettings.php giving an appropriate database user
+and password with privileges to modify the database structure.
+Once the new files are in place, go into the maintenance subdirectory and
+run the script:
+ php update.php
+See caveats below on upgrading from 1.3.x or earlier.
+== Backups! ==
+To upgrade an existing MediaWiki installation, first BACK UP YOUR WIKI!
+If something goes wrong, you want to be able to start again.
+Your image files, configuration, etc can simply be copied or archived as
+you would any other files. (Make sure that the contents of your
+LocalSettings.php are not accidentally made public, as this contains
+a database password.)
+To back up the database, use the tools provided by your service provider
+(if applicable) or the standard mysqldump program.
+For general help on mysqldump:
+WARNING: If using MySQL 4.1.x, mysqldump's charset conversion may in
+some cases damage data in your wiki. If necessary, set the charset
+option to 'latin1' to avoid the conversion. Fore more info see:
+== Caveats ==
+=== Upgrading from 1.4.2 or earlier ===
+1.4.3 has added new fields to the sitestats table. These fields are
+optional and help to speed Special:Statistics on large sites. If you
+choose not to run the database upgrades, everything will continue to
+work in 1.4.3.
+You can apply the update by running maintenance/update.php, or
+manually run the SQL commands from this file:
+ maintenance/archives/patch-ss_total_articles.sql
+=== Upgrading from 1.4rc1 or earlier betas ===
+The logging table has been altered from 1.4beta4 to 1.4beta5
+and again in 1.4.0 final. Copy in the new files and use the web
+installer to upgrade, or the command-line maintenance/update.php.
+If you cannot use the automated installers/updaters, you may
+update the table by manually running the SQL commands in these
+ maintenance/archives/patch-log_params.sql
+ maintenance/archives/patch-logging-title.sql
+=== Upgrading from 1.3.x ===
+This should generally go smoothly.
+If you keep your LocalSettings.php, you may need to change the style paths
+to match the newly rearranged skin modules. Change these lines:
+ $wgStylePath = "$wgScriptPath/stylesheets";
+ $wgStyleDirectory = "$IP/stylesheets";
+ $wgLogo = "$wgStylePath/images/wiki.png";
+to this:
+ $wgStylePath = "$wgScriptPath/skins";
+ $wgStyleDirectory = "$IP/skins";
+ $wgLogo = "$wgStylePath/common/images/wiki.png";
+As well as new messages, the processing of some messages has changed.
+If you have customized them, please compare the new format using
+Special:Allmessages or the relevant LanguageXX.php files:
+ copyrightwarning
+ dberrortext
+ editingcomment (was named commentedit)
+ editingsection (was named sectionedit)
+ numauthors
+ numedits
+ numtalkauthors
+ numtalkedits
+ numwatchers
+ protectedarticle
+ searchresulttext
+ showhideminor
+ unprotectedarticle
+Note that the 1.3 beta releases included a potential vulnerability if PHP
+is configured with register_globals on and the includes directory is
+served to the web. For general safety, turn register_globals *off* if you
+don't _really_ need it for another package.
+If your hosting provider turns it on and you can't turn it off yourself,
+send them a kind note explaining that it can expose their servers and their
+customers to attacks.
+=== Upgrading from 1.2.x ===
+If you've been using the MediaWiki: namespace for custom page templates,
+note that things are a little different. The Template: namespace has been
+added which is more powerful -- templates can include parameters for
+If you were using custom MediaWiki: entries for text inclusions, they
+will *not* automatically be moved to Template: entries at upgrade time.
+Be sure to go through and check that everything is working properly;
+you can move them manually or you can try using moveCustomMessages.php
+in maintenance/archives to do it automatically, but this might break things.
+Also, be sure to pick the correct character encoding -- some languages were
+only available in Latin-1 on 1.2.x and are now available for Unicode as well.
+If you want to upgrade an existing wiki from Latin-1 to Unicode you'll have
+to dump the database to SQL, run it through iconv or another conversion tool,
+and restore it. Sorry.
+=== Upgrading from 1.1.x or earlier ===
+This is less thoroughly tested, but should work.
+You need to specify the *admin* database username and password to the
+installer in order for it to successfully upgrade the database structure.
+You may wish to manually change the GRANTs later.
+If you have a very old database (earlier than organized MediaWiki releases
+in late August 2003) you may need to manually run some of the update SQL
+scripts in maintenance/archives before the installer is able to pick up
+with remaining updates.
+=== Upgrading from UseModWiki or old "phase 2" Wikipedia code ===
+There is a semi-maintained UseModWiki to MediaWiki conversion script at
+maintenance/importUseModWiki.php; it may require tweaking and customization
+to work for you.
+Install a new MediaWiki first, then use the conversion script which will
+output SQL statements; direct these to a file and then run that into your
+You will have to rebuild the links tables etc after importing.