Add comprehensive go.sum explanation document
Co-authored-by: mbissa <[email protected]>
diff --git a/GO_SUM_EXPLANATION.md b/GO_SUM_EXPLANATION.md
new file mode 100644
index 0000000..062f31b
--- /dev/null
+++ b/GO_SUM_EXPLANATION.md
@@ -0,0 +1,112 @@
+# 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`:
+```go
+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`:
+```go
+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:
+```bash
+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:
+```bash
+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.
