Editing Manual/Upgrading (section)

== Frequently asked questions == <!--T:117-->
</translate>
<section begin=FAQ />
<translate>
===How hard is it to upgrade?=== <!--T:118-->

<!--T:119-->
If the only file you have modified is <tvar name=localsettings></tvar>, and you are upgrading from 1.5 or later, the process is very simple. The amount of human work involved is only a few minutes. The database schema changes will take an amount of time proportional to the size of your database — potentially hours for wikis with millions of pages, but for a more typical size of a few thousand pages, it is usually done in seconds.
</translate>

<translate><!--T:120--> Minor upgrades, within the same major version, say from <tvar name=1>.0</tvar> to <tvar name=2></tvar>, do not require any schema changes at all.</translate>
<translate><!--T:218--> You can just update the files. The database needs no update, hence it is not necessary to run the updater script.</translate>

<translate>
<!--T:121-->
Upgrading from 1.4 or earlier is potentially complicated because support for character sets other than UTF-8 was dropped, and the schema for storing bulk text changed. Please read the relevant section in the <code>UPGRADE</code> file.

<!--T:122-->
Upgrading becomes difficult if you have modified our source code, and you don't want your changes to be overwritten. Tools such as <tvar name=diff>[http://www.gnu.org/software/diffutils/diffutils.html diff]</tvar>, <tvar name=patch>[http://www.gnu.org/software/patch/ patch]</tvar>, <tvar name=meld>[http://meldmerge.org/ Meld]</tvar> or <tvar name=winmerge>[http://winmerge.org/ WinMerge]</tvar> may be useful. There is also potential for trouble if you are using unmaintained extensions. Upgrade your extensions at the same time as you upgrade MediaWiki.

<!--T:123-->
If you have modified the skin or use a custom skin, you very likely will have to adjust it to work again with the new version of MediaWiki.
</translate>

{{Tip|1=<translate><!--T:124--> Instead of patching your "global" CSS and JS (JavaScript) files every time, you can simply add the code to your MediaWiki:Common.js and MediaWiki:Common.css pages. As these are part of the database which will be reused when you upgrade, you will not have to patch the MediaWiki core files any more.</translate>}}

<translate>
===How do I upgrade from a really old version? In one step, or in several steps?=== <!--T:125-->
</translate>

<translate><!--T:126--> It depends: If you are '''upgrading from MediaWiki 1.4 or older''', you should upgrade to MediaWiki 1.5 first.</translate>
<translate><!--T:560--> If you are upgrading from a Latin-1 wiki, use upgrade1_5.php (found in MediaWiki 1.5) to convert the relevant parts of the database to UTF-8 (<tvar name=latin></tvar> needs to be set to true in your <tvar name=localsettings></tvar> for this to work).</translate>
<translate><!--T:561--> Next, run <tvar name=1><code>update.php</code></tvar>, and then set the <tvar name=2></tvar> option in <tvar name=3><code>LocalSettings.php</code></tvar> to the encoding previously used by the wiki (e.g. windows-1252).</translate>
<translate><!--T:614--> This is basically how Wikipedia and other Wikimedia Foundation sites were upgraded from MediaWiki 1.4 to 1.5 – see some [[<tvar name=4>wikitech:Obsolete:1.5 upgrade</tvar>|related notes at Wikitech]].</translate>
<translate><!--T:562--> You may need to upgrade to MediaWiki 1.4 before running the upgrade1.5 script.</translate>
<translate><!--T:175--> If you want to make a database dump (e.g. MySQL) of your Latin-1 wiki, make sure the type of the <tvar name=1><code>old_text</code></tvar> field in the <tvar name=2></tvar> table is <tvar name=3><code>mediumblob</code></tvar>, not <tvar name=4><code>mediumtext</code></tvar>, to avoid character encoding issues.</translate>

<translate><!--T:127--> If you are '''upgrading from MediaWiki 1.5 or newer''' to '''1.35''', you can upgrade in one step.</translate>
<translate><!--T:225--> The vast majority of reports, as well as automated testing, indicated that doing it in one step works just fine.</translate>
<translate><!--T:226--> If you have trouble believing this, read [[<tvar name=mail>mailarchive:mediawiki-l/2008-October/028975.html</tvar>|this mailing list post]].</translate>
<translate><!--T:227--> However, please note that when you update from old versions, chances that you will encounter PHP errors are bigger than when you upgrade from the version directly previous to the new version.</translate>
<translate><!--T:228--> You would have received these errors anyway, had you not skipped versions, but the errors would have been associated with each individual update.</translate>
<translate><!--T:229--> Instead, if you update several versions at once, you'll get the same set of errors all at the same time.</translate>
<translate><!--T:230--> This will make the upgrade more difficult, but do not forget that you did not have the trouble of updating to the intermediate versions, which you skipped!</translate>

