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

No documentation file or test is identified in the issue. Start by reviewing the PEP 440 example and the stated old versus new setuptools and pip semantics; document the incompatibility and which requirement forms preserve the same meaning across versions.