Go Releases Basics

10 examples to get you started with Go releases and upgrades - 7 basic and 3 intermediate.

Prerequisites

Go 1.26.x installed (go version should report go1.26 or later)
A module with go.mod at the repo root
Git clean enough to review go fix diffs

go version
go env GOTOOLCHAIN

Basic Examples

1. Check Your Toolchain Version

Know which compiler is building your binaries.

go version
# go version go1.26.0 darwin/arm64
 
go env GOTOOLCHAIN
# auto

go version reports the active toolchain binary
GOTOOLCHAIN=auto (default) may download a newer toolchain when go.mod requires it
CI should print go version on every build log for incident correlation

Related: Go 1.26 Highlights - what changed in the current release

2. Read the Official Release Notes

Release notes are the contract between the Go team and production teams.

go doc -u cmd/go
# Or open: https://go.dev/doc/go1.26

Language changes appear first, then tools, runtime, compiler, and stdlib
Runtime and GC sections matter even when your source code is unchanged
Deprecated GODEBUG settings often get removal timelines two releases ahead

Related: Reading Release Notes Like a Tech Lead - structured review checklist

3. Pin the Language Version in go.mod

The go directive sets minimum language semantics for the module.

module example.com/shop
 
go 1.25

go get go@1.26.0
# updates go.mod: go 1.26.0

Bumping go enables newer language features and may change type-checker behavior
Toolchain version and go directive can differ when GOTOOLCHAIN=auto downloads a newer compiler
Libraries often lag one minor version behind applications to keep downstream consumers compatible

Related: The Go 1 Compatibility Promise in Practice - what the promise covers

4. Understand the Six-Month Cadence

Go minor releases arrive on a predictable schedule.

Go 1.24  ->  February 2025
Go 1.25  ->  August 2025
Go 1.26  ->  February 2026
Go 1.27  ->  August 2026 (expected)

One minor release every six months, typically February and August
Patch releases (1.26.1, 1.26.2) ship security and critical fixes between minors
Plan upgrade windows within 1-2 months of a new minor unless policy requires faster adoption

Related: Go's Evolution - how the cadence became policy

5. Preview go fix Modernizers

Go 1.26 revamps go fix as a modernization tool built on the same framework as go vet.

go fix -diff ./...

go tool fix help
# lists analyzers: any, minmax, mapsloop, newexpr, forvar, ...

Run from a clean git tree; fixes can touch hundreds of files
-diff previews changes without writing files
Run twice on large repos; synergistic fixes may appear after the first pass

Related: Go 1.26 Highlights - Green Tea GC and modernizers in depth

6. Opt Out of Green Tea GC Temporarily

Green Tea is the default garbage collector in Go 1.26.

GOEXPERIMENT=nogreenteagc go build -o app ./cmd/app

Expect 10-40% less GC CPU time on many workloads; some see smaller gains
Disable only while investigating a suspected GC regression, then file an issue
The opt-out is expected to be removed in Go 1.27

Related: Major Milestones - runtime improvements across releases

7. Track GODEBUG Behavior Flags

Some stdlib behavior changes are gated behind GODEBUG until the next major removal cycle.

GODEBUG=tls10server=1 go test ./...

// go.mod may also influence default behavior via the go directive version

Release notes list GODEBUG settings scheduled for removal (often Go 1.27+)
Staging should test both default and legacy GODEBUG when upgrading TLS or timer code
Document any production GODEBUG overrides in runbooks

Intermediate Examples

8. Upgrade a Single Module Safely

A minimal upgrade loop for one service repository.

git checkout -b upgrade/go-1.26
 
go get go@1.26.0
go mod tidy
go test ./...
 
go fix ./...
go test ./...
 
go vet ./...

go mod tidy after the version bump catches transitive requirement drift
Run go fix before manual cleanup so helpers become unused in one pass
go vet catches issues modernizers do not fix

Related: Planning Go Version Upgrades Across a Monorepo - multi-module rollout

9. Coordinate go.work in a Monorepo

Workspaces let multiple modules upgrade together without local replace hacks.

// go.work
go 1.26.0
 
use (
    ./services/api
    ./services/worker
    ./libs/shared
)

go work sync
go test ./...

go work sync aligns go and toolchain directives across workspace modules
Bump the workspace go line before individual module bumps in a coordinated rollout
Remove stale use entries when modules are archived

Related: Major Milestones - workspaces landed in Go 1.18

10. Record Upgrade Decisions in an ADR

Capture what you tested and what you deferred.

## ADR: Adopt Go 1.26
 
### Context
Green Tea GC default; go fix modernizers; new(expr) for optional JSON fields.
 
### Decision
Upgrade staging week 1; production week 3 after p99 GC pause review.
 
### Rollback
Rebuild with GOEXPERIMENT=nogreenteagc; revert go.mod to go 1.25.0.

Link release-note sections to test evidence (benchmarks, canary metrics)
Note GODEBUG and GOEXPERIMENT overrides explicitly
Set a review date to remove temporary opt-outs

Related: Go History & Releases Best Practices - team habits for safe upgrades

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).

Go Releases Basics

