| Index: trunk/phase3/UPGRADE |
| — | — | @@ -1,31 +1,83 @@ |
| 2 | | -== The basic theory == |
| | 2 | +This file provides an overview of the MediaWiki upgrade process. For help with |
| | 3 | +specific problems, check |
| 3 | 4 | |
| 4 | | -Generally, within a stable release series (e.g. 1.4.0, 1.4.1, etc) there |
| 5 | | -are no required database changes, and upgrading should require no more |
| 6 | | -than copying the new source files over the old ones. |
| | 5 | +* the documentation at http://meta.wikimedia.org |
| | 6 | +* the documentation at http://www.mediawiki.org |
| | 7 | +* the mediawiki-l mailing list archive at |
| | 8 | + http://mail.wikipedia.org/pipermail/mediawiki-l |
| | 9 | +* the bug tracker at http://bugzilla.wikimedia.org |
| 7 | 10 | |
| 8 | | -If there are larger changes, such as upgrading from one release series |
| 9 | | -to another (e.g. from 1.3.12 to 1.4.3), then you may need to update the |
| 10 | | -database schema and configuration. |
| | 11 | +for information and workarounds to common issues. |
| 11 | 12 | |
| 12 | | -Basically, to upgrade a wiki you: |
| 13 | | -* Back up your data! (See Backups! below) |
| 14 | | -* Extract the new archive. If you can do this in a clean directory that's |
| 15 | | - great, but it should work to extract over the old files too. This may |
| 16 | | - be easier if you have images etc in place and don't want to move them |
| 17 | | - around, but remember to back up first! |
| 18 | | -* Run the installer to upgrade the database schema (if necessary, |
| 19 | | - see sections below for details). |
| | 13 | +== Overview == |
| 20 | 14 | |
| | 15 | +* Documentation on upgrading from 1.5 to 1.6 can also be found at |
| | 16 | +http://www.mediawiki.org/wiki/Help:Upgrading_to_1.6 |
| 21 | 17 | |
| 22 | | -== IMPORTANT: Upgrading to 1.5 == |
| | 18 | +=== Consult the release notes === |
| 23 | 19 | |
| | 20 | +Before doing anything, stop and consult the release notes supplied with the new |
| | 21 | +version of the software. This detail bug fixes, new features and functionality, |
| | 22 | +and any particular points that may need to be noted during the upgrade |
| | 23 | +procedure. |
| | 24 | + |
| | 25 | +=== Backup first === |
| | 26 | + |
| | 27 | +It is imperative that, prior to attempting an upgrade of the database schema, |
| | 28 | +you take a complete backup of your wiki database and files and verify it. While |
| | 29 | +the upgrade scripts are somewhat robust, there is no guarantee that things will |
| | 30 | +not fail, leaving the database in an inconsistent state. |
| | 31 | + |
| | 32 | +Refer to the MySQL documentation for information on backing up a database. For |
| | 33 | +information on making copies of files, consult the documentation for your |
| | 34 | +operating system. |
| | 35 | + |
| | 36 | +=== Perform the file upgrade === |
| | 37 | + |
| | 38 | +Having downloaded the desired new version of the software, either as a package |
| | 39 | +from SourceForge, or via an export from Subversion, decompress the files as |
| | 40 | +needed, and replace the existing MediaWiki files with the new. |
| | 41 | + |
| | 42 | +You should preserve: |
| | 43 | + |
| | 44 | +* The LocalSettings.php file |
| | 45 | +* The AdminSettings.php file, where it exists |
| | 46 | +* The extensions directory |
| | 47 | +* The images directory |
| | 48 | + |
| | 49 | +If using an alternative uploads directory, preserve this; and if using custom |
| | 50 | +skins, preserve these too. The core code is now updated. |
| | 51 | + |
| | 52 | +=== Perform the database upgrade === |
| | 53 | + |
| | 54 | +You will need an AdminSettings.php file set up in the correct format; see |
| | 55 | +AdminSettings.sample in the wiki root for more information and examples. |
| | 56 | + |
| | 57 | +From the command line, browse to the maintenance directory and run the |
| | 58 | +update.php script to check and update the schema. This will insert missing |
| | 59 | +tables, update existing tables, and move data around as needed. In most cases, |
| | 60 | +this is successful and nothing further needs to be done. |
| | 61 | + |
| | 62 | +=== Check configuration settings === |
| | 63 | + |
| | 64 | +The names of configuration variables, and their default values and purposes, |
| | 65 | +can change between release branches, e.g. $wgDisableUploads in 1.4 is replaced |
| | 66 | +with $wgEnableUploads in later versions. When upgrading, consult the release |
| | 67 | +notes to check for configuration changes which would alter the expected |
| | 68 | +behaviour of MediaWiki. |
| | 69 | + |
| | 70 | +=== Test === |
| | 71 | + |
| | 72 | +It makes sense to test your wiki immediately following any kind of maintenance |
| | 73 | +procedure, and especially after upgrading; check that page views and edits work |
| | 74 | +normally and that special pages continue to function, etc. and correct errors |
| | 75 | +and quirks which reveal themselves. |
| | 76 | + |
| | 77 | +== Upgrading from pre-1.5 wikis == |
| | 78 | + |
| 24 | 79 | Major changes have been made to the schema from 1.4.x. The updater |
| 25 | 80 | has not been fully tested for all conditions, and might well break. |
| 26 | 81 | |
| 27 | | -DO NOT ATTEMPT TO UPGRADE A LIVE, PUBLIC SITE TO 1.5 AT THIS TIME. |
| 28 | | -NEVER EVER ATTEMPT TO PERFORM AN UPGRADE WITHOUT BACKING UP FIRST! |
| 29 | | - |
| 30 | 82 | On a large site, the schema update might take a long time. It might |
| 31 | 83 | explode, or leave your database half-done or otherwise badly hurting. |
| 32 | 84 | |
| — | — | @@ -47,7 +99,6 @@ |
| 48 | 100 | * A number of additional UI messages have been chagned from HTML to |
| 49 | 101 | wikitext, and will need to be manually fixed if customized. |
| 50 | 102 | |
| 51 | | - |
| 52 | 103 | === Configuration changes from 1.4.x: === |
| 53 | 104 | |
| 54 | 105 | $wgDisableUploads has been replaced with $wgEnableUploads. |