Difference between revisions of "WikiDB/Versioning"

From TestWiki
Jump to: navigation, search
(Clarify minor DB updates for edge-cases.)
(Updating page to reflect changes I to the versioning scheme that will come into play as-of the next release.)
Line 1: Line 1:
−
I don't believe in sitting on a 0.x release branch for the rest of my life.  Furthermore, as I am in the habit of releasing changes as they are made it doesn't make sense to have to manually update  the version number every time I update the code.
+
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.
  
−
Therefore, the version-numbering system I have adopted for '''WikiDB''' is based on two numbers:
+
'''''See also:''' [[WikiDB/CHANGELOG|Release History]], [[WikiDB/Upgrading|Upgrading]].
−
 
+
−
* 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 is 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.
+
  
 
== Finding the version number ==
 
== Finding the version number ==
  
−
The version number can be seen on the [[Special:Version]] page on your wiki.  If your installation doesn't display a version number, it is v1.  If it doesn't have a revision either, it is very old and you should definitely upgrade!
+
The version number can be seen on the [[Special:Version]] page on your wiki.  If your installation just displays a revision number it is v1.  If it doesn't have a revision either, it is very old and you should definitely upgrade!
  
 
== Version numbers and upgrades ==
 
== Version numbers and upgrades ==
Line 15: Line 11:
 
When upgrading WikiDB, you should check the version number to decide whether any [[WikiDB/Maintenance scripts|maintenance scripts]] need to be run.
 
When upgrading WikiDB, you should check the version number to decide whether any [[WikiDB/Maintenance scripts|maintenance scripts]] need to be run.
  
−
* If the version number has changed then you will need to run one or more maintenance scripts to upgrade your stored data to work with the latest version.  Be warned - if you upgrade the extension's code without also updating your data, your wiki is liable to break, albeit temporarily.  The details for any particular version upgrade are described on the [[WikiDB/Changes|changes]] page.
+
* 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 [[WikiDB/Tutorial: Creating your own data type|custom data types]]) you may also be required to update your customisations to maintain compatibility with the latest release.  The [[WikiDB/CHANGELOG|release notes]] will contain full details about any potential issues.
−
* If the version number has not changed, then you don't need to run any scripts - just copy the files into place.
+
** '''''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.
 
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 <code>X.Y.Z</code>, where <code>X</code> is the major version number, <code>Y</code> is the minor version number and <code>Z</code> is the patch number, following the semantics described below:
 +
 +
* <code>X</code> is incremented (and <code>Y</code> and <code>Z</code> are reset to zero) if ''any'' of the following are true for the new release:
 +
*# 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.
 +
*# The upgrade introduces breaking changes to any of the APIs that may be used to extend WikiDB (e.g. the [[WikiDB/Tutorial: Creating your own data type|custom data type API]]).
 +
*# The upgrade contains changes to user-visible messages that are likely to affect existing message customisations (e.g. message key is renamed, messages are split/combined or there are significant changes to the meaning of a message).
 +
*# The upgrade drops support for any previously-supported versions of MediaWiki or PHP.
 +
*# The upgrade includes changes to the software license that make it more restrictive.
 +
* <code>Y</code> is incremented (and <code>Z</code> is reset to zero) if none of the above apply, but the release introduces new user-visible functionality.
 +
* <code>Z</code> is incremented in all other situations, which includes (but is not limited to) the following:
 +
*# Bug fixes.
 +
*# Forward-compatibility fixes for new versions of MediaWiki.
 +
*# Performance optimisations.
 +
*# Cosmetic changes to layout/styling.
 +
*# Changes to user-visible messages that are unlikely to affect existing message customisations (including the addition of new messages).
 +
*# New translations.
 +
*# 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: <code>v4 (r1376)</code>.
 +
 +
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! ==
 
== 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 [[WikiDB/Compatibility|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.
 
If you are a user of the extension, it would be very useful if you could add yourself to the [[WikiDB/Compatibility|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.

Revision as of 23:20, 4 May 2018

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.

Finding the version number

The version number can be seen on the Special:Version page on your wiki. If your installation just displays a revision number it is v1. If it doesn't have a revision either, it is very old and 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 affect 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 affect 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.

Retrieved from ‘https://www.kennel17.co.uk/testwiki/index.php?title=WikiDB/Versioning&oldid=19161’