10 examples to get you started with Go releases and upgrades - 7 basic and 3 intermediate.

Prerequisites

Go 1.26.x installed (go version should report go1.26 or later)
A module with go.mod at the repo root
Git clean enough to review go fix diffs

go version
go env GOTOOLCHAIN

Basic Examples

1. Check Your Toolchain Version

Know which compiler is building your binaries.

go version
# go version go1.26.0 darwin/arm64
 
go env GOTOOLCHAIN
# auto

go version reports the active toolchain binary
GOTOOLCHAIN=auto (default) may download a newer toolchain when go.mod requires it
CI should print go version on every build log for incident correlation

Related: Go 1.26 Highlights - what changed in the current release

2. Read the Official Release Notes

Release notes are the contract between the Go team and production teams.

go doc -u cmd/go
# Or open: https://go.dev/doc/go1.26

Language changes appear first, then tools, runtime, compiler, and stdlib
Runtime and GC sections matter even when your source code is unchanged
Deprecated GODEBUG settings often get removal timelines two releases ahead

Related: Reading Release Notes Like a Tech Lead - structured review checklist

3. Pin the Language Version in go.mod

The go directive sets minimum language semantics for the module.

module example.com/shop
 
go 1.25

go get go@1.26.0
# updates go.mod: go 1.26.0

Bumping go enables newer language features and may change type-checker behavior
Toolchain version and go directive can differ when GOTOOLCHAIN=auto downloads a newer compiler
Libraries often lag one minor version behind applications to keep downstream consumers compatible

Related: The Go 1 Compatibility Promise in Practice - what the promise covers

4. Understand the Six-Month Cadence

Go minor releases arrive on a predictable schedule.

Go 1.24  ->  February 2025
Go 1.25  ->  August 2025
Go 1.26  ->  February 2026
Go 1.27  ->  August 2026 (expected)

One minor release every six months, typically February and August
Patch releases (1.26.1, 1.26.2) ship security and critical fixes between minors
Plan upgrade windows within 1-2 months of a new minor unless policy requires faster adoption

Related: Go's Evolution - how the cadence became policy

5. Preview go fix Modernizers

Go 1.26 revamps go fix as a modernization tool built on the same framework as go vet.

go fix -diff ./...

go tool fix help
# lists analyzers: any, minmax, mapsloop, newexpr, forvar, ...

Run from a clean git tree; fixes can touch hundreds of files
-diff previews changes without writing files
Run twice on large repos; synergistic fixes may appear after the first pass

Related: Go 1.26 Highlights - Green Tea GC and modernizers in depth

6. Opt Out of Green Tea GC Temporarily

Green Tea is the default garbage collector in Go 1.26.

GOEXPERIMENT=nogreenteagc go build -o app ./cmd/app

Expect 10-40% less GC CPU time on many workloads; some see smaller gains
Disable only while investigating a suspected GC regression, then file an issue
The opt-out is expected to be removed in Go 1.27

Related: Major Milestones - runtime improvements across releases

7. Track GODEBUG Behavior Flags

Some stdlib behavior changes are gated behind GODEBUG until the next major removal cycle.

GODEBUG=tls10server=1 go test ./...

// go.mod may also influence default behavior via the go directive version

Release notes list GODEBUG settings scheduled for removal (often Go 1.27+)
Staging should test both default and legacy GODEBUG when upgrading TLS or timer code
Document any production GODEBUG overrides in runbooks

Intermediate Examples

8. Upgrade a Single Module Safely

A minimal upgrade loop for one service repository.

git checkout -b upgrade/go-1.26
 
go get go@1.26.0
go mod tidy
go test ./...
 
go fix ./...
go test ./...
 
go vet ./...

go mod tidy after the version bump catches transitive requirement drift
Run go fix before manual cleanup so helpers become unused in one pass
go vet catches issues modernizers do not fix

Related: Planning Go Version Upgrades Across a Monorepo - multi-module rollout

9. Coordinate go.work in a Monorepo

Workspaces let multiple modules upgrade together without local replace hacks.

// go.work
go 1.26.0
 
use (
    ./services/api
    ./services/worker
    ./libs/shared
)

go work sync
go test ./...

go work sync aligns go and toolchain directives across workspace modules
Bump the workspace go line before individual module bumps in a coordinated rollout
Remove stale use entries when modules are archived

Related: Major Milestones - workspaces landed in Go 1.18

10. Record Upgrade Decisions in an ADR

Capture what you tested and what you deferred.

## ADR: Adopt Go 1.26
 
### Context
Green Tea GC default; go fix modernizers; new(expr) for optional JSON fields.
 
### Decision
Upgrade staging week 1; production week 3 after p99 GC pause review.
 
### Rollback
Rebuild with GOEXPERIMENT=nogreenteagc; revert go.mod to go 1.25.0.

Link release-note sections to test evidence (benchmarks, canary metrics)
Note GODEBUG and GOEXPERIMENT overrides explicitly
Set a review date to remove temporary opt-outs

Related: Go History & Releases Best Practices - team habits for safe upgrades

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).

Go Releases Basics

Buscar en la documentación

Go Releases Basics