Skip to content

docs: drop the fetch-depth requirement, semvertag never reads the working tree - #75

Merged
lesnik512 merged 1 commit into
mainfrom
docs/fetch-depth-is-not-needed
Sep 19, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/fetch-depth-is-not-needed

Conversation

@lesnik512

Copy link
Copy Markdown
Member

What was verified in the code

  • grep -rE 'subprocess|pygit2|dulwich|GitPython|os\.system|shutil\.which' semvertag/ returns nothing. The full import set of the package is stdlib plus httpx2, httpware, pydantic, pydantic-settings, semver, typer, rich, modern_di. No git binary, no git library.
  • grep -rE 'open\(|Path\(|pathlib|read_text|\.toml|env_file' semvertag/ returns nothing. The package never reads a file from the tree; _settings.py is pure pydantic-settings over environment variables and CLI flags.
  • semvertag/providers/_base.py defines the whole provider surface as four REST calls: get_default_branch, get_latest_commit_on_default_branch, list_tags, create_tag. providers/github.py implements them against /repos/{repo}, /repos/{repo}/commits?per_page=1, /repos/{repo}/tags and POST /repos/{repo}/git/refs.
  • semvertag/_use_case.py fetches exactly one commit (the head of the default branch) and the tag list, then passes that single Commit to strategy.decide. strategies/conventional_commits.py and strategies/branch_prefix.py both take one Commit. Nothing walks history.
  • action.yml runs astral-sh/setup-uv then uvx 'semvertag>=0.5.0,<1' tag. It reads nothing from the tree, so the composite action needs no checkout step for its own operation.

This matches docs/adr/0005-composite-action-does-not-check-out.md, merged in #74.

What each page said before and says now

README.md, "Use it in GitHub Actions"

  • Before: the sample workflow opened with actions/checkout@v4 and fetch-depth: 0, and the prose said "fetch-depth: 0 matters, the default 1 misses tag-relative history".
  • Now: the sample workflow is - uses: modern-python/semvertag@v0 alone, and the prose says semvertag never reads the working tree so the job needs no actions/checkout step at all.

docs/providers/github.md, Quick Start

  • Before: the workflow began with a fetch-depth: 0 checkout.
  • Now: the workflow is the action step alone.

docs/providers/github.md, the admonition under Quick Start

  • Before: "fetch-depth: 0 matters: semvertag walks commit history to determine the bump. actions/checkout@v4's default fetch-depth: 1 only fetches the single tip commit and will miss tag-relative history." Both claims are false: semvertag does not walk history, and the single tip commit is in fact all it uses, read over the API rather than from the tree.
  • Now: "No checkout needed." It states that the head commit and tag history come over the GitHub API, that neither an actions/checkout step nor a fetch-depth setting is required, and that a checkout is worth adding only when other steps in the same job need the repository files.

docs/providers/github.md, the outputs example (semvertag-and-release)

  • Before / now: same removal of the fetch-depth: 0 checkout; the downstream step only reads step outputs.

docs/providers/github.md, "Without the composite action" pure-CLI recipe

  • Before / now: same removal. uvx semvertag tag reads the API, not the tree.

.github/workflows/semvertag.yml (dogfood) and .github/workflows/ci.yml (action-smoke)

  • Before: actions/checkout@v6 with fetch-depth: 0.
  • Now: actions/checkout@v6 with no with: block. These two jobs do still need a checkout, because they run the action by local path (uses: ./) and Actions can only resolve that from a checked-out tree. They never needed the history depth. Leaving fetch-depth: 0 here would have contradicted the page this PR fixes.

action.yml itself mentions no checkout and needed no change. docs/index.md and docs/providers/gitlab.md already described the API-only behaviour correctly and are untouched.

Gates

Gate Result
uv run --no-sync pytest -q 481 passed in 5.26s
uv run --no-sync eof-fixer . --check clean, no output
lychee --offline --no-progress README.md docs/providers/github.md 33 unique links, 0 errors
same with CI's --remap of blob/main URLs to the workspace 33 unique, 6 OK, 0 errors
just docs-build (mkdocs build --strict) built successfully, no warnings

Out of scope, noted for a follow-up

docs/providers/github.md describes conventional-commits as bumping "from Conventional Commits headers since the last tag" (strategy table) and as scanning "commits since the last tag" (the "Branch-prefix vs conventional-commits" section). The code decides from the head commit alone. That is a separate inaccuracy about strategy semantics rather than about checkout depth, so this PR leaves it alone.

…king tree

semvertag/ contains no subprocess call, no git library and no filesystem
access. The head commit and the tag list come from the forge REST API, and
the bump is decided from that single head commit. No git clone depth can
affect the result, so the documented fetch-depth: 0 requirement was never
real, and the composite action needs no checkout step at all.

README.md and docs/providers/github.md now show the workflow without a
checkout step, and the github.md admonition explains that a checkout is
only needed when other steps in the job want the repository files.

The repo's own dogfood workflow and the PR action-smoke job keep their
checkout, which uses: ./ requires, but drop fetch-depth: 0.
@lesnik512
lesnik512 merged commit 289b1bb into main Sep 19, 2026
9 checks passed
@lesnik512
lesnik512 deleted the docs/fetch-depth-is-not-needed branch September 19, 2026 11:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant