feat(sources): generate .git_archival.txt for setuptools-scm builds

When building from source archives without a .git directory,
setuptools-scm cannot determine the package version. A synthesized
.git_archival.txt with the describe-name field lets setuptools-scm
resolve the version without requiring an environment variable override.

Only replaces existing .git_archival.txt files — does not create new
ones. Packages that do not ship an archival file handle versioning
through other means (e.g. fallback_version) and injecting a synthetic
file can break packages with a custom tag_regex.

Simplifications based on setuptools-scm internals:
- Only describe-name is required (node/node-date are ignored)
- Uses %(describe as the unprocessed marker (matching setuptools-scm)

Co-Authored-By: Claude <claude@anthropic.com>
Closes: #961

Author: LalatenduMohanty

src/fromager/sources.py

@@ -690,6 +690,14 @@ def default_build_sdist(
         sdist_root_dir=sdist_root_dir,
         build_dir=build_dir,
     )
+    has_git_metadata = build_dir.joinpath(".git").exists() or (
+        sdist_root_dir != build_dir and sdist_root_dir.joinpath(".git").exists()
+    )
+    if not has_git_metadata:
+        ensure_git_archival(
+            version=version,
+            target_dir=build_dir,
+        )
     # The format argument is specified based on
     # https://peps.python.org/pep-0517/#build-sdist.
     with tarfile.open(sdist_filename, "x:gz", format=tarfile.PAX_FORMAT) as sdist:
@@ -771,6 +779,79 @@ def ensure_pkg_info(
     return had_pkg_info
 
 
+# Template .git_archival.txt files contain "$Format:…$" placeholders that
+# `git archive` expands into real values.  setuptools-scm detects the string
+# "%(describe" in the content to identify unprocessed archival files
+# (see setuptools_scm.git.archival_to_version).
+_UNPROCESSED_ARCHIVAL_MARKER = "%(describe"
+
+# Fields that must be present for setuptools-scm to resolve a version.
+# setuptools-scm only uses ``describe-name``; other fields like ``node``
+# and ``node-date`` are ignored and need not be synthesized.
+_REQUIRED_ARCHIVAL_FIELDS = {"describe-name"}
+
+_GIT_ARCHIVAL_CONTENT = """\
+describe-name: {version}
+"""
+
+
+def ensure_git_archival(
+    *,
+    version: Version,
+    target_dir: pathlib.Path,
+) -> bool | None:
+    """Ensure that sdist has a usable ``.git_archival.txt`` for setuptools-scm.
+
+    When building from source archives without a ``.git`` directory,
+    setuptools-scm cannot determine the package version.  A synthesized
+    ``.git_archival.txt`` provides the version through the ``describe-name``
+    field so that setuptools-scm resolves it without requiring an environment
+    variable override.
+
+    See https://setuptools-scm.readthedocs.io/en/latest/usage/#git-archives
+
+    Returns True if a valid archival file was already present (no changes
+    made), False if a new file was written (the existing file contained
+    unprocessed placeholders), or None if no archival file existed (no
+    changes made).
+
+    Only replaces existing files — does not create new ones.  Packages
+    that do not ship a ``.git_archival.txt`` in their sdist handle
+    versioning through other means (e.g. ``fallback_version``,
+    ``_version_module.py``) and injecting a synthetic file can break
+    packages with a custom ``tag_regex``.
+    """
+    archival_file = target_dir.joinpath(".git_archival.txt")
+
+    if not archival_file.is_file():
+        logger.debug("no .git_archival.txt in %s, skipping", target_dir)
+        return None
+
+    content = archival_file.read_text()
+    parsed_fields: dict[str, str] = {}
+    for line in content.splitlines():
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        parsed_fields[key.strip()] = value.strip()
+    if (
+        _UNPROCESSED_ARCHIVAL_MARKER not in content
+        and _REQUIRED_ARCHIVAL_FIELDS <= set(parsed_fields)
+        and all(parsed_fields.get(f) for f in _REQUIRED_ARCHIVAL_FIELDS)
+    ):
+        logger.debug("valid .git_archival.txt already present in %s", target_dir)
+        return True
+    logger.warning("replacing invalid .git_archival.txt in %s", target_dir)
+
+    archival_file.write_text(
+        _GIT_ARCHIVAL_CONTENT.format(
+            version=str(version),
+        )
+    )
+    logger.info("created .git_archival.txt for version %s in %s", version, target_dir)
+    return False
+
+
 def validate_sdist_filename(
     req: Requirement,
     version: Version,

tests/test_sources.py

@@ -312,3 +312,82 @@ def test_scan_compiled_extensions(
         assert matches == [pathlib.Path(filename)]
     else:
         assert matches == []
+
+
+class TestEnsureGitArchival:
+    """Tests for ensure_git_archival()."""
+
+    def test_skips_when_no_file_exists(self, tmp_path: pathlib.Path) -> None:
+        """Verify no file is created when none existed before."""
+        version = Version("1.2.3")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+        archival = tmp_path / ".git_archival.txt"
+
+        assert result is None
+        assert not archival.is_file()
+
+    def test_replaces_unprocessed_file(self, tmp_path: pathlib.Path) -> None:
+        """Verify unprocessed template file is replaced."""
+        archival = tmp_path / ".git_archival.txt"
+        archival.write_text(
+            "node: $Format:%H$\n"
+            "node-date: $Format:%cI$\n"
+            "describe-name: $Format:%(describe:tags=true)$\n"
+        )
+        version = Version("4.5.6")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is False
+        content = archival.read_text()
+        assert "describe-name: 4.5.6\n" in content
+        assert "%(describe" not in content
+
+    def test_preserves_valid_file(self, tmp_path: pathlib.Path) -> None:
+        """Verify a valid archival file is left untouched."""
+        archival = tmp_path / ".git_archival.txt"
+        original = (
+            "node: abc123\n"
+            "node-date: 2025-01-01T00:00:00+00:00\n"
+            "describe-name: v1.0.0-0-gabc123\n"
+        )
+        archival.write_text(original)
+        version = Version("9.9.9")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is True
+        assert archival.read_text() == original
+
+    def test_preserves_valid_file_describe_name_only(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Verify a file with only describe-name is valid."""
+        archival = tmp_path / ".git_archival.txt"
+        original = "describe-name: 2.0.0\n"
+        archival.write_text(original)
+        version = Version("9.9.9")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is True
+        assert archival.read_text() == original
+
+    def test_replaces_truncated_file(self, tmp_path: pathlib.Path) -> None:
+        """Verify a truncated file missing required fields is replaced."""
+        archival = tmp_path / ".git_archival.txt"
+        archival.write_text("node-date: 2025-01-01T00:00:00+00:00\n")
+        version = Version("3.0.0")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is False
+        content = archival.read_text()
+        assert "describe-name: 3.0.0\n" in content
+
+    def test_replaces_file_with_empty_values(self, tmp_path: pathlib.Path) -> None:
+        """Verify a file with required fields but empty values is replaced."""
+        archival = tmp_path / ".git_archival.txt"
+        archival.write_text("describe-name:\n")
+        version = Version("5.0.0")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is False
+        content = archival.read_text()
+        assert "describe-name: 5.0.0\n" in content