[PR #15023/de30d841 backport][9.1.x] feat(packaging): version git archives of arbitrary commits

.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

.gitattributes

@@ -1 +1,8 @@
 *.bat  text eol=crlf
+
+# setuptools-scm reads the version out of this file when the source tree is a
+# ``git archive`` (a GitHub source download) rather than a checkout.
+# Deliberately the "stable" template: it records describe output but not
+# ``ref-names``, so the archive of a given commit does not change its content
+# -- and therefore its checksum -- when a branch that points at it later moves.
+.git_archival.txt  export-subst

MANIFEST.in

@@ -0,0 +1,5 @@
+# Only meaningful inside a ``git archive``, where ``export-subst`` has filled it
+# in; an sdist carries its version in the metadata instead. Shipping the
+# unexpanded template would leave setuptools-scm a stray ``$Format:...$`` to
+# consider on every build from an unpacked sdist.
+exclude .git_archival.txt

changelog/11680.packaging.rst

@@ -0,0 +1,17 @@
+Source archives of arbitrary commits -- the tarballs GitHub serves under
+``/archive/``, not just the ones for tags -- can now be built into an sdist or a
+wheel with a correct version. A ``.git_archival.txt`` file, expanded by ``git
+archive`` via ``export-subst``, carries the describe output that
+``setuptools-scm`` would otherwise have to ask ``git`` for.
+
+The archival file deliberately omits ``ref-names``. Recording it would make the
+content of an archive -- and therefore its checksum -- change whenever a branch
+that points at the archived commit is moved afterwards, which is how the
+equivalent tarballs of tagged releases became unstable for other projects.
+Describe output alone depends only on the commit and on the tags reachable from
+it.
+
+The archival file is not shipped in the sdist -- an sdist carries its version
+in its metadata, and the template is only ever expanded by ``git archive``.
+
+Building pytest from a git checkout now requires ``setuptools-scm >= 10.1``.

pyproject.toml

@@ -2,7 +2,7 @@
 build-backend = "setuptools.build_meta"
 requires = [
     "setuptools>=77",
-    "setuptools-scm[toml]>=6.2.3",
+    "setuptools-scm[toml]>=10.1",
 ]
 
 [project]
@@ -82,7 +82,10 @@ scripts.pytest = "_pytest.config:_console_main"
 ]
 
 [tool.setuptools_scm]
-write_to = "src/_pytest/_version.py"
+version_file = "src/_pytest/_version.py"
+# keep writing _version.py into the checkout: running pytest from a source
+# tree relies on it. The setuptools-scm default flips in a future major.
+write_to_source = true
 
 [tool.black]
 # See https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#t-target-version