PR#1154: Python: Add a warning about git tarballs and setuptools_scm - packaging-committee

packaging-committee

#1154 Python: Add a warning about git tarballs and setuptools_scm

Merged 2 years ago by churchyard. Opened 2 years ago by churchyard.

churchyard/packaging-committee setuptools_scm into master

Python: Add a warning about git tarballs and setuptools_scm

Miro Hrončok • 2 years ago

40f821a

guidelines/modules/ROOT/pages/Python.adoc

file modified

+14

		`@@ -1136,6 +1136,20 @@`
		you can use the <<pypi_source,the `+%pypi_source+` macro>>
		`to generate the proper URL.`

		+ WARNING: Some Python packages use metadata from `git`
		`+ (or a similar version control system)`
		`+ to construct their version string,`
		`+ for example via https://pypi.org/project/setuptools-scm/[setuptools_scm].`
		`+ When publishing a package to PyPI,`
		`+ this version metadata is usually stored and included in a file,`
		`+ so the version control history is no longer needed to construct it.`
		`+ However, when using tarballs from a git forge directly,`
		`+ this version information is missing`
		`+ and must be manually provided by the packager.`
		+ For example, the `SETUPTOOLS_SCM_PRETEND_VERSION` environment variable can be set
		+ to the desired value in the `+%generate_buildrequires+` and `+%build+` scripts in the spec file
		+ for packages that use `setuptools_scm` for this purpose.
		`+`
		`== Example spec file[[_example_python_spec_file]]`

		`The following is a viable spec file`

churchyard commented 2 years ago

I'd appreciate it if somebody could review the language and understandability of this.

Other than that, I don't think this requires a vote, it is not a new rule, just a warning about the status quo.

decathorpe commented 2 years ago

LGTM, though I have suggestions that might improve clarity of the text a bit.
Feel free to take the parts you like (if any) and ignore the ones you don't. :)

WARNING: Some Python packages use metadata from git
(or a similar version control system)
to construct their version string,
for example via https://pypi.org/project/setuptools-scm/[setuptools_scm].
When publishing a package to PyPI,
this version metadata is usually stored and included in a file,
so the version control system (VCS?) history is no longer needed
to construct the correct version string.
However, when using tarballs from a git forge directly,
this version information is missing
and must be manually provided by the packager.
For example, the SETUPTOOLS_SCM_PRETEND_VERSION environment variable can be set
to the desired value in the +%generate_buildrequires+ and +%build+ scripts in the spec file
for packages that use setuptools_scm for this purpose.