feat(build): compute ddtrace version dynamically from git state

Replace setuptools_scm's abandoned release-branch-semver scheme (broken by
detached-HEAD branch detection) and the manual version-bump PR process with
scripts/compute_version.py: a dependency-free script that derives PEP 440
versions from git tags/branches, using explicit CI-provided ref info (never
`git rev-parse --abbrev-ref HEAD` alone) and ancestry-independent global tag
comparison for main's "latest shipped release" (release branches never merge
back, so ancestry-based lookup misses sibling-branch releases).

Validated so far:
- Unit tests against synthetic git repos (tests/scripts/test_compute_version.py),
  covering all 4 version rules, detached HEAD, GH/GitLab ref resolution, and the
  main-after-sibling-branch-release regression case.
- Historical replay against this repo's real git history (via disposable
  worktrees) for rules 1-3: exact tag builds, release-branch patch/dev
  versions, and freshly-cut release branches all matched expected output.

Still outstanding before this can be trusted in production CI:
- Cross-CI determinism: confirm GitHub Actions and GitLab CI resolve the same
  branch name and produce an identical version string for the same commit.
- cibuildwheel's manylinux/musllinux containers: verify `git` is available
  (needed since setup.py recomputes the version inside those containers too).
- sdist-then-wheel round trip: confirm ddtrace/_version_frozen.py, written
  when git is available, is correctly read back when a wheel is built from an
  sdist with no .git present.
- GIT_DEPTH: "0" on the GitLab package/build jobs: confirm against a live
  pipeline that full tag history is actually fetched (rule 4's global tag scan
  needs it).

Pre-commit hooks (mypy, bandit) skipped for this commit with explicit sign-off:
both are triggered by pre-existing, unrelated issues in scripts/gen_gitlab_config.py's
import graph (tests/suitespec.py, scripts/needs_testrun.py) that predate this
change and are outside mypy.ini's official `files = ddtrace, docs` scope, plus
expected Low-severity bandit findings on this script's inherent subprocess/assert
usage.

Author: P403n1x87

.gitignore

