WikiDB/Versioning

From TestWiki
< WikiDB
Revision as of 21:11, 30 March 2019 by HappyDog (Talk | contribs) (Finding the version number: Was a bit confusingly written...)

Jump to: navigation, search

This page explains how you should interpret WikiDB version numbers. The versioning scheme has changed a couple of times over the history of the extension.

See also: Release History, Upgrading, Legacy Versions.

Finding the version number

The version number can be seen on the Special:Version page on your wiki.

Very old versions of WikiDB might display just a revision number without a version number. Very, very old versions may not display any version information at all. In either case you are running a buggy version of WikiDB with very limited functionality; you should definitely upgrade!

Version numbers and upgrades

When upgrading WikiDB, you should check the version number to decide whether any maintenance scripts need to be run.

  • If the major version number has changed then you may need to run one or more maintenance scripts to upgrade your stored data to work with the latest version. If you have customised the extension (e.g. adding your own custom data types) you may also be required to update your customisations to maintain compatibility with the latest release. The release notes will contain full details about any potential issues.
    • Warning: Failure to run any upgrade scripts may render your wiki (temporarily) inoperable or may result in incorrect or stale data being displayed.
    • Make sure you check the release notes for all major releases between your current version and the version you are upgrading from, else you may miss important upgrade steps. For example, if you are upgrading from 5.x to 7.x you should read the release notes for both 6.0.0 and 7.0.0.
    • All of the command-line scripts are non-destructive and safe to run at any time, so if you are unsure about whether a script should be run it is probably best to run it.
    • For large wikis, some of the scripts may take a long time to complete. You should factor this into your upgrade process.
  • If the major version number has not changed, then you don't need to run any scripts and there should be no breaking changes - just copy the files into place.

See WikiDB/Upgrading for more info.

Versioning schemes

Current versioning scheme

As of WikiDB 5.0.0, the extension uses semantic versioning.

The version number is of the form X.Y.Z, where X is the major version number, Y is the minor version number and Z is the patch number, following the semantics described below:

  • X is incremented (and Y and Z are reset to zero) if any of the following are true for the new release:
    1. The upgrade requires (or strongly recommends) that you run one or more command-line scripts.
      • This will occur if the back-end DB schema has changed or if the parsing rules are significantly modified.
      • If it is a weak recommendation, e.g. due to edge-case changes to parsing rules that are unlikely to affect anyone in practice, then this will not trigger a major version increment.
    2. The upgrade introduces breaking changes to any of the APIs that may be used to extend WikiDB (e.g. the custom data type API).
    3. The upgrade contains changes to user-visible messages that are likely to break existing message customisations (e.g. message key is renamed, messages are split/combined or there are significant changes to the meaning of a message).
    4. The upgrade drops support for any previously-supported versions of MediaWiki or PHP.
    5. The upgrade includes changes to the software license that make it more restrictive.
  • Y is incremented (and Z is reset to zero) if none of the above apply, but the release introduces new user-visible functionality.
  • Z is incremented in all other situations, which includes (but is not limited to) the following:
    1. Bug fixes.
    2. Forward-compatibility fixes for new versions of MediaWiki.
    3. Performance optimisations.
    4. Cosmetic changes to layout/styling.
    5. Changes to user-visible messages that are unlikely to break existing message customisations (including the addition of new messages).
    6. New translations.
    7. Changes to the software license that make it more permissive.

Versioning scheme for v2 to v4

Prior to v5.0.0, the version-numbering system for WikiDB was based on two numbers, the version and the revision. It looked something like this: v4 (r1376).

These version numbers should be interpreted as follows:

  • The version number is an integer which is incremented manually whenever changes are made that require modifications to the internal database. This includes changes to the internal schema, and any changes to the way data is stored that may require reparsing existing pages of the wiki. Note that changes that may require a DB update for some users, but which are not thought to be required in the majority of cases will not cause the version number to change.
  • The revision number is incremented automatically every time I make any changes at all to the code or to other unrelated code that sits in the same repository. The revision number for each file can be seen at the top of the file, and the revision number for the extension is the highest of these numbers.

Versioning scheme for older releases

Very old versions of WikiDB didn't have a version number at all, just a revision number. Very, very old versions didn't have any kind of versioning at all. If you are using one of these versions then you are strongly recommended to upgrade!

Let me know what you're using!

If you are a user of the extension, it would be very useful if you could add yourself to the compatibility page. This allows me to keep an eye of what versions of WikiDB are currently in use and, more importantly, what versions of MediaWiki. This helps me decide which older versions I might need to support if I decide to upgrade the minimum requirements, and where I should focus my testing.