Why go.sum Changes in PRs

Question: Why does go.sum have to change in PR #8627?

Short Answer: It doesn't. PR #8627 does not modify go.sum or go.mod.

Detailed Explanation

What Changed in PR #8627?

PR #8627 (“xdsclient: stop batching writes on the ADS stream”) only modified internal implementation files:

  • internal/xds/clients/internal/buffer/unbounded.go
  • internal/xds/clients/xdsclient/ads_stream.go
  • internal/xds/clients/xdsclient/channel.go

No dependency changes were made, so go.mod and go.sum remain unchanged.

Why go.sum Might Appear in the PR Diff

If you see go.sum in the PR diff, it may be due to:

  1. Git grafted/shallow clone artifacts: When viewing a shallow clone or grafted repository, module files may appear as “new” even when unchanged
  2. Display formatting: Some diff viewers show all module files when any module in the multi-module repo changes
  3. Transitive dependency updates: Other modules in subdirectories may have updated their go.sum files

When DOES go.sum Need to Change?

The go.sum file must be updated when:

1. Adding New Dependencies

When you add a new import that requires a package not already in go.mod:

import "github.com/new/package"

Run go mod tidy to update both go.mod and go.sum.

2. Updating Dependency Versions

When explicitly updating a dependency version in go.mod:

require github.com/some/package v2.0.0  // updated from v1.0.0

Run go mod tidy to update go.sum with new checksums.

3. Removing Dependencies

When removing code that was the last use of a dependency, run go mod tidy to clean up go.sum.

4. Adding New Transitive Dependencies

When updating a direct dependency that itself adds new dependencies, go.sum will include checksums for those transitive dependencies.

When Does go.sum NOT Need to Change?

The go.sum file does NOT need to change when:

  1. Modifying existing code: Changes to implementation that don't affect dependencies
  2. Adding tests: Unless tests import new packages
  3. Refactoring: Moving code around without changing imports
  4. Documentation changes: Updates to comments, README, etc.
  5. Bug fixes: Most bug fixes that don't require new dependencies

What is go.sum?

The go.sum file contains cryptographic checksums of the content of specific module versions. It ensures:

  • Reproducible builds: Everyone gets the same dependencies
  • Security: Detects if a dependency has been tampered with
  • Integrity: Verifies downloaded modules match expected content

Each line in go.sum represents either:

  • The module's go.mod file: <module> <version>/go.mod h1:<hash>
  • The module's complete code: <module> <version> h1:<hash>

How to Update go.sum

When dependencies change, always run:

go mod tidy

This command:

  1. Adds missing dependencies required by your code
  2. Removes dependencies no longer needed
  3. Updates go.sum with all necessary checksums
  4. Cleans up go.mod formatting

Multi-Module Repository Note

gRPC-Go is a multi-module repository with several go.mod files:

  • Root /go.mod and /go.sum
  • /examples/go.mod and /examples/go.sum
  • /security/advancedtls/go.mod and /security/advancedtls/go.sum
  • And others...

A PR may need to update go.sum in multiple modules if changes affect multiple modules.

Verification

To verify if go.sum is correct and up-to-date:

go mod tidy
git diff go.sum

If git diff shows no changes, your go.sum is already correct.

Summary for PR #8627

For PR #8627 specifically:

  • ✅ Only internal code was modified
  • ✅ No new imports were added
  • ✅ No dependency versions were changed
  • ✅ go.sum correctly remained unchanged
  • ✅ This is the expected behavior for internal refactoring

If you see go.sum in the diff, it's a display artifact, not an actual change.