PEP 440: Make examples clearer

[konstin]

The PEP 440 version matching examples are confusing to read and the 1.1a1 in == 1.1.* is dependent on whether the user requested pre-releases or not, which I've clarified (pypa/packaging#617).

---

I'm confused because this repository tells me to sign the CLA before I submit a pull request, but the link CLA signing guide then tells me to first open a pull requests and wait for the CLA bot reply

[ghost]

All commit authors signed the Contributor License Agreement.

[CAM-Gerlach]

I'm not totally sure how the re-ordered text in the comments resolves the confusion mentioned in that thread, but I'll defer that to the appropriate experts and folks you interacted with on the thread, whom I've tagged here.

I'm confused because this repository tells me to sign the CLA before I submit a pull request, but the link CLA signing guide then tells me to first open a pull requests and wait for the CLA bot reply

Sorry, that's out of date—we recently (ish) got a new CLA bot, and there were a couple spots where the text didn't entirely reflect those changes. I've opened #2900 to update those, thanks.

[pfmoore]

The consensus in pypa/packaging#617 seemed to be that the spec should be moved to packaging.python.org, and the updates added there. There's also a similar discussion on Discourse where essentially the same conclusion seemed to have been reached.

I think we need to get consensus on the correct course of action before proceeding here. At the very least, this PR should be mentioned on the Discourse discussion.

[konstin]

I agree with moving PEP 440 to the specs page to packaging.python.org, but in the meantime, i'd advocate for at least updating the 1.1a1 in == 1.1.* example because otherwise this PEP reads rather contradictory (says it matches there, says only matches under special circumstances in the section about prereleases)

[CAM-Gerlach]

The part I still don't really follow, and one of the reasons why folks might be hesitant to accept this, is why it is necessary to change dozens of comments when it is (unless I misunderstand, which I might) only a ≈couple that are actually causing the confusion here. Even this being a packaging standard aside, the less minimal the change the harder sell it is to accept it, and its certainly a lot more difficult to justify rewriting dozens of comments vs. adding/changing a few words in a couple of them to clarify one very specific point.

[konstin]

I found the phrasing very confusing when trying to figure out the examples; I've now cut it down to just one line change

[pradyunsg]

My 2 cents: Let's land this -- it's a small-enough change now and we can come around to moving PEP 440 over to https://packaging.python.org/en/latest/specifications/version-specifiers/ when someone finds the bandwidth to do so.

[AA-Turner]

I'm inclined to merge this; there's no objections to the one-line change and approval from @pradyunsg, one of the packaging maintainers.

A