document the backward-incompatible PEP 440 change to requirement semantics

Originally reported by: dairahopwood (Bitbucket: dairahopwood, GitHub: Unknown)

The PEP 440-compliant requirement checking is not backward-compatible with setuptools prior to version 8, or pip prior to version 6. An example of a requirement whose meaning has changed is:

foo == X, foo >= Y

In the old semantics, this would allow either foo == X or foo >= Y. In the new semantics, it fails to match any version of foo unless X == Y.

This causes problems for applications that have non-trivial version requirements and need to work with both old and new setuptools (for example, see https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2354 ). While the PEP 440 semantics is clearly simpler and more understandable, there needs to be documentation of the incompatibility, and of how an application can restrict itself to requirements that have the same meaning under the old and new semantics.

I believe requirements of the following form have the same meaning:

[{>|>=} X], [!= Y_i, ...], [{<|<=} Z] where X < Y_i < Z for all Y_i

(There may be any number of Y_i including zero; the lower and upper bound constraints are also optional. In the above, {|} and [] and ... are metacharacters, not literal parts of the requirement string.)

Of course any requirement with only a single constraint (foo op X) also has the same meaning, provided that constraint is supported in the old setuptools/pip version.

Bitbucket: https://bitbucket.org/pypa/setuptools/issue/310

pypa / setuptools

document the backward-incompatible PEP 440 change to requirement semantics #310