Missing documentation for calver

[kasium]

I found out that this project supports calver (e.g. calver-by-date) but these options are not documented

[huxuan]

Hi buddies, any quick start for how to use it?

[RonnyPfannschmidt]

Starting point is to use one of the Calver named Version shemes as per the readme

The documentation rework in #880 will eventually provide better examples

[huxuan]

I tried to change the version_scheme to calver-by-date, but seems it will still use the git tag when the repo is clean. So maybe the problem is what is the best practice to use calver. It might also including how to manage git tags or even the migration from normal semver to calver.

[RonnyPfannschmidt]

Current behavior is that on exact tags The Tag wins

[jziolkowski]

I'm either blind or the docs are still missing for this?

Basically I wonder if/how can I achieve this:

vYYYY.MM.<sequence>[.devX]

[RonnyPfannschmidt]

@jziolkowski this would be something called "calver-by-month" its currently not implemented

setuptools-scm/src/setuptools_scm/version.py

Lines 323 to 413 in d665621

	_DATE_REGEX = re.compile(
	r"""
	^(?P<date>
	(?P<prefix>[vV]?)
	(?P<year>\d{2}|\d{4})(?:\.\d{1,2}){2})
	(?:\.(?P<patch>\d*))?$
	""",
	re.VERBOSE,
	)
	def date_ver_match(ver: str) -> Match[str] | None:
	return _DATE_REGEX.match(ver)
	def guess_next_date_ver(
	version: ScmVersion,
	node_date: date | None = None,
	date_fmt: str | None = None,
	version_cls: type | None = None,
	) -> str:
	"""
	same-day -> patch +1
	other-day -> today
	distance is always added as .devX
	"""
	match = date_ver_match(str(version.tag))
	if match is None:
	warnings.warn(
	f"{version} does not correspond to a valid versioning date, "
	"assuming legacy version"
	)
	if date_fmt is None:
	date_fmt = "%y.%m.%d"
	else:
	# deduct date format if not provided
	if date_fmt is None:
	date_fmt = "%Y.%m.%d" if len(match.group("year")) == 4 else "%y.%m.%d"
	if prefix := match.group("prefix"):
	if not date_fmt.startswith(prefix):
	date_fmt = prefix + date_fmt
	today = version.time.date()
	head_date = node_date or today
	# compute patch
	if match is None:
	tag_date = today
	else:
	tag_date = (
	datetime.strptime(match.group("date"), date_fmt)
	.replace(tzinfo=timezone.utc)
	.date()
	)
	if tag_date == head_date:
	patch = "0" if match is None else (match.group("patch") or "0")
	patch = int(patch) + 1
	else:
	if tag_date > head_date and match is not None:
	# warn on future times
	warnings.warn(
	f"your previous tag ({tag_date})"
	f" is ahead your node date ({head_date})"
	)
	patch = 0
	next_version = "{node_date:{date_fmt}}.{patch}".format(
	node_date=head_date, date_fmt=date_fmt, patch=patch
	)
	# rely on the Version object to ensure consistency (e.g. remove leading 0s)
	if version_cls is None:
	version_cls = PkgVersion
	next_version = str(version_cls(next_version))
	return next_version
	def calver_by_date(version: ScmVersion) -> str:
	if version.exact and not version.dirty:
	return version.format_with("{tag}")
	# TODO: move the release-X check to a new scheme
	if version.branch is not None and version.branch.startswith("release-"):
	branch_ver = _parse_version_tag(version.branch.split("-")[-1], version.config)
	if branch_ver is not None:
	ver = branch_ver["version"]
	match = date_ver_match(ver)
	if match:
	return ver
	return version.format_next_version(
	guess_next_date_ver,
	node_date=version.node_date,
	version_cls=version.config.version_cls,
	)

implements it for `vYYYY.MM.DD.{sequence}[.devX]

im open to adoption it to support calver-by-month but i cant implement it myself soon