@@ -248,3 +248,6 @@ ddtrace/profiling/collector/build-test/
 # file created when running scripts/lint
 uv.lock
 .riot/*.installed
+
+# generated by scripts/compute_version.py at build time
+ddtrace/_version_frozen.py

.gitlab/package.yml

@@ -32,6 +32,7 @@ variables:
 .build_base:
   stage: package
   variables:
+    GIT_DEPTH: "0"
     CMAKE_BUILD_PARALLEL_LEVEL: "12"
     CARGO_BUILD_JOBS: "12"
     CMAKE_ARGS: "-DNATIVE_TESTING=OFF"
@@ -283,6 +284,7 @@ variables:
       - PYTHON_VERSION: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
         WINDOWS_ARCH: ["amd64", "x86"]
   variables:
+    GIT_DEPTH: "0"
     WINDOWS_BUILD_IMAGE: "registry.ddbuild.io/images/mirror/dd-trace-py/windows-build:d4d18a67d43d400d3ecc6bda777a5e233a24f434@sha256:58c3e28646ddf8a1021a079a380c8840e51f0b88c1489a522beee6ec99413019"
   script:
     - bash .gitlab/scripts/build-wheel-windows.sh
@@ -385,13 +387,15 @@ download_dependency_wheels:
   script:
     - .gitlab/scripts/upload-debug-symbols-to-backend.sh
 
-# Extract package version from pyproject.toml and save to dotenv artifact
+# Compute package version from git state and save to dotenv artifact
 "package version":
   image: registry.ddbuild.io/images/mirror/python:3.14.0
   tags: [ "arch:amd64" ]
   stage: package
+  variables:
+    GIT_DEPTH: "0"
   script:
-    - PACKAGE_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+    - PACKAGE_VERSION=$(scripts/compute_version.py)
     - echo "PACKAGE_VERSION=${PACKAGE_VERSION}" | tee -a package_version.env
     # Validate commit tag matches version if tag is set
     - |

.gitlab/templates/cached-testrunner.yml

@@ -5,6 +5,7 @@
     EXT_CACHE_VENV: '${{CI_PROJECT_DIR}}/.cache/ext_cache_venv${{PYTHON_VERSION}}'
   before_script: |
     ulimit -c unlimited
+    git config --global --add safe.directory ${{CI_PROJECT_DIR}}
     # 3.15 is shipped as the pyenv version "3.15-dev" until
     # upstream CPython 3.15 is released. The shim is the usual "python3.15"
     # (no -dev suffix on the binary), so build_base_venvs' `python$PYTHON_VERSION`

docs/contributing-release.rst

@@ -24,8 +24,12 @@ High-Level Steps
 These are the high-level steps involved in all ddtrace releases:
 
 1. Set / Validate branch structure
-2. Set / Validate version strings on branches
-3. Make a GitHub release
+2. Make a GitHub release
+
+There is no version-string pull request in any of these steps: the version is computed automatically
+from git state at build time by ``scripts/compute_version.py``. See "Version String" below. The only
+manual action that determines a release's version is the exact tag created by the GitHub release
+itself.
 
 Here are the specifics of those steps for all of the different types of releases. See even more detail in the sections that follow.
 
@@ -36,14 +40,9 @@ Patch Release
 
     * A branch named after the relevant minor version line (``X.Y``) is expected to already exist. This is the "release branch".
 
-2. Set / Validate version strings on branches
-
-    * The version string on the release branch is currently set to a patch version on the relevant minor release line (for example, ``1.2.3``)
-    * Pull request a change to the version string on the release branch that sets it to the patch version you're releasing.
-
-3. Make a GitHub release
+2. Make a GitHub release
 
-    * Target: the merged commit from the version string pull request above
+    * Target: the tip of the release branch
     * "Set as latest" may be applicable
     * "Pre-release" unchecked
 
@@ -54,15 +53,9 @@ Minor or Major Release Candidate
 
     * The main branch exists
 
-2. Set / Validate version strings on branches
-
-    * main's version string is currently a release candidate ``rc`` version.
-    * Pull request a change to the version string on the main branch that sets it to the next release candidate on the current minor release line.
-        In practice this means incrementing the ``rcX`` number by one.
-
-3. Make a GitHub release
+2. Make a GitHub release
 
-    * Target: the merged commit from the version string pull request above
+    * Target: the tip of the main branch
     * "Pre-release" checked
 
 Minor or Major Release
@@ -80,43 +73,54 @@ Minor or Major Release
         $ git merge main -Xtheirs # this keeps the tags intact so that reno will work properly
         $ git push -u origin X.Y
 
-2. Set / Validate version strings on branches
+2. Make a GitHub release
 
-    * main's version string is currently a release candidate ``rc`` version.
-    * Pull request a change to the version string on the main branch that sets it to ``rc1`` on the next release line.
-        For example: in step 1 we created branch ``1.3``, and we will change the version string on main to ``1.4.0rc1``.
-    * The version string on the release branch is currently set to a patch version on the previous minor release line.
-        For example: in step 1 we created branch ``1.3``, and it has a version string of ``1.2.9``
-    * Pull request a change to the version string on the release branch that sets it to the minor version you're releasing.
-
-3. Make a GitHub release
-
-    * Target: the merged commit on the release branch from the version string pull request above
+    * Target: the tip of the release branch created above
     * "Set as latest" checked
     * "Pre-release" unchecked
 
 Version String
 --------------
 
-The ``[project.version]`` attribute in ``pyproject.toml`` is the source of truth about the version of ddtrace.
-If you inspect a ddtrace wheel via directory exploration or ``print(ddtrace.__version__)``, the version you find will match the
-version in the wheel's name.
-
-If you check the attribute on a checkout of the ddtrace main branch, you will find it set to the ``rcX`` release candidate version
-that comes next on the currently under-development minor release line. For example:
+ddtrace's version is not a literal anywhere in the source tree. It's computed at build time by
+``scripts/compute_version.py`` from git state, and exposed as ``ddtrace.__version__`` via the
+installed package's metadata. If you inspect a ddtrace wheel via directory exploration or
+``print(ddtrace.__version__)``, the version you find will match the version in the wheel's name.
+
+The rules, applied in order:
+
+1. If the commit being built is exactly tagged ``vX.Y.Z`` or ``vX.Y.ZrcN``, the version is that tag,
+   verbatim (``v`` stripped). This is the only way a final or ``rc`` version is ever produced — always
+   by a human creating that exact tag, e.g. as part of making a GitHub release.
+2. Otherwise, on a release branch (named ``X.Y``): the next patch version after the latest ``vX.Y.Z``
+   tag on that branch, suffixed ``.devN`` (``N`` = commits since that tag), or ``X.Y.0.devN`` if the
+   branch was just cut and has no tag yet.
+3. Otherwise (``main``, feature branches, PRs): the next minor version after the latest final release
+   anywhere in the repo, suffixed ``.devN``.
+
+For example:
+
+* Latest release: ``4.4.0`` -> version on main: ``4.5.0.devN``
+* Latest release: ``4.3.0rc4`` -> version on main: ``4.4.0.devN`` (rc's don't count as "the latest
+  final release" — only an actual ``vX.Y.Z`` tag does)
+* Latest release: ``4.4.0`` -> version on the ``4.4`` branch: ``4.4.1.devN``
+* Latest release: ``4.2.1`` -> version on the freshly-cut ``4.3`` branch, no tag yet: ``4.3.0.devN``
+
+Branch identity for rules 2/3 comes from CI-provided ref info (GitHub Actions'
+``GITHUB_HEAD_REF``/``GITHUB_REF_NAME``, GitLab's ``CI_COMMIT_BRANCH``/``CI_COMMIT_REF_NAME``), not
+from ``git rev-parse --abbrev-ref HEAD`` — that returns the literal string ``"HEAD"`` under a detached
+checkout, which is the norm for CI, and silently misclassifies release branches as "main-like" if
+relied upon. To compute what a particular branch's version would be from a local, possibly-detached
+checkout (for example, testing a release branch cut before pushing it), set
+``_DD_TRACE_BUILD_VERSION=X.Y`` in the environment to override branch detection:
 
-* Latest release: ``4.4.0`` -> version string on main: ``4.5.0rc1``
-* Latest release: ``4.3.0rc4`` -> version string on main: ``4.3.0rc5``
-* Latest release: ``4.2.1`` -> version string on main: ``4.3.0rc1``
-
-If you check the attribute on a checkout of a ddtrace release branch with a name like ``X.Y``, you will find it set to the patch release version
-that comes next on that minor release line. For example:
+.. code-block:: bash
 
-* Latest release: ``4.4.0`` -> version string on 4.4 branch: ``4.4.1dev``
-* Latest release: ``4.3.0rc4`` -> version string on 4.3 branch: not applicable, branch doesn't exist
-* Latest release: ``4.2.1`` -> version string on 4.2: ``4.2.2dev``
+    $ _DD_TRACE_BUILD_VERSION=4.13 scripts/compute_version.py
 
-If ever you discover that one of these guarantees is not upheld, please open a pull request adjusting the version string accordingly.
+If you ever find a computed version doesn't match one of the rules above, that's a bug in
+``scripts/compute_version.py`` (see ``tests/scripts/test_compute_version.py``) — not something to work
+around by hand-editing a version string, since there is no longer one to edit.
 
 
 Pre-Release Performance Gates

pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ddtrace"
-version = "4.15.0rc1"
+dynamic = ["version"]
 description = "Datadog APM client library"
 readme = "README.md"
 license = { text = "LICENSE.BSD3" }

scripts/check_suitespec_coverage.py

@@ -25,6 +25,10 @@
 # Ignore any embedded documentation
 IGNORE_PATTERNS.add("**/*.md")
 
+# Standalone scripts/*.py tests run directly (e.g. via scripts/gen_gitlab_config.py's own check
+# list), not through a riot-managed suite, so they have no suite pattern to match against.
+IGNORE_PATTERNS.add("tests/scripts/*.py")
+
 
 def owners(path: str) -> str:
     return ", ".join(CODEOWNERS.of(path))