Clarify implicit version automation

[astrojuanlu]

Some thoughts from #8473, also related to #5319, #8015, and #8460.

In our Versioned Documentation docs we say:

• That tags should be "numbered in a way that is consistent with semantic versioning", but we don't say what happens otherwise. Having this "how we envision" section feels weird, we should be more descriptive and rephrase this advice somehow. Partially addressed in New Read the Docs tutorial, part II #8473:

 we will create a ``latest`` version.
 This will point at the default branch for your VCS control: ``master``, ``default``, or ``trunk``.
 
-We also create a ``stable`` version,
-if your project has any tagged releases.
-``stable`` will be automatically kept up to date to point at your highest version.
+If your project has any tags or branches with a name following `semantic versioning <https://semver.org/>`_,
+we also create a ``stable`` version, tracking your most recent release.
 If you want a custom ``stable`` version,
 create either a tag or branch in your project with that name.
 

• Next, that "we in fact are parsing your tag names against the rules given by PEP 440" ❓ Which forces users to understand what are the differences between PEP 440 and SemVer. This however reflects the truth more closely:

readthedocs.org/readthedocs/projects/version_handling.py

Lines 36 to 40 in b68a921

	try:
	normalized_version = unicodedata.normalize('NFKD', uni_version)
	ascii_version = normalized_version.encode('ascii', 'ignore')
	final_form = ascii_version.decode('ascii')
	return Version(final_form)

• And finally, we are not saying that, in fact, we also accept .x as a patch segment:

readthedocs.org/readthedocs/projects/version_handling.py

Lines 41 to 44 in b68a921

	except InvalidVersion:
	# Handle the special case of 1.x, 2.x or 1.0.x, 1.1.x
	if final_form and '.x' in final_form:
	return parse_version_failsafe(final_form.replace('.x', '.0'))

This issue concerns updating the documentation to reflect the current reality, although I support continuing the discussion in #5319 about making these Automation Rules that are present for all newly created projects, and that can be controlled.

[ericholscher]

I'd like to remove any additional magic that we can. In particular, removing the auto-activating of versions seems like something that Automation Rules are better for, and we should document that. We could also enable it by default in new projects if we thought it was useful enough, but I'm not sure it is.

I'd love to also get rid of the stable code, but I don't believe we've built them into Automation Rules yet.

[humitos]

I agree with @ericholscher here. The more magic we can remove, the better. In particular, if we can migrate that behavior to be explicitly configured by the user.

I'd love to also get rid of the stable code, but I don't believe we've built them into Automation Rules yet.

We have automation rules to detect SemVer (on branches/tags) but we haven't built yet the version aliases (#5318), which is the missing part required to have the same stable behavior via automation rules.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.