fix(build): derive versions without VERSION (#705)

Author: gaborbernat

Cargo.toml

@@ -1,7 +1,6 @@
 [package]
 name = "pipdeptree"
-# Placeholder: the authoritative release version lives in the VERSION file and is wired into the
-# binary through build.rs (PIPDEPTREE_VERSION); this crate is never published to crates.io.
+# The build resolves the release version; this crate is never published to crates.io.
 version = "0.0.0"
 description = "Display Python package dependency trees"
 repository = "https://github.com/tox-dev/pipdeptree"

VERSION

@@ -1,16 +1,74 @@
+use std::env;
+use std::fs;
+use std::path::Path;
+use std::process::Command;
+
 fn main() {
-    // Meson passes the version it derived from the git tags; a bare cargo build falls back to the VERSION file.
     println!("cargo:rerun-if-env-changed=PIPDEPTREE_VERSION");
-    let version = std::env::var("PIPDEPTREE_VERSION").unwrap_or_else(|_| {
-        let version_file = format!("{}/VERSION", env!("CARGO_MANIFEST_DIR"));
-        println!("cargo:rerun-if-changed={version_file}");
-        std::fs::read_to_string(&version_file).expect("VERSION must be readable")
-    });
+    println!("cargo:rerun-if-changed=PKG-INFO");
+    println!("cargo:rerun-if-changed=.git");
+    let version = env::var("PIPDEPTREE_VERSION")
+        .ok()
+        .or_else(from_git)
+        .or_else(from_metadata)
+        .unwrap_or_else(|| "0.0.0".to_string());
     println!("cargo:rustc-env=PIPDEPTREE_VERSION={}", version.trim());
-    if std::env::var_os("CARGO_FEATURE_EXTENSION_MODULE").is_some()
-        && std::env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("macos")
+    if env::var_os("CARGO_FEATURE_EXTENSION_MODULE").is_some()
+        && env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("macos")
     {
         println!("cargo:rustc-link-arg=-undefined");
         println!("cargo:rustc-link-arg=dynamic_lookup");
     }
 }
+
+fn from_git() -> Option<String> {
+    if !Path::new(".git").exists() {
+        return None;
+    }
+    if let Some(paths) = git(&[
+        "rev-parse",
+        "--git-path",
+        "HEAD",
+        "--git-path",
+        "refs",
+        "--git-path",
+        "packed-refs",
+    ]) {
+        for path in paths.lines() {
+            println!("cargo:rerun-if-changed={path}");
+        }
+    }
+    let described = git(&["describe", "--tags", "--long", "--match", "[0-9]*"])?;
+    let (release, commit) = described
+        .rsplit_once('-')
+        .expect("git describe includes a commit");
+    let (tag, distance) = release
+        .rsplit_once('-')
+        .expect("git describe includes a distance");
+    Some(if distance == "0" {
+        tag.to_string()
+    } else {
+        format!("{tag}.dev{distance}+{commit}")
+    })
+}
+
+fn git(args: &[&str]) -> Option<String> {
+    let output = Command::new("git").args(args).output().ok()?;
+    output
+        .status
+        .success()
+        .then(|| String::from_utf8_lossy(&output.stdout).trim().to_string())
+}
+
+fn from_metadata() -> Option<String> {
+    fs::read_to_string("PKG-INFO")
+        .ok()?
+        .lines()
+        .take_while(|line| !line.is_empty())
+        .find_map(|line| {
+            line.strip_prefix("Version:")
+                .map(str::trim)
+                .filter(|version| !version.is_empty())
+                .map(ToOwned::to_owned)
+        })
+}

build.rs

@@ -0,0 +1,2 @@
+Remove the tracked ``VERSION`` file. Resolve build versions from ``PIPDEPTREE_VERSION``, Git tags, or sdist metadata,
+falling back to ``0.0.0`` when none is available.

docs/changelog/699.packaging.rst

@@ -106,9 +106,23 @@ Sphinx writes ``.tox/docs_out/html/index.html``.
 Releasing
 ---------
 
-``tools/version.py`` derives the version from the release tags, so the tag a release carries is the version its wheels
-and sdist report. Nothing in the tree names the version, and the ``VERSION`` file exists for builds with no tags to
-read, such as one from an unpacked sdist.
+Builds use the following version sources, in order:
+
+1. ``PIPDEPTREE_VERSION``, if set.
+2. A reachable Git release tag, with a development suffix for commits after the tag.
+3. The ``Version`` header in the source distribution's ``PKG-INFO`` metadata.
+4. ``0.0.0`` if none of those sources provides a version.
+
+Meson-Python includes ``PKG-INFO`` in sdists, so rebuilding a wheel from an sdist needs no Git history. Bare Cargo
+builds use the same precedence. Fetch release tags in shallow clones to obtain the release-derived version.
+
+Package maintainers building without Git history or distribution metadata can supply their own version:
+
+.. code-block:: bash
+
+    PIPDEPTREE_VERSION=4.2.3 uv build
+
+The override takes precedence over tags and metadata; the build uses the value the maintainer supplies.
 
 Every user-visible change brings a news fragment under ``docs/changelog``, named ``<issue>.<type>.rst`` with one of the
 types ``breaking``, ``feature``, ``bugfix``, ``doc`` or ``packaging``. The unreleased fragments render as a draft

docs/development.rst

@@ -8,9 +8,6 @@ project(
   default_options: ['python.allow_limited_api=false'],
 )
 
-# Freeze the git-derived version into the sdist so a wheel built from it needs no git history.
-meson.add_dist_script('tools/version.py', '--write')
-
 py = import('python').find_installation(pure: false)
 py.install_sources(
   files(

meson.build

@@ -16,8 +16,7 @@ use tempfile::{TempDir, tempdir};
 static PYTHON_LOCK: Mutex<()> = Mutex::new(());
 static RESOLVER: Once = Once::new();
 
-pub const VERSION: &str =
-    include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/VERSION")).trim_ascii_end();
+pub const VERSION: &str = env!("PIPDEPTREE_VERSION");
 
 mockall::mock! {
     pub Processes {}

rust/tests/public_api/common.rs

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import runpy
+import subprocess  # ruff:ignore[suspicious-subprocess-import]  # Integration tests need real Git and Cargo processes.
+from pathlib import Path
+from shutil import which
+from typing import TYPE_CHECKING, Final
+from unittest.mock import create_autospec
+
+import pytest
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@pytest.mark.usefixtures("repository", "package_metadata")
+@pytest.mark.parametrize(
+    ("release", "override", "expected"),
+    [
+        pytest.param("4.2.3", None, "4.2.3", id="release"),
+        pytest.param("4.3.0rc1", None, "4.3.0rc1", id="prerelease"),
+        pytest.param("4.2.3", "5.0.0rc1", "5.0.0rc1", id="override"),
+    ],
+)
+def test_build_version_tag(
+    build_version: Callable[[], str],
+    git: Callable[..., str],
+    monkeypatch: pytest.MonkeyPatch,
+    release: str,
+    override: str | None,
+    expected: str,
+) -> None:
+    git("tag", release)
+    if override is not None:
+        monkeypatch.setenv("PIPDEPTREE_VERSION", override)
+
+    assert build_version() == expected
+
+
+@pytest.mark.usefixtures("repository")
+def test_build_version_after_tag(build_version: Callable[[], str], git: Callable[..., str]) -> None:
+    git("tag", "4.2.3")
+    git("commit", "--allow-empty", "-m", "After release")
+
+    assert build_version() == f"4.2.3.dev1+g{git('rev-parse', '--short', 'HEAD')}"
+
+
+@pytest.mark.usefixtures("repository")
+def test_build_version_without_release_tag(build_version: Callable[[], str], git: Callable[..., str]) -> None:
+    git("tag", "unrelated")
+
+    assert build_version() == "0.0.0"
+
+
+@pytest.mark.parametrize(
+    ("metadata", "expected"),
+    [
+        pytest.param("Metadata-Version: 2.4\nName: pipdeptree\nVersion: 4.2.3\n\nDescription", "4.2.3", id="sdist"),
+        pytest.param("Version: 4.2.3.dev2+g1234567\n", "4.2.3.dev2+g1234567", id="development-sdist"),
+        pytest.param("Name: pipdeptree\n", "0.0.0", id="missing-version"),
+        pytest.param("Version: \n", "0.0.0", id="empty-version"),
+        pytest.param("Name: pipdeptree\n\nVersion: 9.9.9\n", "0.0.0", id="description-is-not-metadata"),
+        pytest.param(None, "0.0.0", id="missing-metadata"),
+    ],
+)
+def test_build_version_metadata(
+    build_version: Callable[[], str], tmp_path: Path, metadata: str | None, expected: str
+) -> None:
+    if metadata is not None:
+        (tmp_path / "PKG-INFO").write_text(metadata, encoding="utf-8")
+
+    assert build_version() == expected
+
+
+@pytest.mark.usefixtures("repository", "package_metadata")
+@pytest.mark.parametrize("git_available", [pytest.param(True, id="untagged"), pytest.param(False, id="missing-git")])
+def test_build_version_metadata_fallback(
+    build_version: Callable[[], str],
+    git: Callable[..., str],
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    git_available: bool,
+) -> None:
+    if not git_available:
+        git("tag", "4.2.3")
+        monkeypatch.setenv("PATH", "")
+
+    assert build_version() == "4.1.0"
+
+
+@pytest.mark.usefixtures("parent_repository", "package_metadata")
+def test_build_version_parent_repository(build_version: Callable[[], str]) -> None:
+    assert build_version() == "4.1.0"
+
+
+@pytest.fixture(params=[pytest.param("meson", id="meson"), pytest.param("cargo", id="cargo")])
+def build_version(
+    request: pytest.FixtureRequest,
+    meson_version: Callable[[], str],
+    cargo_version: Callable[[], str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> Callable[[], str]:
+    monkeypatch.delenv("PIPDEPTREE_VERSION", raising=False)
+    return {"meson": meson_version, "cargo": cargo_version}[request.param]
+
+
+@pytest.fixture
+def meson_version(
+    project_root: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> Callable[[], str]:
+    def resolve() -> str:
+        with monkeypatch.context() as context:
+            context.setattr(Path, "resolve", create_autospec(Path.resolve, return_value=tmp_path / "tools/version.py"))
+            runpy.run_path(str(project_root / "tools/version.py"), run_name="tools.version")["main"]()
+        return capsys.readouterr().out.strip()
+
+    return resolve
+
+
+@pytest.fixture(scope="session")
+def project_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+@pytest.fixture
+def cargo_version(cargo_build_script: Path, tmp_path: Path) -> Callable[[], str]:
+    def resolve() -> str:
+        result: Final = subprocess.run(
+            [str(cargo_build_script)], cwd=tmp_path, capture_output=True, text=True, check=True
+        )
+        return next(
+            line.split("=", 2)[2]
+            for line in result.stdout.splitlines()
+            if line.startswith("cargo:rustc-env=PIPDEPTREE_VERSION=")
+        )
+
+    return resolve
+
+
+@pytest.fixture(scope="session")
+def cargo_build_script(project_root: Path, tmp_path_factory: pytest.TempPathFactory) -> Path:
+    rustc: Final = which("rustc")
+    assert rustc is not None
+    executable: Final = tmp_path_factory.mktemp("build-version") / "build-version.exe"
+    subprocess.run([rustc, "--edition=2024", str(project_root / "build.rs"), "-o", str(executable)], check=True)
+    return executable
+
+
+@pytest.fixture(params=[pytest.param(False, id="git-directory"), pytest.param(True, id="git-file")])
+def repository(request: pytest.FixtureRequest, git: Callable[..., str], tmp_path: Path) -> None:
+    if request.param:
+        git("init", "--separate-git-dir", str(tmp_path.parent / f"{tmp_path.name}.git"))
+    else:
+        git("init")
+    git("commit", "--allow-empty", "-m", "Initial commit")
+
+
+@pytest.fixture
+def git(tmp_path: Path) -> Callable[..., str]:
+    executable: Final = which("git")
+    assert executable is not None
+
+    def run(*args: str) -> str:
+        return subprocess.run(
+            [
+                executable,
+                "-c",
+                "user.name=Test",
+                "-c",
+                "user.email=test@example.com",
+                "-c",
+                "commit.gpgsign=false",
+                *args,
+            ],
+            cwd=tmp_path,
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+
+    return run
+
+
+@pytest.fixture
+def package_metadata(tmp_path: Path) -> None:
+    (tmp_path / "PKG-INFO").write_text("Version: 4.1.0\n", encoding="utf-8")
+
+
+@pytest.fixture
+def parent_repository(git: Callable[..., str], tmp_path: Path) -> None:
+    git("-C", str(tmp_path.parent), "init")
+    git("-C", str(tmp_path.parent), "commit", "--allow-empty", "-m", "Parent repository")
+    git("-C", str(tmp_path.parent), "tag", "--force", "9.9.9")