feat(packaging): version git archives of arbitrary commits

GitHub serves a source tarball for every commit, not only for tags, but
so far only a tag's tarball could be built: without a .git directory
setuptools-scm had nothing to read the version from.

A .git_archival.txt expanded by ``git archive`` via ``export-subst``
gives it one. The stable template is deliberate -- recording ``ref-names``
as well would tie an archive's content, and so its checksum, to whichever
branches happen to point at the commit, so moving a branch afterwards
would silently change the download.

While here, move off the deprecated ``write_to`` and state the
``write_to_source`` behaviour that setuptools-scm is about to flip
rather than inherit the change silently.

Closes #11680

Co-Authored-By: Claude Opus 5 (1M context) via Claude Code <noreply@anthropic.com>

Author: RonnyPfannschmidt

.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

changelog/11680.packaging.rst

@@ -0,0 +1,14 @@
+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.
+
+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]
@@ -100,7 +100,10 @@ dev = [
 ]
 
 [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