Difference between revisions of "WikiDB/Versioning"

From TestWiki
Jump to: navigation, search
(Finding the version number: Was a bit confusingly written...)
(Versioning schemes: Improved last edit, about pre-release versions.)
 
(3 intermediate revisions by the same user not shown)
Line 45: Line 45:
 
*# Cosmetic changes to layout/styling.
 
*# Cosmetic changes to layout/styling.
 
*# Changes to user-visible messages that are unlikely to break existing message customisations (including the addition of new messages).
 
*# Changes to user-visible messages that are unlikely to break existing message customisations (including the addition of new messages).
*# New translations.
+
*# Localisation updates (new languages, translation updates, etc.).
 
*# Changes to the software license that make it more permissive.
 
*# Changes to the software license that make it more permissive.
 +
 +
In addition, pre-release versions may occasionally be distributed, in which case they will have an additional suffix, e.g. <code>-beta1</code>.  These versions are for private distribution and are broadly equivalent to the subsequent formal release (e.g. <code>5.1.0-beta1</code> would ultimately be released as <code>5.1.0</code>).  These versions do not have explicit release notes, will not be listed on this page and will not have any documentation as to how they differ from the version that is ultimately released.
  
 
=== Versioning scheme for v2 to v4 ===
 
=== Versioning scheme for v2 to v4 ===
Line 54: Line 56:
 
These version numbers should be interpreted as follows:
 
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 '''version''' number is an integer which was incremented manually whenever changes were made that required modifications to the internal database.  This included 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 did 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.
+
* The '''revision''' number was incremented automatically every time I made 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 ===
 
=== Versioning scheme for older releases ===

Latest revision as of 21:01, 7 February 2022

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[edit]

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[edit]

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[edit]

Current versioning scheme[edit]

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. Localisation updates (new languages, translation updates, etc.).
    7. Changes to the software license that make it more permissive.

In addition, pre-release versions may occasionally be distributed, in which case they will have an additional suffix, e.g. -beta1. These versions are for private distribution and are broadly equivalent to the subsequent formal release (e.g. 5.1.0-beta1 would ultimately be released as 5.1.0). These versions do not have explicit release notes, will not be listed on this page and will not have any documentation as to how they differ from the version that is ultimately released.

Versioning scheme for v2 to v4[edit]

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 was incremented manually whenever changes were made that required modifications to the internal database. This included 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 did not cause the version number to change.
  • The revision number was incremented automatically every time I made 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[edit]

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![edit]

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.