Fix versions comparison

content/apt/pom.apt.vm

@@ -511,33 +511,53 @@ mvn install:install-file -Dfile=non-maven-proj.jar -DgroupId=some.group -Dartifa
 
     * Non-numeric tokens ("qualifiers") have the alphabetical order, except for the following tokens which come first in this order:
 
-    "<<<alpha>>>" \< "<<<beta>>>" \< "<<<milestone>>>" \< "<<<rc>>>" = "<<<cr>>>" \< "<<<snapshot>>>" \< "" = "<<<final>>>" = "<<<ga>>>" \< "<<<sp>>>"
+    "<<<alpha>>>" \< "<<<beta>>>" \< "<<<milestone>>>" \< "<<<rc>>>" \< "<<<snapshot>>>" \< "" = "<<<final>>>" = "<<<ga>>>"
 
         * the "<<<alpha>>>", "<<<beta>>>" and "<<<milestone>>>" qualifiers can respectively be shortened to "a", "b" and "m" when directly followed by a number.
 
   * else "<<<.qualifier>>>" = "<<<-qualifier>>>" \< "<<<-number>>>" \< "<<<.number>>>"
 
+  []
+
+   following semver rules is encouraged, string qualifiers are ordered lexically,
+   except for some qualifiers: 'snapshot', 'final', 'ga', 'release' and ''.
+   for other qualifiers natural ordering is used:
+     * alpha = a < beta = b < ea < milestone = m < preview < rc < 'snapshot' < '' = 'final' = 'ga' = 'release'
+
+  []
+
+   the usage of 'CR' qualifier is discouraged, use 'RC' instead.
+   the usage of 'SP' qualifier is discouraged, use version increment instead.
+     * in Maven 3: 'cr' = 'rc' < 'snapshot' < '' < 'sp'
+     * in Maven 4: 'cr' < 'rc' < 'sp' < 'snapshot' < ''
+
+  []
+
+   the usage of 'final', 'ga', 'release' qualifiers is discouraged, use no qualifier instead.
+     * in Maven 4: 'snapshot' < 'final' = 'ga' = 'release' = ''
+     * in a next major version of Maven, say Maven 5, we might have: 'final' < 'ga' < 'release' < 'snapshot' < ''
+
   []
 
   End Result Examples:
 
   * "<<<1>>>" \< "<<<1.1>>>" (number padding)
 
-  * "<<<1-snapshot>>>" \< "<<<1>>>" \< "<<<1-sp>>>" (qualifier padding)
+  * "<<<1-snapshot>>>" \< "<<<1>>>" (qualifier padding)
 
   * "<<<1-foo2>>>" \< "<<<1-foo10>>>" (correctly automatically "switching" to numeric order)
 
   * "<<<1.foo>>>" = "<<<1-foo>>>" \< "<<<1-1>>>" \< "<<<1.1>>>"
 
-  * "<<<1.ga>>>"  = "<<<1-ga>>>"  = "<<<1-0>>>" = "<<<1.0>>>" = "<<<1>>>" (removing of trailing "null" values)
+  * "<<<1.ga>>>" = "<<<1-ga>>>" = "<<<1-0>>>" = "<<<1.0>>>" = "<<<1>>>" (removing of trailing "null" values)
 
-  * "<<<1-sp>>>"   \> "<<<1-ga>>>"
+  * "<<<1-sp>>>" \< "<<<1-ga>>>"
 
-  * "<<<1-sp.1>>>"  \> "<<<1-ga.1>>>"
+  * "<<<1-sp.1>>>" \< "<<<1-ga.1>>>"
 
   * "<<<1-sp-1>>>" \< "<<<1-ga-1>>>" = "<<<1-1>>>" (trailing "null" values at each hyphen)
 
-  * "<<<1-a1>>>"  = "<<<1-alpha-1>>>"
+  * "<<<1-a1>>>" = "<<<1-alpha-1>>>"
 
   Note: Contrary to what was stated in some design documents, for version order, snapshots are not treated differently than releases or any other qualifier.