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 https://github.com/pdm-project/pdm-backend/blob/940d129ddda0e604b00831907069078bb8357c77/src/pdm/backend/hooks/version/init.py#L88-L94 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 https://github.com/pdm-project/pdm-backend/blob/4f20cfd51928b9e4d8b1a941630865755b569b19/src/pdm/backend/hooks/version/scm.py#L312-L327