Skip to content

fix: KEEP-1056 pin cobra/doc tooling deps so go mod tidy stops pruning go.sum - #82

Merged
suisuss merged 1 commit into
mainfrom
fix/KEEP-1056-pin-cobra-doc-tooling-deps
Jul 29, 2026
Merged

fix: KEEP-1056 pin cobra/doc tooling deps so go mod tidy stops pruning go.sum#82
suisuss merged 1 commit into
mainfrom
fix/KEEP-1056-pin-cobra-doc-tooling-deps

Conversation

@suisuss

@suisuss suisuss commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Problem

Every dependabot Go module bump fails the docs-check CI job:

missing go.sum entry for module providing package github.com/cpuguy83/go-md2man/v2/md2man
  (imported by github.com/spf13/cobra/doc)
docs/doc.go:14: running "go": exit status 1

docs/generate.go carries //go:build ignore, so go mod tidy never sees its import of
github.com/spf13/cobra/doc. Tidy treats go-md2man/v2 and blackfriday/v2 as unreachable
and prunes their h1: hashes from go.sum. Doc generation then cannot compile cobra/doc.
Dependabot runs tidy on every bump, so this reproduces on every Go module PR.

KEEP-1051 (#76) moved the //go:generate directive into docs/doc.go because directives in
build-excluded files are never scanned. That made generation actually run, which exposed this
latent hole rather than creating it.

Fix

A tools-tagged blank import in docs/tools.go. go mod tidy evaluates imports under all
build tag combinations, unlike the compiler, so the tag keeps the file out of every real build
while holding the hashes pinned.

Alternatives considered and rejected:

  • Go 1.24 tool directive: cobra/doc is a library, not a main package, so go tool rejects
    it, and go get -tool silently upgraded cobra to 1.10.2 as a side effect.
  • CI-side go get before generating: docs-check only runs git diff --exit-code docs/, so
    it would go green while leaving main's go.sum pruned, breaking go generate locally for
    everyone and at release time in sync-cli-docs.yml.
  • Making the generator an untagged package: works, but churns a file fix: KEEP-1051 make docs generation actually run, and regenerate the reference #76 just rewrote.

Also included

golang.org/x/crypto was marked // indirect while cmd/read/read.go:13 imports it directly,
so go.mod was not tidy-clean and any tidy run promoted it. Landing that deliberately here.
Version is unchanged at 0.46.0; the bump to 0.52.0 remains #81's job.

Verification

Run in golang:1.25 and golangci-lint:latest-alpine containers:

  • go mod tidy now leaves go.sum completely untouched (previously it stripped four h1: lines)
  • go generate ./docs/ succeeds and git diff --exit-code docs/ is clean, which is the check that fails on chore(deps): bump golang.org/x/crypto from 0.46.0 to 0.52.0 #81 today
  • go build ./..., go vet ./..., go test ./... (28 packages) all pass
  • golangci-lint run ./... reports 0 issues
  • go list -deps ./cmd/kh contains no md2man, so the shipped binary is unaffected

Follow-up

PRs #36, #37 and #81 all carry the identical pruning and will keep failing docs-check until
this lands. Once merged, @dependabot recreate each so tidy reruns against a main containing
tools.go. #32 (actions/checkout) is unaffected.

…g go.sum

generate.go carries //go:build ignore, so go mod tidy never sees its import
of github.com/spf13/cobra/doc and prunes go-md2man and blackfriday from
go.sum. Doc generation then fails with a missing go.sum entry. Dependabot
runs tidy on every bump, so this broke docs-check on PRs #36, #37 and #81.

Add a tools-tagged blank import. go mod tidy evaluates imports under all
build tag combinations, unlike the compiler, so the tag keeps the file out
of every real build while holding those hashes pinned. Verified: tidy now
leaves go.sum untouched, and go list -deps ./cmd/kh has no md2man.

Also promote golang.org/x/crypto out of the indirect block: cmd/read/read.go
imports it directly, so go.mod was not tidy-clean and any tidy run moved it.
@suisuss
suisuss merged commit bde0e8f into main Jul 29, 2026
4 checks passed
@suisuss
suisuss deleted the fix/KEEP-1056-pin-cobra-doc-tooling-deps branch July 29, 2026 01:46
@eskp eskp mentioned this pull request Jul 29, 2026
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