<translate><!--T:240--> If you are '''upgrading to MediaWiki 1.36''' or later, only upgrades from the last two LTS releases are supported (<tvar name=1>[[phab:T259771]]</tvar>).</translate>
<translate><!--T:616--> This will mean that for very old versions, that you first upgrade to MediaWiki 1.35 and then upgrade to 1.43, and then (if you want to upgrade to a non-LTS version) upgrade to <tvar name=1></tvar>.</translate>

<translate>
===Should I back up first?=== <!--T:129-->

<!--T:130-->
Short answer: Yes.

<!--T:131-->
Long answer: It depends on a) how much you value your data, b) how hard it is to create a backup and c) how confident you are with MySQL maintenance and administration. 
</translate>

<translate><!--T:132--> An upgrade failure may leave your database in an inconsistent state, in between two versions.</translate>
<translate><!--T:231--> A PHP or MySQL error might happen during upgrade leaving your database partly upgraded.</translate>
<translate><!--T:232--> In such situations it may be possible to somehow fix this problem with much manual work.</translate>
<translate><!--T:233--> However, it will be ''way easier'' to just put a database backup from before running update.php in place and to continue with that.</translate>
<translate><!--T:234--> Otherwise you might have hours of - needless - work.</translate>

<translate><!--T:133--> Recovery is often complex.</translate>
<translate><!--T:235--> Volunteers on the support forums are unlikely to be impressed if you neglect to make a backup and then need help to recover from upgrade-related corruption.</translate>
<translate><!--T:236--> A better outcome is if you can revert to your backup, and then [[<tvar name=1>phab:maniphest/task/create/</tvar>|report the bug against the corresponding MediaWiki project]] in the upgrade process which caused the corruption.</translate>

<translate>
===Can I keep my <tvar name=1><code>LocalSettings.php</code></tvar>?=== <!--T:134-->
</translate>
<translate><!--T:135--> Yes, but you may have to make some minor changes. The format of <tvar name=1></tvar> is largely backward compatible.</translate>
<translate><!--T:563--> Changes which break <tvar name=1>LocalSettings.php</tvar> compatibility will be documented in the "configuration changes" section of the [[<tvar name=2>Special:MyLanguage/Release notes</tvar>|release notes]].</translate>

<translate>
===Can my wiki stay online while it is upgrading?=== <!--T:136-->

<!--T:137-->
Generally yes, however if you upgrade via Git, Git may temporarily (for a few seconds) break it.

<!--T:138-->
If you are upgrading between minor releases of MediaWiki, all you need to do is update the source files.

<!--T:139-->
Note: the following assumes you have command line access. If you are upgrading between major releases of MediaWiki, the preferred procedure is as follows:
</translate>

# <translate><!--T:140--> Unpack the new version of MediaWiki into a new directory</translate>
# <translate><!--T:201--> Prepare that new directory: copy your current <tvar name=1><code>LocalSettings.php</code></tvar> from the old directory, copy any installed extensions and custom skins (if any).</translate> <translate><!--T:599--> Check <tvar name=1></tvar> and <tvar name=2></tvar> settings in <tvar name=3><code>LocalSettings.php</code></tvar> and if necessary copy logo file from the old directory to the new directory.</translate>
# <translate><!--T:202--> In the release notes for the new version, see if any changes need to be made to <tvar name=1><code>LocalSettings.php</code></tvar>.</translate>
# <translate><!--T:579--> In the old directory, edit <tvar name=1>LocalSettings.php</tvar> and insert the following code.</translate> <translate><!--T:580--> This will place the database in read-only mode for regular wiki activity, without restricting your own update actions.</translate> <translate><!--T:581--> Users will see the message provided if they attempt an edit during the upgrade process:</translate><br /><div class="mw-highlight mw-highlight-lang-php"><div class="mw-code">$adminTask = (  ===  || (  ) );<br /> = $adminTask ?  : '|class=s1}};</div></div>
# <translate><!--T:205--> Run the [[<tvar name=upg>Special:MyLanguage/Manual:Upgrading#Command_line_2</tvar>|update script]] or the web updater in the new directory.</translate>
# <translate><!--T:206--> Copy the images from the images sub-directory from the old directory to the new directory.</translate>
# <translate><!--T:207--> Swap the old directory and the new directory.</translate> <translate><!--T:582--> (This will make the database writable again, because <tvar name=1></tvar> was only set in the old directory's <tvar name=2>LocalSettings.php</tvar>.)</translate>

<translate>
===Why upgrade?=== <!--T:141-->
</translate>
:''<translate><!--T:142--> Subscribe to <tvar name=announce>[[mail:mediawiki-announce|mediawiki-announce]]</tvar> to be notified of new releases.</translate>''

<translate>
<!--T:143-->
Recent releases receive security fixes to keep your wiki and your host safe from vandals, while old releases don't (see <tvar name=lifecycle></tvar>).

<!--T:144-->
New major releases come with new features, which you might want to use: see the [[<tvar name=1>Special:MyLanguage/Release notes</tvar>|release notes]] for details.
</translate>
<section end=FAQ />

<translate>