Bureaucrats, confirmed, Administrators
4,558
edits
Changes
MediaWiki/Upgrade/REL1 25 to REL1 26 (view source)
Revision as of 01:07, 8 April 2006
, 01:07, 8 April 2006no edit summary
=== Overview ===
I just upgraded my wiki site, and thought I would write down the steps for further reference. Even though the instructions that come with the source are very detailed, I find it helpful to note my personal preferences, observations, and clarifications where I might not understand the instructions.
The process obviously started with downloading the source from the web. I saved it locally to the site where it's installed, above the docroot so that it wasn't accessible to site visitors. I uncompressed it after checking that it wouldn't accidentally overwrite an existing directory.
I performed a diff of the entire tree v. my installed copy using the venerable KDiff3 to get an idea of the magnitude of the code changes; to learn by reading some code changes and get a feel for the 'current best practices'. It also helped me to see what old stuff was deprecated, or that I had lying around as cruft on my filesystem. I figured that when I updated my files with rsync, I would use the --delete switch to remove any of the cruft on the target.
=== 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
procedure.
=== Backup first ===
I copied my filesystem as a backup. This is not explicitly mentioned in the UPGRADE file, but obvious if you want to be able to revert.
I copied my database as a backup. I noticed that phpMyAdmin failed silently to create a backup because it exhausted the PHP memory limit. When I say 'failed silently' I mean that it saved the export as a compressed file on my system without complaining, but the contents of that file were the plain-text error message from PHP. I could have increased the script memory limit, but instead I used mysql-admin. The Mysql Administrator client had it's own bug, in that one of my prior backup profiles was somehow corrupt (maybe it no longer existed on the filesystem?) and Mysql Administrator would crash whenever I clicked on that profile. I'll have to figure out if there is a setting file where I can manually remove this 'profile' to prevent further crashes.
=== 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.
I did all of those because I do have an 'accessible' skin. The easy way to do the filesystem upgrade is with the rsync command. Besides the filesystem update, you also need to create a AdminSettings.php file with credentials to access your database.
:<code>user@host:/path/to/docroot$ rsync -vrc --delete --stats --progress --exclude images/ --exclude extensions/ --exclude LocalSettings.php --exclude skins/disabled/ mediawiki-1.6.1/ wiki</code>
=== 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.
<pre>
cd wiki/maintenance/
ls
php ./update.php
</pre>
=== 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.
I just upgraded my wiki site, and thought I would write down the steps for further reference. Even though the instructions that come with the source are very detailed, I find it helpful to note my personal preferences, observations, and clarifications where I might not understand the instructions.
The process obviously started with downloading the source from the web. I saved it locally to the site where it's installed, above the docroot so that it wasn't accessible to site visitors. I uncompressed it after checking that it wouldn't accidentally overwrite an existing directory.
I performed a diff of the entire tree v. my installed copy using the venerable KDiff3 to get an idea of the magnitude of the code changes; to learn by reading some code changes and get a feel for the 'current best practices'. It also helped me to see what old stuff was deprecated, or that I had lying around as cruft on my filesystem. I figured that when I updated my files with rsync, I would use the --delete switch to remove any of the cruft on the target.
=== 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
procedure.
=== Backup first ===
I copied my filesystem as a backup. This is not explicitly mentioned in the UPGRADE file, but obvious if you want to be able to revert.
I copied my database as a backup. I noticed that phpMyAdmin failed silently to create a backup because it exhausted the PHP memory limit. When I say 'failed silently' I mean that it saved the export as a compressed file on my system without complaining, but the contents of that file were the plain-text error message from PHP. I could have increased the script memory limit, but instead I used mysql-admin. The Mysql Administrator client had it's own bug, in that one of my prior backup profiles was somehow corrupt (maybe it no longer existed on the filesystem?) and Mysql Administrator would crash whenever I clicked on that profile. I'll have to figure out if there is a setting file where I can manually remove this 'profile' to prevent further crashes.
=== 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.
I did all of those because I do have an 'accessible' skin. The easy way to do the filesystem upgrade is with the rsync command. Besides the filesystem update, you also need to create a AdminSettings.php file with credentials to access your database.
:<code>user@host:/path/to/docroot$ rsync -vrc --delete --stats --progress --exclude images/ --exclude extensions/ --exclude LocalSettings.php --exclude skins/disabled/ mediawiki-1.6.1/ wiki</code>
=== 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.
<pre>
cd wiki/maintenance/
ls
php ./update.php
</pre>
=== 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.