[doc-only] docs: document setuptools-scm clone requirements for source builds#2424
Open
bharatr21 wants to merge 1 commit into
Open
[doc-only] docs: document setuptools-scm clone requirements for source builds#2424bharatr21 wants to merge 1 commit into
bharatr21 wants to merge 1 commit into
Conversation
Signed-off-by: Bharat Raghunathan <bharatrgatech@gmail.com>
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 clonecommands in our own install guidesthat are intended to be copied by contributors produce broken builds.
Two of the three bad-clone cases fail silently:
--depth 10.1.dev1+g0d22cb444— no error--no-tags0.1.dev2114+g0d22cb444— no error.git)LookupError— the only case that errorsA partial
--depthis worse than none. With the nearestcuda-pathfinder-v*tag10 commits back, a
--depth 20clone gives:cuda_pathfindercuda_corecuda_bindingsSo "it built and the version looked right" is not evidence the clone is sound,
and no fixed
--depthstays 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 isneeded, the recommended treeless clone, recovery for shallow clones and stale
forks, and the symptoms of each failure mode.
git clonecommands in thecuda_coreandcuda_pathfinderguides togit clone --filter=blob:none, and added a pointer tothe new section from all three.
cuda_bindingshas no clone command, so it gets athird requirement bullet alongside the existing CTK header/static-lib ones.
The recommended clone matches what CI already does (
fetch-depth: 0+filter: blob:noneinbuild-wheel.yml): full commit graph and tags, no historicalblobs. It took 6.2s against
github.com.Verification
2114-commit graph; all four packages resolve correct versions
(
13.3.2.dev128,1.1.1.dev32,1.6.1.dev10) viapython -m setuptools_scm,so each package's real
pyproject.tomlconfig is exercised.--depth 1,--depth 20,--no-tags, and no-.gitfailure modes all reproducedagainst the real remote.
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CUDA_COREandgit fetch --unshallow --tagsrecovery paths confirmed working before documenting them.
pre-commithook set passes on all four files with no reformatting; RSTparses clean and lychee reports no broken links.
Checklist