Improve documentation on hooks flow - specifically when and how the dynamic version is written to a file

[ZeeD]

Hi.
I'm trying to wrap my head around pdm, pdm-backend and, more generally, how the hooks works and how are they actually connected.

At the moment my goal is to understand how I can leverage pdm to create a python file with the scm version. I have looked at Writing dynamic version to file and at Lifecycle and Hooks but I have some questions:

1. let's say that I set up correctly dynamic = ["version"], source = "scm", and write_to = "foo/_version.py" in the appropriate pyproject.toml tables. What cli command(s) will trigger the creation of the file? is there an explicit way?
2. During the initializazion, I have set distribution = false (because I'm writing a application that is meant to be used internally and deployed via dockerfile where I just copy the sources) - is this choice relevant?
3. Can you confirm I do need to set pdm-backend as build-backend? or is it a pdm feature that may work with setuptools or any other backend?
4. What happens if in my git repository there is no tag (at all, or that matches the tag_regex)? I haven't see any log/warning/error during my tests
5. What is the rule to "choose" an appropriate tag, assuming there are more than one that matches?
6. On

   pdm-backend/src/pdm/backend/hooks/version/__init__.py

   Lines 88 to 94 in 940d129

   	def resolve_version_from_scm(
   	self,
   	context: Context,
   	write_to: str | None = None,
   	write_template: str = "{}\n",
   	tag_regex: str | None = None,
   	) -> str:

   I think I've found the relevant code, and it is in a hooks.version module, but I haven't found any reference to it in the docs. Is that related to the pdm hooks?

I'm having these doubts because I have a project that I've recently migrated to pdm, and I'm new to it, and I want to be sure to understand how it works

[frostming]

The dynamic version, and the whole backend, only take effect when distribution = true.

And the hook will be triggered whenever a build action is performed, that includes pdm build, pdm sync, pdm install(if installing self is required, because installing from the source will build) etc.

You can even trigger the build hook with other build frontends, such as build, in this case distribution won't be honored as it is a PDM-only config.

[IronFarm]

Yeah it would be great to see an explanation of how the tag is generated. I could pick out the commit hash and the current date but there seemed to be large differences depending on whether my working directory was dirty and I couldn't figure out whether the branch name had an impact. Thanks!

[frostming]

@IronFarm

pdm-backend/src/pdm/backend/hooks/version/scm.py

Lines 312 to 327 in 4f20cfd

	def format_version(version: SCMVersion) -> str:
	if version.distance is None:
	main_version = str(version.version)
	else:
	guessed = guess_next_version(version.version)
	main_version = f"{guessed}.dev{version.distance}"
	if version.distance is None or version.node is None:
	clean_format = ""
	dirty_format = "+d{time:%Y%m%d}"
	else:
	clean_format = "+{node}"
	dirty_format = "+{node}.d{time:%Y%m%d}"
	fmt = dirty_format if version.dirty else clean_format
	local_version = fmt.format(node=version.node, time=datetime.utcnow())
	return main_version + local_version