Add clarification to wfUseMW() phpdoc

While reviewing Ia5a7661c I happened to stumble in to the dark labyrinth
of PHP's version_compare() function. This comment attempts to leave
bread crumbs behind for the next unwary adventurer who stumbles into the
same damp cave.

The tricky bit is that when '1.22wmf22' is compared with '1.22'
internally it is as though you are comparing '1.22.wmf.22' with
'1.22.0.0'. By the component-wise comparison then performed 'wmf' is
considered the lowest priority value that could be in the third
position. When using '1.22c' for the required version the 'c' is given
the same lowest priority as 'wmf'.

Change-Id: I58aeb8dc6b1ff31897d72eb44904d96487ad3653

diff --git a/includes/GlobalFunctions.php b/includes/GlobalFunctions.php
index 77c09e5..dda0a40 100644 (file)
--- a/includes/GlobalFunctions.php
+++ b/includes/GlobalFunctions.php
@@ -3065,6 +3065,14 @@ function wfUsePHP( $req_ver ) {
  * This is useful for extensions which due to their nature are not kept in sync
  * with releases
  *
+ * Note: Due to the behavior of PHP's version_compare() which is used in this
+ * fuction, if you want to allow the 'wmf' development versions add a 'c' (or
+ * any single letter other than 'a', 'b' or 'p') as a post-fix to your
+ * targeted version number. For example if you wanted to allow any variation
+ * of 1.22 use `wfUseMW( '1.22c' )`. Using an 'a' or 'b' instead of 'c' will
+ * not result in the same comparison due to the internal logic of
+ * version_compare().
+ *
  * @see perldoc -f use
  *
  * @param $req_ver Mixed: the version to check, can be a string, an integer, or