REQUIRE version specification syntax is a common source of confusion

[ssfrr]

in #7757 @IainNZ brought up that the REQUIRE syntax is a source of confusion for a pretty large number of people, so I figured it might be worth an issue to brainstorm.

see https://pythonhosted.org/setuptools/pkg_resources.html#requirement-objects for how setuptools in python parses package requirements.

https://pythonhosted.org/setuptools/pkg_resources.html#parsing-utilities describes how version numbers comparison works (e.g. trailing .0s are dropped, so 2.4 is equivalent to 2.4.0)

Certainly complicates the parser, but at least there's a formal spec given.

In the interest of having an example in the thread:

FooProject >= 1.2
PickyThing<=1.6,!=1.9.6,<2.0,==2.4.0
SomethingWhoseVersionIDontCareAbout

This would describe that FooProject had to be 1.2.0 or greater, PickyThing could be anything from 1.6.0(inclusive) to 2.0.0(non inclusive), except for 1.9.6. 2.4.0 is OK too. SomethingWhoseVersionIDontCareAbout can be any version.

In general I wouldn't expect most packages to need this much specificity, and the currently common

julia 0.3-

would become

julia >=0.3

(though this wouldn't catch 0.3-rc1 if we're following the same parsing rules as python)

[shashi]

I think for me the reason for confusion (cc #7757) was that the documentation doesn't make it very clear. Quoting from http://julia.readthedocs.org/en/latest/manual/packages/#requirements

For example, the line:
Distributions 0.1
is satisfied by any version of Distributions greater than or equal to 0.1.0.

I thought that 0.3-rc1 is >= 0.3.0 although upon reflection I realised I was wrong.

The only reference to Package 0.3- syntax is in the docs is:

If you want to indicate that any 0.1.x version will do, you will want to write:
Distributions 0.1 0.2-
The 0.2- “pseudo-version” is less than all real version numbers that start with 0.2.

It takes quite some effort to infer from this what Distributions 0.2- alone would do.

Improving the docs can be a first step here, although I'd have liked explicit intervals like (0.1 0.2] etc.

[StefanKarpinski]

It takes quite some effort to infer from this what Distributions 0.2- alone would do.

I guess this may not be entirely obvious, after all. Please feel free to add some verbiage to clarify it.

[jakebolewski]

@tkelman I think you may want to tackle this one for your own sanity

[tkelman]

The current format is beyond fixing. Explaining it more won't suddenly fix the broken intuition people have about it. Should eventually be replaced with a more verbose specification, a la #11955

[jakebolewski]

I agree, closing this issue in favor of #11955.