Document semantics and syntax of version specification in VCS URL.

[piotr-dobrogost]

Currently at VCS Support one reads (emphasis mine):

The "project name" component of the url suffix "egg=<project name>-<version>" is used by pip in its dependency logic to identify the project prior to pip downloading and analyzing the metadata. The optional "version" component of the egg name is not functionally important. It merely provides a human-readable clue as to what version is in use.

However looking at examples at jazzband/pip-tools#372 (comment) specifying version number influences pip's behavior of install command noticeably. Please notice that these examples use egg=<project name>==<version> syntax which is not mentioned at all in the VCS Support section of documentation.

Documentation should give answers to how does egg=<project name>-<version> relate to egg=<project name>==<version> and what is the semantics of specifying version in either form.

[chrahunt]

IMO we should deprecate this syntax (with some long deprecation period) and refer to the PEP 440 direct URL syntax instead.

[pradyunsg]

#egg=<something> -- yep. Sounds like a good idea to me. :)

[xavfernandez]

Regarding the initial documentation issue, it should have been closed via #4174 & #5888 .
Regarding the #egg syntax deprecation, #1289 should be the right issue so I'm closing this one.