Clarify support for an optional v-prefix in branch and tag names

[laymonage]

Hey all, thanks for such a cool project ❤️

We at Wagtail use RTD for our docs, and we use v-prefixed names for our git tags. RTD seems to pick it up nicely, but I couldn't find any mention of the prefix in the docs. I wanted to make sure that this is the default RTD behaviour rather than something that we set up at some point and forgot about.

In https://docs.readthedocs.io/en/stable/versions.html it says that RTD follows SemVer and PEP 440 for its default versioning workflows. However, SemVer.org says the following:

Is “v1.2.3” a semantic version?
No, “v1.2.3” is not a semantic version. However, prefixing a semantic version with a “v” is a common way (in English) to indicate it is a version number. Abbreviating “version” as “v” is often seen with version control. Example: git tag v1.2.3 -m "Release version 1.2.3", in which case “v1.2.3” is a tag name and the semantic version is “1.2.3”.

I suppose that kind of implies RTD's behaviour. However, the first sentence of "No, “v1.2.3” is not a semantic version" and the reinforcement in the last part "the semantic version is “1.2.3”" combined with RTD's docs only saying "we follow semantic versioning" made me doubt whether the v prefix is supported by default or not.

It looks like this is something RTD has supported since the very beginning (at least since 556f676 when automation rules were added). Then the regex is changed in #6402 to use the one suggested by SemVer.org, with the addition of the v-prefix support. This was explicitly acknowledged in #6395 (comment), but never documented.

I thought I'd add this info to help others who might stumble upon the same confusion as I did 🙂

Related: #8476

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--11712.org.readthedocs.build/en/11712/

• Developer's documentation (dev): https://dev--11712.org.readthedocs.build/en/11712/

[stsewd]

Hi, thanks for the PR! For clarification:

• The parsing of versions listed on RTD is done purely using PEP 440 (or packaging to be more precise https://packaging.python.org/en/latest/specifications/version-specifiers/#preceding-v-character)
• The matching of versions for automation rules is done with the regex you found.

I guess this sentence would be the correct description for this page

readthedocs.org/docs/user/versions.rst

Line 133 in 3b947be

- **Tags** are semantic versioning compatible (according to `PEP 440`_) snapshots

And for automation rules to mention the v prefix at

readthedocs.org/docs/user/automation-rules.rst

Line 49 in 3b947be

- **SemVer versions**: All new versions that follow `semantic versioning <https://semver.org/>`__ will match the rule.

Maybe @ericholscher has some thoughts here, he's been refactoring our docs.

[laymonage]

Oh wow, thanks @stsewd! I wanted to mention whether it might've come from PEP 440 instead, but I did Ctrl+F for "prefix" and couldn't find anything – turns out it says "Preceding v character". That makes a lot of sense!

I've added a commit to also add the info in automation-rules.rst. I think the changes in versions.txt already look good, but I'm happy to make specific adjustments if needed.

Though now I wonder how compatible PEP 440 is with SemVer, and what RTD's documented behaviour should be.

The PEP makes clear of this in https://packaging.python.org/en/latest/specifications/version-specifiers/#semantic-versioning, which seems to say it's mostly compatible apart from the hyphen or plus signs for the prerelease details. On the other hand, the regex in SemVer (which RTD follows), seems to allow this.

So RTD tries to cater to both:

• Allow the v prefix from PEP 440, even if SemVer says it's not part of SemVer
• Allow the hyphen/plus from SemVer, even if PEP 440 says it's incompatible

If we're being pedantic, it looks like we can't say RTD follows either one – and for a good reason! Anyway, I don't want to argue the exact wording, I just want the v prefix support to be documented. Let me know if you'd like further changes in the PR 😄

[ericholscher]

Looks good to me. I've been wanting to clarify this support a bit more, so this is a good first step 👍