golang/proposal: how a design doc gets a change into Go

What golang/proposal actually is

This repository is the written record of how Go changes. The README states that the project's development process is design-driven: significant changes to the language, the libraries or the tools must be discussed, and sometimes formally documented, before they can be implemented. The scope is wider than the language. It covers API changes in the main Go repository and in every golang.org/x repository, command-line changes to the go command, and any visible behavior change that would need a GODEBUG setting for compatibility. Adoption of new protocols, protocol versions or cryptographic algorithms counts too, even when the change lives inside an implementation, because the README treats such changes as externally visible and therefore in need of discussion.

The audience is not Go users in general. It is the person who wants a change accepted into Go itself, plus the reviewers who have to decide. The repository holds the process description, the template for design documents, the separate template for language changes, and the checked-in design docs themselves under design/. The top level also carries CONTRIBUTING.md, LICENSE, PATENTS, codereview.cfg and fill.el. That last file is an Emacs helper, which tells you something about the age and the habits of the workflow.

The four-step proposal process

The README lays out a sequence with two possible exit points. First, the author creates a brief issue using the Go issue tracker, and the README is explicit that no design document is needed at this stage. A non-proposal issue can become a proposal by adding the proposal label. Second, discussion on the issue tracker triages the proposal into one of three outcomes: accept it, decline it, or ask for a design doc. If the answer is accept or decline, the process stops there.

If a design doc is requested, the author writes one to work out the details and address the concerns raised in the initial discussion. Then, once comments and revisions wind down, there is a final discussion on the issue with two possible outcomes: accept or decline. After either decision, implementation proceeds like any other contribution to Go.

The design of this process is worth noting. The cheap step comes first. A one-paragraph issue can be declined without anyone writing a document, which is the main defense against wasted effort. The expensive step, a full design doc, is only requested after a discussion has already identified specific concerns the document must answer. That is a deliberate ordering, and it means a proposal author who shows up with a finished design doc attached to the first issue has skipped a step the process expects them to take.

Writing and checking in a design document

The README gives concrete rules for the document itself. It should be checked in to this repository as design/NNNN-shortname.md, where NNNN is the GitHub issue number and shortname is a few dash-separated words at most. It should follow design/TEMPLATE.md and should address the specific concerns raised during the initial discussion. The README expects multiple checked-in revisions, and notes that new authors may be paired with a design doc shepherd to help.

Two formatting rules stand out. Documents should be wrapped around the 80 column mark, and each sentence should start on a new line so that comments can be made accurately and diffs stay short. The second rule is unusual outside Go and it exists for a reason: with one sentence per line, a reviewer can comment on a single sentence without the surrounding paragraph shifting. The repository ships fill.el so that Emacs users can make fill-paragraph produce that layout automatically.

There is also a rule about where comments go. Comments on Gerrit change lists should be restricted to grammar, spelling or procedural errors related to preparing the proposal. Everything else belongs on the GitHub issue. That split keeps the review tool for the document and the discussion tool for the design.

Cloning the repository and checking in a design doc

There is no package to install and no binary to run. The README gives one command for obtaining the repository, and it points at the go.googlesource.com mirror rather than GitHub:

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

After cloning you get design/, design/TEMPLATE.md, go2-language-changes.md, fill.el and the top-level files. The README says to follow the usual Gerrit workflow for Go when submitting, which is documented on go.dev rather than in this repository, so the pushing mechanics are not described here.

Your first real use is adding a document. The README fixes the path as design/NNNN-shortname.md, where NNNN is the GitHub issue number and shortname is a few dash-separated words at most, and says the doc should follow design/TEMPLATE.md. So you copy the template to a name built from your issue number, edit it, and commit:

git clone https://go.googlesource.com/proposal
cd proposal
cp design/TEMPLATE.md design/NNNN-shortname.md
git add design/NNNN-shortname.md
git commit -m "design/NNNN-shortname.md"

What you should see after this is a new file in design/ whose name matches an existing GitHub issue, because the README ties the file name to the issue number. If you do not have that issue number, you have started in the wrong place. The template is a starting point, not a form to fill in mechanically.

Where this process breaks down

The process assumes a proposal author who can navigate Gerrit, GitHub issues and a checked-in markdown document. Nothing in the README describes a simpler path for a first-time contributor, and the two-tool split (Gerrit for the document, GitHub for the discussion) means you are working in two systems with two comment conventions. The README states the convention; it does not offer tooling that enforces it.

The scope rules are also explicitly a judgment call. The README says that deciding what is appropriate is a matter of judgment that will be refined through experience, and it repeats the instruction to file a proposal if in doubt. That is honest, but it means you cannot resolve a borderline case from the document alone. There is a short list of things typically out of scope, including API changes in internal packages, changes in golang.org/x/build, and new system call numbers or direct syscall wrappers in golang.org/x/sys, with a narrow exception for x/sys/windows additions that map 1:1 to the Windows API. Determining whether a mapping is 1:1 is left to the x/sys/windows maintainers, so the boundary is decided by people, not by a rule you can apply yourself.

Finally, if your goal is to change your own program, this repository is the wrong tool entirely. It governs changes to Go, not changes made with Go.

golang/proposal against a plain GitHub pull request

The obvious alternative is the model most open source projects use: open a pull request against the code, discuss it in the review thread, and merge when the maintainers agree. The difference is not bureaucracy for its own sake. In a pull request review, the design and the implementation are argued at the same time, and the diff anchors the conversation. Here the design is argued first, in a separate document, and the implementation only follows after an accept decision. That ordering is what lets Go decline a change before anyone writes code, and it is what the README means when it says the process exists to give proposals a proper, fair, timely, recorded evaluation with a clear answer.

The cost is latency and ceremony. A pull request can be opened in a minute; a design doc has to be named after an issue, written against a template, wrapped at 80 columns, one sentence per line, and pushed through Gerrit. For a project that promises Go 1 compatibility, and states that any proposed change must not break that promise, the ceremony buys something a review thread does not: a durable, findable record. The README lists making past proposals easy to find, to avoid duplicated effort, as one of the process goals.

Maintenance, licensing and what to check before relying on it

The repository is not archived, and its last push was on 2026-08-07, so it is still being touched. That is a weak signal on its own: a process repository changes when the process changes or when a new design doc lands, not on a release cadence. The repository has no published GitHub releases, which fits a repository that ships documents rather than artifacts. There is no package to upgrade; cite a Git commit when you need a stable historical snapshot. Your upgrade cost is reading the README again before you submit, because the rules you follow are the ones currently checked in, not the ones you remember.

The licence is BSD-3-Clause, and the repository also carries a PATENTS file. Both apply to the repository contents. If you are writing a design doc that will be checked in here, the licence on your contribution is a question for the Go contribution process rather than something this description can settle.

What to verify first is narrow and concrete: open design/TEMPLATE.md and go2-language-changes.md and confirm which one applies to your change, since the README routes language changes to the Go 2 template and everything else to the general one.

Editorial conclusion

Use golang/proposal if you are proposing a change to the Go language, the standard library, golang.org/x packages or the go command, and read go2-language-changes.md before writing anything if the change touches the language. Do not clone it expecting a library: there is no package to import, and the repository exists to hold design documents and the process description. Before you write, verify two things in the repository itself: that design/TEMPLATE.md still matches the kind of document you plan to submit, and that the Gerrit workflow described in the README is the route your change will take rather than a GitHub pull request.

Frequently asked questions

Official sources

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