Documentation: Describe how to configure dynamic package versioning using scm/git

[vlcinsky]

This issue is proposing an update of pdm documentation with regards to declaring package version.

Current status (as of pdm version 2.7):

pdm allows to specify in pyproject.toml a package version in multiple ways.

Static

[project]
version = "1.0.0"

The version is explicitly stated in the pyproject.toml.

Dynamic (from a file):

[project]
...
dynamic = ["version"]

[tool.pdm]
version = { source = "file", path = "mypackage/__version__.py" }

The version is read from a file (here mypackage/__version__.py) which is typically managed by some external tool such as bumpversion.

Dynamic (from scm/git)

[project]
...
dynamic = ["version",]
...
[tool.pdm.version]
source = "scm"

The version is derived from the latest tag in (git) source control. If current commit is tagged, the version is read from the tag as is, if the tag is present is some commit behind, version string is derived from given tag and current commit hash.

Documentation describes only the first two options

The problem is, that the "Dynamic (from scm/git)" option is not described in the documentation and it is not easy to find it.

Proposed solution

Update the PEP 621 Metadata/Package version as follows:

• Keep the "Static" tab
• Rename the "Dynamic" tab to "Dynamic (from a file)", remove the link "dynamic versioning" as it does not lead to useful instructions.
• Add new tab named "Dynamic (from scm/git)" and add very short description as shown above.

Alternative solution

Alternatively we may update "Build configuration/dynamic versioning" section which seems to be currently intended but is actually missing.

Points to review

I have tested the dynamic versioning with scm/git for pdm.backend

[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"

It is very likely, that each backend may offer a bit different options for assigning version. In such a case, it would be better to use dedicated section for each backend and in that place describe (for pdm-backend) or refer to (for other backends) how is versioning and possibly other aspects of package build configured and managed.

[pawamoy]

Thanks, that would be a nice enhancement to the docs. Would you like to contribute a PR with the tabs you suggest?

[frostming]

I agree to apply the alternative solution. The "dynamic versioning" in PEP 621 metadata page is what I forgot to move out when we remove the backend-specific logics from PDM. Now it doesn't make sense to keep it there, since as you said, the config options may vary in different backends. We have this for pdm-backend.

Welcome to submit a PR to update the docs.

[vlcinsky]

@frostming I will take care of PR.

The concept for "versioning" PR are

• in pdm documentation
  • show short examples (similar to what I have proposed above) without trying to be complete
  • explain, that
  • static version shall work for all backends
  • dynamic version might differ backend by beckend
  • provide relevant links to specific backend documentation, where possible.

off topic: distinguish pdm specific stuff and other stuff in pyproject.toml

Personally I feel, that it is worth (generally for pdm) to clarify, that:

• pyproject.toml as used for pdm has different sections:
  • common project metadata
  • sections specific to pdm unique functionality (venv, ...)
  • sections specific to configured build backend
  • sections specific to other tools and that the pdm documentation serves as source of truth only for the second section type, for others it might provide some examples but full specification must be found elsewhere (PEPs for metadata, specific backend docs, specific tool docs).

I will not attempt to put it into versioning section (in fact my PR will focus only on the versioning issue).