README.md - proposal - Git at Google

 # Proposing Changes to Go

 ## Introduction

 The Go project's development process is design-driven.
 Significant changes to the language, libraries, or tools 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](https://talks.golang.org/2015/how-go-was-made.slide),
 [The Evolution of Go](https://talks.golang.org/2015/gophercon-goevolution.slide),
 and [Go, Open Source, Community](https://blog.golang.org/open-source)
 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.

 1. The proposal author [creates a brief issue](https://golang.org/issue/new) 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.

 2. 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.

 3. The proposal author writes a [design doc](#design-documents) to work out details of the proposed
    design and address the concerns raised in the initial discussion.

 4. 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.
 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.

 ### 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](https://golang.org/doc/go1compat) 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](https://blog.golang.org/go2-here-we-come).
 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.

 (See the [release notes](https://golang.org/doc/devel/release.html) 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](https://github.com/golang/proposal/) 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](https://golang.org/doc/contribute.html#Code_review).

 - The design doc should follow [the template](design/TEMPLATE.md).

 - 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](http://rhodesmill.org/brandon/2012/one-sentence-per-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 procedural errors related to the preparation of the proposal itself.
 All other comments should be addressed to the related GitHub issue.


 ### Quick Start for Experienced Committers

 Experienced committers who are certain that a design doc will be
 required for a particular proposal
 can skip steps 1 and 2 and include the design doc with the initial issue.

 In the worst case, skipping these steps only leads to an unnecessary design doc.

 ### Proposal Review

 A group of Go team members holds “proposal review meetings”
 approximately weekly to review pending proposals.

 The principal goal of the review meeting is to make sure that proposals
 are receiving attention from the right people,
 by cc'ing relevant developers, raising important questions,
 pinging lapsed discussions, and generally trying to guide discussion
 toward agreement about the outcome.
 The discussion itself is expected to happen on the issue tracker,
 so that anyone can take part.

 The proposal review meetings also identify issues where
 consensus has been reached and the process can be
 advanced to the next step (by marking the proposal accepted
 or declined or by asking for a design doc).

 ### Consensus and Disagreement

 The goal of the proposal process is to reach general consensus about the outcome
 in a timely manner.

 If general consensus cannot be reached,
 the proposal review group decides the next step
 by reviewing and discussing the issue and
 reaching a consensus among themselves.
 If even consensus among the proposal review group
 cannot be reached (which would be exceedingly unusual),
 the arbiter ([rsc@](mailto:rsc@golang.org))
 reviews the discussion and
 decides the next step.

 ## Help

 If you need help with this process, please contact the Go contributors by posting
 to the [golang-dev mailing list](https://groups.google.com/group/golang-dev).
 (Note that the list is moderated, and that first-time posters should expect a
 delay while their message is held for moderation.)

 To learn about contributing to Go in general, see the
 [contribution guidelines](https://golang.org/doc/contribute.html).
	# Proposing Changes to Go

	## Introduction

	The Go project's development process is design-driven.
	Significant changes to the language, libraries, or tools 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](https://talks.golang.org/2015/how-go-was-made.slide),
	[The Evolution of Go](https://talks.golang.org/2015/gophercon-goevolution.slide),
	and [Go, Open Source, Community](https://blog.golang.org/open-source)
	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.

	1. The proposal author [creates a brief issue](https://golang.org/issue/new) 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.

	2. 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.

	3. The proposal author writes a [design doc](#design-documents) to work out details of the proposed
	design and address the concerns raised in the initial discussion.

	4. 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.
	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.

	### 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](https://golang.org/doc/go1compat) 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](https://blog.golang.org/go2-here-we-come).
	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.

	(See the [release notes](https://golang.org/doc/devel/release.html) 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](https://github.com/golang/proposal/) 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](https://golang.org/doc/contribute.html#Code_review).

	- The design doc should follow [the template](design/TEMPLATE.md).

	- 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](http://rhodesmill.org/brandon/2012/one-sentence-per-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 procedural errors related to the preparation of the proposal itself.
	All other comments should be addressed to the related GitHub issue.


	### Quick Start for Experienced Committers

	Experienced committers who are certain that a design doc will be
	required for a particular proposal
	can skip steps 1 and 2 and include the design doc with the initial issue.

	In the worst case, skipping these steps only leads to an unnecessary design doc.

	### Proposal Review

	A group of Go team members holds “proposal review meetings”
	approximately weekly to review pending proposals.

	The principal goal of the review meeting is to make sure that proposals
	are receiving attention from the right people,
	by cc'ing relevant developers, raising important questions,
	pinging lapsed discussions, and generally trying to guide discussion
	toward agreement about the outcome.
	The discussion itself is expected to happen on the issue tracker,
	so that anyone can take part.

	The proposal review meetings also identify issues where
	consensus has been reached and the process can be
	advanced to the next step (by marking the proposal accepted
	or declined or by asking for a design doc).

	### Consensus and Disagreement

	The goal of the proposal process is to reach general consensus about the outcome
	in a timely manner.

	If general consensus cannot be reached,
	the proposal review group decides the next step
	by reviewing and discussing the issue and
	reaching a consensus among themselves.
	If even consensus among the proposal review group
	cannot be reached (which would be exceedingly unusual),
	the arbiter ([rsc@](mailto:rsc@golang.org))
	reviews the discussion and
	decides the next step.

	## Help

	If you need help with this process, please contact the Go contributors by posting
	to the [golang-dev mailing list](https://groups.google.com/group/golang-dev).
	(Note that the list is moderated, and that first-time posters should expect a
	delay while their message is held for moderation.)

	To learn about contributing to Go in general, see the
	[contribution guidelines](https://golang.org/doc/contribute.html).