The golang/proposal repository is a design-driven development process for the Go project that manages how significant changes to the language, libraries, and tools are proposed, reviewed, and decided upon.
The repository addresses the need to ensure that changes to Go receive proper, fair, and timely evaluation with clear outcomes while maintaining a searchable record to prevent duplicated effort. The approach is structured in stages: a proposal author first files a brief GitHub issue describing the change, the community discusses it to determine whether to accept, decline, or request a more detailed design document. If a design document is needed, the author expands the proposal to address concerns raised during initial discussion. Once comments wind down, a final discussion determines acceptance or rejection. After a decision is made, implementation proceeds as a standard contribution. This process applies to API changes in the main repository and golang.org/x repositories, command-line changes to the go command, visible behavior changes requiring GODEBUG settings for compatibility, and adoption of new protocols or cryptographic algorithms.
The proposal process is mandatory for notable changes, making it essential for anyone contributing significant features or modifications to Go. The repository serves both as a governance framework and as a historical archive of design decisions. It suits projects where stability and careful deliberation are priorities and where changes need community consensus before implementation begins. The README does not compare this approach to alternatives.
The project maintains a formal, documented process with clear templates and guidelines, including a separate template for language changes. Discussion and decision-making occur transparently on the issue tracker, creating a permanent record of the reasoning behind accepted and rejected proposals. The repository itself is primarily composed of HTML design documents that capture the detailed specifications and rationale for changes that have progressed through the proposal process.
