An excerpt from the repository, fetched Nov 13, 2026.
Read the project’s introduction
Proposing Changes to Go
Introduction
The Go project's development process is design-driven.
Significant changes to the language, libraries, or tools
(which includes API changes in the main repo and all golang.org/x repos,
as well as command-line changes to the go command)
must be first discussed, and sometimes formally documented,
before they can be implemented.
This document describes the process for proposing, documenting, and
implementing changes to the Go project.
To learn more about Go's origins and development process, see the talks
How Go Was Made,
The Evolution of Go,
and Go, Open Source, Community
from GopherCon 2015.
The Proposal Process
The proposal process is the process for reviewing a proposal and reaching
a decision about whether to accept or decline the proposal.
The proposal author creates a brief issue describing the proposal.
Note: There is no need for a design document at this point.
Note: A non-proposal issue can be turned into a proposal by simply adding the proposal label.
Note: Language changes should follow a separate template
A discussion on the issue tracker aims to triage the proposal into one of three outcomes:
Accept proposal, or
decline proposal, or
ask for a design doc.
If the proposal is accepted or declined, the process is done.
Otherwise the discussion is expected to identify concerns that
should be addressed in a more detailed design.
The proposal author writes a design doc to work out details of the proposed
design and address the concerns raised in the initial discussion.
Once comments and revisions on the design doc wind down, there is a final
discussion on the issue, to reach one of two outcomes:
Accept proposal or
decline proposal.
After the proposal is accepted or declined (whether after step 2 or step 4),
implementation work proceeds in the same way as any other contribution.
Detail
Goals
Make sure that proposals get a proper, fair, timely, recorded evaluation with
a clear answer.
Make past proposals easy to find, to avoid duplicated effort.
If a design doc is needed, make sure contributors know how to write a good one.
Definitions
A proposal is a suggestion filed as a GitHub issue, identified by having
the Proposal label.
A design doc is the expanded form of a proposal, written when the
proposal needs more careful explanation and consideration.
Scope
The proposal process should be used for any notable change or addition to the
language, libraries and tools.
“Notable” includes (but is not limited to):
API changes in the main repo and all golang.org/x repos.
Command-line changes to the go command.
Any visible behavior changes that need a GODEBUG setting for compatibility.
Any other visible behavior changes in existing functionality.
Adoption or use of new protocols, protocol versions, cryptographic algorithms, and the like,
even in an implementation.
Such changes are externally visible and require discussion and probably a GODEBUG setting.
Since proposals begin (and will often end) with the filing of an issue, even
small changes can go through the proposal process if appropriate.
Deciding what is appropriate is matter of judgment we will refine through
experience.
If in doubt, file a proposal.
There is a short list of changes that are typically not in scope for the proposal process:
Making API changes in internal packages, since those APIs are not publicly visible.
Making API or command-line changes in golang.org/x/build, since that is code to run the Go project, not for users to import and depend on.
Adding new system call numbers or direct system call wrappers (//sys lines)
in golang.org/x/sys. Additions to x/sys/windows with a clear 1:1 mapping from
the Windows API to the Go API can be accepted without proposal review.
Determining whether a change is a 1:1 mapping is up to the golang.org/x/sys/windows
maintainers. Any additional APIs, including methods on types that aren't
clearly reflected in the Windows API, must go through Go proposal review.
Adding new C-equivalent data structures to support those system calls.
Again, if in doubt, file a proposal.
Compatibility
Programs written for Go version 1.x must continue to compile and work with
future versions of Go 1.
The Go 1 compatibility document describes
the promise we have made to Go users for the future of Go 1.x.
Any proposed change must not break this promise.
Language changes
In 2018 we started a Go 2 process during which we may change the
language, as described on the Go
blog.
Language changes should follow the proposal process described here.
As explained in the blog entry, language change proposals should
address an important issue for many people,
have minimal impact on everybody else, and
come with a clear and well-understood solution.
Proposals should follow the Go 2 template.
See the Go 2 review minutes
and the release notes for
examples of recent language changes.
Design Documents
As noted above, some (but not all) proposals need to be elaborated in a design document.
The design doc should be checked in to the proposal repository as design/NNNN-shortname.md,
where NNNN is the GitHub issue number and shortname is a short name
(a few dash-separated words at most).
Clone this repository with git clone https://go.googlesource.com/proposal
and follow the usual Gerrit workflow for Go.
The design doc should follow the template.
The design doc should address any specific concerns raised during the initial discussion.
It is expected that the design doc may go through multiple checked-in revisions.
New design doc authors may be paired with a design doc "shepherd" to help work on the doc.
For ease of review with Gerrit, design documents should be wrapped around the
80 column mark.
Each sentence should start on a new line
so that comments can be made accurately and the diff kept shorter.
In Emacs, loading fill.el from this directory will make fill-paragraph format text this way.
Comments on Gerrit CLs should be restricted to grammar, spelling,
or proce
Read the full README on GitHub