[MNG-7559] Improve documentation of versions comparison

[sultan]

Fix versions comparison https://issues.apache.org/jira/browse/MNG-7559
intention is:

• 1.0.0.RC1 < 1.0.0-RC2
• ( edr, pfd, etc.) < final, ga, release
• 9.4.1.jre16 > 9.4.1.jre16-preview

following semver rules should be encouraged, natural ordering is used without the need to hard code strings, except for hard coded qualifiers 'a', 'b', 'm', 'cr', 'snapshot', 'final', 'ga', 'release', '' and 'sp':

• alpha = a < beta = b < milestone = m < rc = cr < 'snapshot' < '' = 'final' = 'ga' = 'release' < 'sp'

the documentation should discourage the usage of 'CR', 'final', 'ga', 'release' and 'SP' qualifiers.
Maven Central should begin to reject new artifact using CR and SP qualifiers.

[sultan]

code:

• PR [MNG-7559] Fix versions comparison maven#845

documentation:

• PR [MNG-7559] Improve documentation of versions comparison #331

[sultan]

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

[elharo]

It would be helpful to separate formatting and language changes from functionality changes.

[elharo]

This is related to MNG-7559 but does not seem to fix it. It merely changes docs. That issue requests changes in behavior.

[sultan]

reverted one comparison, and added another test case to prove website documentation right

[sultan]

i think i resolved everything, thank you for your feedback. waiting approval of last fixes.

[sultan]

This is related to MNG-7559 but does not seem to fix it. It merely changes docs. That issue requests changes in behavior.

The test cases for MNG 7559 are here:

maven-artifact/src/test/java/org/apache/maven/artifact/versioning/ComparableVersionTest.java

     * Test <a href="https://issues.apache.org/jira/browse/MNG-7559">MNG-7559</a> edge cases
     * 1.0.0.RC1 < 1.0.0-RC2
     * -pfd < final, ga, release
     * 2.0.1.MR < 2.0.1
     * 9.4.1.jre16 > 9.4.1.jre16-preview
     */
    @Test
    public void testMng7559()
    {
        checkVersionsOrder( "1.0.0.RC1", "1.0.0-RC2" );
        checkVersionsOrder( "4.0.0.Beta3", "4.0.0-RC2" );
        checkVersionsOrder( "2.3-pfd", "2.3" );
        checkVersionsOrder( "2.0.1.MR", "2.0.1" );
        checkVersionsOrder( "9.4.1.jre16-preview", "9.4.1.jre16" );
        checkVersionsEqual( "2.0.a", "2.0.0.a" ); // previously ordered, now equals
        checkVersionsOrder( "1-sp-1", "1-ga-1" ); // proving website documentation right.
    }

of all the error cases 2.3-pfd was the first declared on the issue and fixed.

did i miss something ?