golang/proposal: The Repository for Go Language and API Change Proposals

What golang/proposal Is and How It Serves the Go Project

This repository holds two things: the process documentation for how the Go project evaluates proposed changes, and the design documents (as Markdown files in the design/ directory) that have been written for specific proposals. The README opens by stating that 'The Go project's development process is design-driven,' meaning that significant changes to the language, standard library, and tools require discussion and, sometimes, a written design before implementation can proceed.

The repository is not something developers clone to use Go itself. It is a coordination point for contributors who want to change Go, and a historical archive of why past decisions were made. The design/ folder contains proposals filed as issues on GitHub, each stored as a Markdown file named design/NNNN-shortname.md where NNNN is the GitHub issue number. The top-level entries also include CONTRIBUTING.md, a template for go2-language-changes.md, and the fill.el Emacs helper.

The Four-Step Review Process

The proposal process has four possible steps. The first is filing a GitHub issue with a brief description. The README emphasizes that no design document is needed at this stage. The second step is a discussion on the issue tracker, which aims to triage the proposal into one of three outcomes: accept it, decline it, or ask for a design document. If the proposal is accepted or declined at this stage, the process ends.

If a design document is requested, the author writes one to address the concerns raised in the initial discussion. This is the third step. The fourth step is a final discussion on the issue, again reaching either acceptance or declination.

After a proposal is accepted, implementation proceeds through the same contribution process as any other Go change. The process is designed, as the README states, to give proposals 'a proper, fair, timely, recorded evaluation with a clear answer,' and to make past proposals findable so that the same question is not raised multiple times without reference to the prior discussion.

Writing and Submitting a Design Document

Design documents live in the design/ directory of this repository as Markdown files. To submit one, clone the repository from its canonical location:

git clone https://go.googlesource.com/proposal

The README instructs contributors to follow the standard Gerrit workflow used across all Go contributions. Design documents should use the template at design/TEMPLATE.md. Formatting conventions include wrapping lines at the 80-column mark and starting each sentence on a new line, which the README explains makes comments more precise and diffs shorter. An Emacs helper for this formatting is included as fill.el at the repository root.

The README notes that new design document authors may be paired with a shepherd who helps develop the document. Comments on Gerrit CLs are restricted to grammar, spelling, and procedural issues; substantive feedback goes to the associated GitHub issue. This keeps the Gerrit review focused on document quality rather than design debate.

What Needs a Proposal and What Does Not

The README defines the scope of the proposal process explicitly. Changes that require a proposal include: API changes in the main Go repository and all golang.org/x repositories, command-line changes to the go command, any visible behavior change that needs a GODEBUG setting for compatibility, and adoption of new protocols or cryptographic algorithms.

Changes that do not require a proposal include: API changes in internal packages (which are not publicly visible), changes to golang.org/x/build (which is internal infrastructure), and additions of new system call numbers or direct system call wrappers in golang.org/x/sys with a clear one-to-one mapping from the Windows API. The README adds a practical note for uncertain cases: 'If in doubt, file a proposal.' Filing an issue costs little, and a non-proposal issue can be converted to a proposal simply by adding the proposal label.

Language Changes and Go 1 Compatibility

Language changes carry an additional constraint that applies to no other category: they must not break Go 1 compatibility. The README references the Go 1 compatibility document, which describes the promise that programs written for Go 1.x will continue to compile and work with future versions of Go 1. Any proposed language change must be evaluated against this promise first.

Language proposals should follow the go2-language-changes.md template and meet three criteria stated in the README: they must address an important issue for many people, have minimal impact on everyone else, and come with a clear and well-understood solution. The README links to a blog post about the Go 2 process and to the Go 2 review minutes and release notes as examples of language changes that have passed this bar.

This high bar is a deliberate constraint, not an oversight. The README reflects a project philosophy in which language stability is treated as a long-term commitment to every developer who has written Go code.

Python Enhancement Proposals as a Comparison

The Python programming language uses a similar process called Python Enhancement Proposals (PEPs). Both require a written proposal before significant language or standard library changes can proceed, and both use a multi-step review cycle with an explicit accept-or-decline outcome.

The substantive difference is tooling: Python PEPs are managed through GitHub pull requests on the peps repository, while Go's design documents go through Gerrit. Gerrit is the code review system used across all Go contributions, so using it for design documents keeps the toolchain consistent for Go contributors already familiar with the workflow. Python's GitHub-based approach is more accessible to contributors who work primarily on GitHub.

A second difference is granularity: Go's process applies to API changes in golang.org/x repositories, which are not part of the language specification itself. Python's PEP process focuses on the language and standard library, with a separate process for packaging ecosystem changes.

The README also links to three talks from GopherCon 2015 as background on Go's origins and development philosophy: 'How Go Was Made,' 'The Evolution of Go,' and 'Go, Open Source, Community.' These provide context for why the proposal process exists in its current form.

The repository is licensed under BSD-3-Clause. The last push was on 2026-08-07.

Editorial conclusion

Go contributors who want to propose a significant API change, language feature, or visible behavior change must follow the process documented here. Casual users of Go do not interact with this repository directly. The key step for anyone who has read this far is to file a GitHub issue in this repository before writing a design document: the README explicitly states there is no need for a design doc at the filing stage. The last push was on 2026-08-07, confirming the repository is active.

Frequently asked questions

Official sources

1. golang/proposal on GitHub
2. Issues
3. License: BSD-3-Clause
4. README