Update Go Version

Steps

0. Create a feature branch

Always create a new branch from the latest main before making any changes. Never commit directly to main.

git checkout main
git fetch origin
git pull origin main
git checkout -b update-go-X.Y.Z

Use the naming convention update-go-X.Y.Z where X.Y.Z is the target version.

1. Read current state

Extract the current versions from the codebase:

• go directive from go.mod (line 3, e.g. go 1.24.6)
• toolchain directive from go.mod (line 5, e.g. toolchain go1.24.9)
• go-version from .github/workflows/ci.yml (e.g. 1.24.13)

Report these to the user before making changes.

2. Determine bump type

Compare the target version against the current toolchain directive in go.mod:

• Same minor (e.g. current toolchain go1.25.3, target 1.25.7): patch bump. Only the toolchain directive and build/CI files need updating.
• Different minor (e.g. current toolchain go1.24.9, target 1.25.7): minor bump. The toolchain directive and build/CI files need updating. Ask the user whether to also update the go directive (see step 4).

Tell the user which type was detected before proceeding.

3. Run the upgrade script

The tools/upgrade-go-version.sh script handles CI, Dockerfile, and release config updates. It also creates a git commit with those changes:

bash tools/upgrade-go-version.sh X.Y.Z

This updates and commits:

• .github/workflows/*.yml — go-version: values
• .goreleaser.yaml — version check hook
• .pyroscope.yaml — ref: for Go stdlib source linking and GO_VERSION
• tools/update_examples.Dockerfile — GO_VERSION ARG
• All Go Dockerfiles — FROM golang: base image tag (excluding ebpf testdata)

4. Update toolchain directive in go.mod and go.work files

Update the toolchain directive to goX.Y.Z in all go.mod files using go mod edit, and the root go.work using go work edit:

# For go.mod files:
go mod edit -toolchain=goX.Y.Z <file>

# For go.work files (go mod edit does NOT work on .work files):
go work edit -toolchain=goX.Y.Z <file>

go.mod files:

• go.mod
• api/go.mod
• lidia/go.mod
• examples/golang-pgo/go.mod
• examples/tracing/golang-push/go.mod
• examples/language-sdk-instrumentation/golang-push/rideshare/go.mod
• examples/language-sdk-instrumentation/golang-push/rideshare-alloy/go.mod
• examples/language-sdk-instrumentation/golang-push/rideshare-k6/go.mod
• examples/language-sdk-instrumentation/golang-push/simple/go.mod

go.work (root only — use go work edit):

• go.work

Optional: update go directive (minor bump only)

The go directive sets the minimum compatible Go version. Only update it when:

• A dependency requires a newer Go version
• The codebase uses a Go language feature from the newer minor version
• The user explicitly requests it

If updating the go directive, the go and toolchain values MUST differ to prevent Go from dropping the toolchain line. Use two separate calls:

# For go.mod files:
go mod edit -go=X.Y.0 <file>
go mod edit -toolchain=goX.Y.Z <file>

# For go.work files (go mod edit does NOT work on .work files):
go work edit -go=X.Y.0 <file>
go work edit -toolchain=goX.Y.Z <file>

Also update the go directive in all go.work files (use go work edit):

• go.work
• examples/golang-pgo/go.work
• examples/tracing/golang-push/go.work
• examples/language-sdk-instrumentation/golang-push/rideshare/go.work
• examples/language-sdk-instrumentation/golang-push/rideshare-alloy/go.work
• examples/language-sdk-instrumentation/golang-push/rideshare-k6/go.work
• examples/language-sdk-instrumentation/golang-push/simple/go.work

5. Synchronize Go modules

make go/mod

This runs go work sync and go mod tidy across all modules. Required because CI runs check/go/mod.

Review the diff. Expected: go.sum changes, small indirect dependency bumps. Investigate anything unexpected.

6. Verify the build

make go/bin

If the build fails, investigate and fix before proceeding.

7. Commit remaining changes

The script already committed CI/Dockerfile/release changes. Now commit the go.mod/go.work/go.sum changes:

git add -u *.mod *.sum *.work api/ lidia/ examples/

Use a commit message that reflects what changed:

• Toolchain only: "Update Go toolchain to goX.Y.Z"
• Toolchain + go directive: "Update Go to X.Y.Z (go directive + toolchain)"

8. Summary

Show the user:

• Number of files modified
• Old -> New version for each category (go directive, toolchain, CI, Dockerfiles)
• Whether it was a minor or patch bump
• Build verification result
• Remind user to review commits and push when ready

Version semantics reference