Release Notes Process
Purpose and Scope
This page explains how to think about release notes when contributing to the Go repository. Release notes are the public bridge between source changes and the stable Go distributions that users install from go.dev. They summarize what changed, call out compatibility-relevant behavior, and direct readers to the appropriate release or minor-revision context. The official release history presents each stable release as a distribution-level event, with major releases receiving release notes and supported releases receiving minor revisions for critical bug and security fixes. That public framing matters because contributors should write release-note material for users of the Go distribution, not only for reviewers reading an implementation change.
The Go repository is the source for the language implementation, standard library, command-line tools, and supporting build/test programs. The root README identifies the canonical repository, its GitHub mirror, the BSD-style license, official binary downloads, source installation entry point, and contribution guidelines. That makes it the repository-level orientation for anyone preparing a change that may need release-note coverage. Release-note work should start from the same first-party perspective: explain the user-visible effect, identify whether it affects a stable public surface, and avoid treating internal refactoring as a user-facing feature unless it changes observable behavior. Sources: README.md
Release notes are also tied to Go's compatibility promise and support window. The public release history says that a major release remains supported until there are two newer major releases, and that minor revisions are issued for critical problems, including critical security problems. For contributors, this means a note should distinguish between a new capability in the next major release, a behavior change relevant to migration, and a fix that users may see in a supported minor release. The audience is not limited to compiler engineers; it includes application developers, module authors, package maintainers, release managers, and platform teams deciding when to upgrade.
Relevant Source Files
- README.md - Repository-level orientation for the Go project, including canonical source location, mirror location, binary distribution link, source-installation link, contribution guidance, and issue-tracker guidance.
- misc/go_android_exec/main.go - Android execution wrapper used by the Go tool in builder/test contexts, showing that release-impacting work can involve platform support and test infrastructure as well as public package APIs.
- src/cmd/addr2line/main.go - Tool entry point for go tool addr2line, including usage text, pprof-oriented behavior, telemetry counters, and an explicit warning that the interface is intended only for pprof and may change.
- src/cmd/asm/main.go - Assembler command entry point, showing architecture selection, flag parsing, object-file emission, GOEXPERIMENT macro handling, and failure behavior that can become release-note material when user-visible.
- src/cmd/cgo/main.go - cgo command implementation data structures for Go files, C references, calls, exported functions, directives, and generated output, grounding release notes that affect cgo users.
- src/cmd/compile/internal/gc/main.go - Compiler main pipeline entry point, documenting flag parsing, panic handling, package setup, architecture initialization, GC tuning during compilation, and the high-level parse/type-check/compile/write flow.
Release Notes as a User-Facing Contract
A useful Go release note should answer the question a user asks after upgrading: what changed that affects my code, tools, builds, platforms, or operations? The source tree contains many layers, and not every change deserves a note. Internal cleanups, refactorings, and test-only changes usually do not need public documentation. A change is more likely to need release-note treatment when it affects the Go command, compiler diagnostics, assembler flags, cgo behavior, supported platforms, standard library APIs, runtime behavior, security posture, or documented workflows such as installing and building from source.
The root README makes clear that users normally obtain official binary distributions from go.dev/dl and use documented installation instructions, while contributors work through the contribution guidelines. That split is important for note writing. A release note is not a commit message and not a code-review checklist; it is a distribution note. It should describe the result once the change is part of a Go release. For example, if a tool changes only to support internal testing, a note may not be useful. If the same change affects cross-platform test execution, installation, or users invoking a command, it should be described in terms a Go user can act on. Sources: README.md
The representative command entry points show how broad the release-note surface can be. go tool addr2line is a small tool used by pprof, with documented input and output behavior and an explicit caveat that its interface is intended only for pprof and may change or be deleted. That kind of caveat changes the release-note standard: a user-facing note should not overpromise stability for an internal support tool, but it should still document visible changes if pprof workflows, profiling output, or tool invocation behavior are affected. Sources: src/cmd/addr2line/main.go
Toolchain notes should be written at the level of the public command or workflow. The assembler main function chooses the target architecture, parses flags, configures linker context fields, handles spectre settings, writes object-file headers, defines GOEXPERIMENT macros for runtime assembly, and removes the output file on failure. A change in any of those paths may be important if it changes accepted flags, generated object files, diagnostics, or supported architecture behavior. By contrast, moving helper code inside cmd/asm without changing the command contract should normally remain in the change description rather than the release notes. Sources: src/cmd/asm/main.go
Pairing API Changes with Notes
When a change adds, removes, or changes a public API, the release note and API review should reinforce each other. The API surface tells users what names exist and how to call them; the release note tells users why the addition matters, what problem it solves, and whether there are migration or compatibility implications. The official module release workflow uses version numbers to signal changes such as bug fixes, additions, and breaking changes. The Go distribution has its own release cadence, but the same communication principle applies: versioned releases should make the significance of user-visible changes clear.
For standard library or toolchain API changes, write the note from the package or command user's perspective. A compiler implementation change in src/cmd/compile/internal/gc/main.go may be technically about front-end processing, architecture initialization, package setup, or object emission, but the release note should discuss the visible outcome: a new diagnostic, different optimization behavior, build-time effect, generated code change, or language implementation support. The compiler main function itself describes the high-level pipeline as parsing flags and source files, type-checking the package, compiling functions to machine code, and writing the compiled package definition. That description is a good reminder to locate the user-visible stage before writing. Sources: src/cmd/compile/internal/gc/main.go
cgo changes often need especially careful notes because they sit at the boundary between Go source, C declarations, generated files, callbacks, exported functions, linker flags, and platform toolchains. The cgo source defines Package and File structures that collect package names, Go files, gcc output files, C references, calls, exported functions, preambles, noescape and nocallback directives, and accumulated names. A release note for cgo should name the affected directive, generated artifact, platform, or interoperability rule when possible. Avoid saying only that cgo was improved; explain whether users must change code, rebuild, adjust flags, or can expect better diagnostics. Sources: src/cmd/cgo/main.go
Contributor Workflow for Next-Release Documentation
Start by deciding whether the change is release-note worthy. Ask whether a user upgrading to the next Go release would need to know about it to understand new behavior, adopt a feature, avoid a surprise, or diagnose a regression. Changes to installation, source layout, supported platforms, command invocation, compiler behavior, cgo interoperability, profiling tools, security-sensitive packages, or standard library APIs usually deserve consideration. Changes that are purely internal may still matter if they alter performance, diagnostics, compatibility, or operational behavior users can observe.
Next, write the note in release-language rather than implementation-language. Name the affected component first, such as the compiler, cgo, go tool addr2line, the assembler, Android test execution, or the installation workflow. Then state the effect in present-tense user terms. If the change is guarded by a platform, architecture, experiment, flag, or build mode, include that condition. If there is no user action required, say what users may observe. If there is user action required, state the action directly and keep the explanation short enough to fit into release notes.
For changes that touch tests or builders, separate developer infrastructure from released behavior. The Android execution wrapper is used as go_android_GOARCH_exec by the Go tool and runs binaries on an Android device through adb. It serializes adb commands with a file lock, waits for boot completion, copies GOROOT to the device, creates temporary directories, and cleans them up. Those details are mostly infrastructure, but a release note may be appropriate if the supported Android testing workflow, builder reliability expectations, or platform support visible to users changes. Sources: misc/go_android_exec/main.go
Finally, coordinate the note with the code review. The Go README points contributors to the contribution guidelines and clarifies that the issue tracker is for bug reports and proposals, not general questions. In practice, that means release-note text should be reviewed alongside the implementation when the change is user-visible. Reviewers can check whether the note matches the actual behavior, whether it overstates stability, whether it belongs in a major-release note or a minor-release fix summary, and whether it needs an associated API entry or issue reference. Sources: README.md
System-to-Code Mapping
| Release-note area | What to document | Source signal |
|---|---|---|
| Distribution and contribution entry points | Where users get releases, where contributors start, and how the canonical repository relates to mirrors | README.md |
| Profiling support tools | Changes to addr2line invocation, input/output behavior, or pprof-facing behavior | src/cmd/addr2line/main.go |
| Assembly and architecture behavior | Flag, architecture, GOEXPERIMENT, object-file, or diagnostic changes visible to assembly users | src/cmd/asm/main.go |
| cgo interoperability | Directive, generated-code, exported-function, C reference, or platform compiler behavior changes | src/cmd/cgo/main.go |
| Compiler behavior | Flag parsing, diagnostics, frontend processing, type-checking, code generation, package output, or optimization changes | src/cmd/compile/internal/gc/main.go |
| Platform test execution | Android device execution, adb behavior, temporary test state, and builder-facing platform support | misc/go_android_exec/main.go |
Practical Checklist
Before sending or reviewing a change, use a compact checklist. Identify the component, identify the audience, decide whether the change is visible after installation, and classify it as feature, compatibility note, bug fix, security fix, platform note, tool note, or API addition. If the change adds a public name, the release note should explain the user problem solved by that name. If it changes behavior without adding an API, the note should say what users may see. If it affects a command, include the command name and any relevant flag, input, output, or supported workflow.
A good note should be specific but not overly tied to private implementation details. For example, instead of writing that a parser or linker context field changed, describe the assembler behavior that users experience. Instead of describing internal cgo maps or AST structures, describe the cgo directive or generated declaration affected. Instead of naming a compiler package only, name the build, diagnostic, optimization, or language behavior that changed. The source should remain the authority, but the note should remain durable for readers who do not know the repository internals.
Next Steps
If your change affects the Go distribution, read the public release history first so your note matches the way Go presents major releases and minor revisions. Then review the affected source path and write a short user-facing entry that names the component and outcome. For API additions, make sure the release-note text and API review tell a consistent story. For toolchain changes, verify the command's actual invocation, flags, output, and failure behavior in the relevant command source before finalizing the note.
Related pages: api-compatibility-checker, standard-library-api, toolchain-command-reference, compiler-architecture, module-release-workflow.