Difference between revisions of "WikiDB/Upgrading"

From TestWiki
Jump to: navigation, search
m (tweaks)
(Upgrading WikiDB: Updated in the light of changes to the versioning scheme.)
Line 38: Line 38:
 
=== Step 2: DB updates ===
 
=== Step 2: DB updates ===
  
WikiDB is versioned using a version number and a revision, e.g. <code>version 3, r542</code>.  If the version number has not changed, then you do not need to make any changes to the database.
+
WikiDB is versioned using [[WikiDB/Versioning|semantic versioning]] so it is easy to tell whether or not there may be additional upgrade steps, including DB updates.
  
If the version number has changed, this indicates that some changes to the DB are required.  Check the release notes for the specifics, and see [[WikiDB/Maintenance scripts]] for details about running the scripts that it mentions.
+
If the major version number has not changed (e.g. '''5'''.2.0 -> '''5'''.3.1), then you will not need to make any changes to the database.  However, if this is a major upgrade (e.g. '''5'''.2.0 -> '''6'''.0.2) then there may be DB changes required.  Check the [[WikiDB/CHANGELOG|release notes]] for the specifics, and see [[WikiDB/Maintenance scripts]] for details about running any scripts that are mentioned.
  
If you can't find the release notes, or are completely paranoid, here's the full set of commands you may need to run on an upgradeIn practice some of these may not be required (or may be runnable with different options, which would save time):
+
If you can't find the release notes, or are completely paranoid, here's the full set of commands to ensure the WikiDB database is fully up-to-dateThese are non-destructive and so are always safe to run, but they may be slow on large wikis:
  
 
<bash>
 
<bash>
Line 49: Line 49:
 
$ php RebuildWikiDB.php --wipefirst
 
$ php RebuildWikiDB.php --wipefirst
 
</bash>
 
</bash>
 +
 +
=== Other considerations ===
 +
 +
* If you have local message customisations then you may need to update them when upgrading.  The release notes will indicate any breaking changes to existing messages (which will only occur on a major version number increment) but you are recommended to check [{{fullurl:Special:AllMessages|prefix=wikidb-}} Special:AllMessages] to ensure that nothing is missed.  Note that all messages start with the prefix <code>wikidb_</code>.
 +
* If you have any local WikiDB extensions (e.g. [[WikiDB/Tutorial: Creating your own data type|custom data types]]) then a major release of WikiDB may include API changes that could cause your code to break.  You should test your code on the latest version of WikiDB before upgrading.
 +
 +
In all cases, changes of this nature will be detailed in the release notes, along with appropriate upgrade instructions (where relevant).

Revision as of 23:00, 4 May 2018

This page explains how to upgrade WikiDB, along with any WikiDB-specific considerations when upgrading MediaWiki itself.

Upgrading MediaWiki

In theory, you should not need to perform any additional steps when upgrading MediaWiki, in relation to WikiDB.

In practice, there is always the possibility that a new version of MW will cause problems for existing extensions. These largely fall into three categories, which are as follows:

The wiki doesn't work at all after the upgrade
This could happen for a million reasons, so you will need to do some trouble-shooting. These instructions apply to all extensions, not just WikiDB.
  1. First, disable all extensions by commenting out the include() lines in LocalSettings.php. Check that MediaWiki itself is working properly when no extensions are installed - it may be that the bug/incompatibility is in MediaWiki itself.
  2. Enable your extensions one-by-one and re-test. This should help you to pinpoint the extension that is causing the problem.
  3. Upgrade the offending extension. The problem may be fixed in a more recent version.
  4. If the problem still exists in the latest version of the extension then you have two choices:
    1. Downgrade MediaWiki to the previous version, and wait for the extension to be made compatible.
    2. Run MediaWiki with that extension disabled.
In either case you should contact the extension author to let them know about the problem, and encourage them to fix it.
The wiki works, but has error messages or unexpected functionality
In general, the same rules apply as for the previous item, so follow the above steps. However, in this case you may find that there are ways to work around the problem (or that it is OK to ignore from the time-being) which mean you are able to continue using the upgraded version without having to disable the extension.
The wiki works fine, however you get unexpected output (odd or missing data, unexpected formatting, etc.)
This may occur for one of two reasons - either the way MW renders something has changed, or the way that data is parsed has been altered in a way that affects WikiDB.
  1. Make sure you have upgraded to the latest version of WikiDB, which may have fixed the issue.
  2. Run RebuildWikiDB.php with the --wipefirst argument, to re-parse the entire wiki and re-populate the cached WikiDB data. This can be very slow for large wikis, but it will ensure that all data is completely up-to-date.
  3. If you are still experiencing problems, please contact me and I will look into it for you.

Upgrading WikiDB

Step 1: Download and install the latest code

You can download the latest version of WikiDB as a zipped archive.

Download WikiDB Here!
or visit the file description page for a bit more information (e.g. version details, etc).

You should delete your existing WikiDB code folder, and extract the downloaded file in its place.

Step 2: DB updates

WikiDB is versioned using semantic versioning so it is easy to tell whether or not there may be additional upgrade steps, including DB updates.

If the major version number has not changed (e.g. 5.2.0 -> 5.3.1), then you will not need to make any changes to the database. However, if this is a major upgrade (e.g. 5.2.0 -> 6.0.2) then there may be DB changes required. Check the release notes for the specifics, and see WikiDB/Maintenance scripts for details about running any scripts that are mentioned.

If you can't find the release notes, or are completely paranoid, here's the full set of commands to ensure the WikiDB database is fully up-to-date. These are non-destructive and so are always safe to run, but they may be slow on large wikis:

$ cd /path/to/mediawiki/extensions/WikiDB/maintenance
$ php SetupTables.php
$ php RebuildWikiDB.php --wipefirst

Other considerations

  • If you have local message customisations then you may need to update them when upgrading. The release notes will indicate any breaking changes to existing messages (which will only occur on a major version number increment) but you are recommended to check Special:AllMessages to ensure that nothing is missed. Note that all messages start with the prefix wikidb_.
  • If you have any local WikiDB extensions (e.g. custom data types) then a major release of WikiDB may include API changes that could cause your code to break. You should test your code on the latest version of WikiDB before upgrading.

In all cases, changes of this nature will be detailed in the release notes, along with appropriate upgrade instructions (where relevant).