Skip to content

[doc-only] docs: document setuptools-scm clone requirements for source builds#2424

Open
bharatr21 wants to merge 1 commit into
NVIDIA:mainfrom
bharatr21:setuptools-scm-docs
Open

[doc-only] docs: document setuptools-scm clone requirements for source builds#2424
bharatr21 wants to merge 1 commit into
NVIDIA:mainfrom
bharatr21:setuptools-scm-docs

Conversation

@bharatr21

Copy link
Copy Markdown
Contributor

Description

Closes #2400

Every package in this repo derives its version from git tags via setuptools-scm,
but there's no mention in the docs, and the git clone commands in our own install guides
that are intended to be copied by contributors produce broken builds.

Two of the three bad-clone cases fail silently:

Clone Resolved version
--depth 1 0.1.dev1+g0d22cb444 — no error
--no-tags 0.1.dev2114+g0d22cb444 — no error
source zip (no .git) LookupError — the only case that errors

A partial --depth is worse than none. With the nearest cuda-pathfinder-v* tag
10 commits back, a --depth 20 clone gives:

Package Version Outcome
cuda_pathfinder 1.6.1.dev10+g0d22cb4 Correct, tag falls inside depth
cuda_core 0.1.dev20+g0d22cb444 Wrong, no error
cuda_bindings 0.1.dev20+g0d22cb444 Wrong, no error

So "it built and the version looked right" is not evidence the clone is sound,
and no fixed --depth stays correct as commits land between releases.

Changes

  • CONTRIBUTING.md: new "Cloning the repository" section (plus TOC entries)
    covering the per-package tag patterns, why root = ".." means the whole repo is
    needed, the recommended treeless clone, recovery for shallow clones and stale
    forks, and the symptoms of each failure mode.
  • Install guides: updated the four git clone commands in the cuda_core and
    cuda_pathfinder guides to git clone --filter=blob:none, and added a pointer to
    the new section from all three. cuda_bindings has no clone command, so it gets a
    third requirement bullet alongside the existing CTK header/static-lib ones.

The recommended clone matches what CI already does (fetch-depth: 0 +
filter: blob:none in build-wheel.yml): full commit graph and tags, no historical
blobs. It took 6.2s against github.com.

Verification

  • Treeless clone from GitHub fetches all 87 tags, is not shallow, and has the full
    2114-commit graph; all four packages resolve correct versions
    (13.3.2.dev128, 1.1.1.dev32, 1.6.1.dev10) via python -m setuptools_scm,
    so each package's real pyproject.toml config is exercised.
  • --depth 1, --depth 20, --no-tags, and no-.git failure modes all reproduced
    against the real remote.
  • SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CUDA_CORE and git fetch --unshallow --tags
    recovery paths confirmed working before documenting them.
  • Full pre-commit hook set passes on all four files with no reformatting; RST
    parses clean and lychee reports no broken links.

Checklist

  • I am familiar with the Contributing Guidelines.
  • New or existing tests cover these changes.
  • The documentation is up to date with these changes.

Signed-off-by: Bharat Raghunathan <bharatrgatech@gmail.com>
@copy-pr-bot

copy-pr-bot Bot commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@github-actions github-actions Bot added cuda.bindings Everything related to the cuda.bindings module cuda.core Everything related to the cuda.core module cuda.pathfinder Everything related to the cuda.pathfinder module labels Jul 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cuda.bindings Everything related to the cuda.bindings module cuda.core Everything related to the cuda.core module cuda.pathfinder Everything related to the cuda.pathfinder module

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Include requirements for setuptools-scm success in the CONTRIBUTING docs

1 participant