Better explanation of version pinning

[pocc]

For this PR, @henryiii has talked about how you can version pin with this repo. I'm not seeing anything about it in the README. Can you be more explicit in the README with a section on "Using a specific version", with an example?

[henryiii]

pip install clang-format==12.0.1

For example?

[pocc]

Yeah something like that. The way you are pinning repo versions to PyPI versions to clang-format versions is clever and non-obvious. An example or note could be on the fourth line.

[henryiii]

There was a discussion explaining the version scheme but it was in an issue/PR of a deleted repo.

We should also be aware that this package might be popular with people not very familiar with Python (esp. packaging).

[nightlark]

By repo versions, are you referring to the git tag/GitHub releases? Those should always map directly to the PyPI versions, and at least at the moment all of those map to the matching clang-format version.

It would probably be good to explain that the first 3 version number components (and optional pre-release segment) always match up with the corresponding clang-format release; a 4th version number component or post/dev release segment indicates a change solely related to the PyPI wheel and not the version of clang-format included with it.

[pocc]

Agreed that

repo1 version <=> PyPI version

is typical. But you're doing

repo1 version <=> PyPI version <=> repo2 version

and I've never seen that before.

It's not explicitly documented with an example, which is why I created this issue.

[dokempf]

I added a note about the matching versions to README. Hopefully this clarifies the situation a bit.