Language Design#

General#

• design/go0initial Rob Pike, Robert Griesemer, Ken Thompson. The Go Annotated Specification. Mar 3, 2008.
• design/go0spec0 The Go Programming Language. Language Specification. Mar 7, 2008.
• design/go0semicolon Rob Pike. Semicolons in Go. Dec 10, 2009.
• design/go11func Russ Cox. Go 1.1 Function Calls. February 2013
• design/go11return Russ Cox. Go “Return at End of Function” Requirements. March 2013
• design/go12nil Russ Cox. Go 1.2 Field Selectors and Nil Checks. July 2013.
• doc/go13todo Go 1.3 “To Do” List. Jun 1, 2014.
• doc/goatgoogle Rob Pike. Go at Google - Language Semantics. October 25, 2012.
• doc/makego Andrew Gerrand. How Go was Made. July 9, 2015.
• discuss/go1preview Russ Cox. Go 1 Preview. 2011.
• design/overlapping-interfaces Robert Griesemer. Proposal: Permit embedding of interfaces with overlapping method sets. Oct 16, 2019.
  • issue/6977 spec: allow embedding overlapping interfaces
• design/struct-conversion Robert Griesemer. Proposal: Ignore tags in struct type conversions. June 16, 2016.
  • issue/16085 Proposal: Ignore tags in struct type conversions
• design/go2trans Ian Lance Taylor. Proposal: Go 2 transition. October 15, 2018
• design/signed-int-shift Robert Griesemer. Proposal: Permit Signed Integers as Shift Counts for Go 2. January 17, 2019
  • issue/19113 proposal: spec: allow signed shift counts
• design/number-literal Russ Cox, Robert Griesemer. Proposal: Go 2 Number Literal Changes. March 6, 2019
  • issue/12711 proposal: different octal base literal representation
  • issue/19308 proposal: spec: binary integer literals
  • issue/28493 proposal: permit blank (_) separator in integer number literals
  • issue/29008 proposal: Go 2: hexadecimal floats
• discuss/delete-return why delete() doesn't return a bool ?
  • issue/5147 runtime: consider caching previous map hash value
  • issue/51405 proposal: Go 2: builtin: delete should return the deleted map item
• issue/33502 proposal: review meeting minutes
• issue/33892 proposal: Go 2 review meeting minutes
• issue/19623 proposal: spec: change int to be arbitrary precision
• design/unsafearithmetic Matthew Dempsky. Go 1.4: unsafe.Pointer arithmetic. Aug 2014.
• issue/19367 unsafe: add Slice(ptr *T, len anyIntegerType) []T
• issue/40481 unsafe: add Add function
• issue/53003 unsafe: add StringData, String, SliceData
• issue/43615 proposal: weak reference maps
• issue/48105 spec: clarify sequencing of function calls within expressions
• issue/56351 proposal: spec: add delete(m) to clear map
• issue/58233 proposal: spec: define return statement's result assignment order?
• issue/57616 proposal: spec: add simple string interpolation similar to Swift
• issue/57411 proposal: spec: define initialization order more precisely
• issue/56103 spec: disallow anonymous interface cycles
• issue/25448 spec: guarantee non-nil return value from recover
• issue/61372 proposal: spec: add untyped builtin zero
• issue/56351 spec: add clear(x) builtin, to clear map, zero content of slice
• issue/58625 unsafe: allow conversion of uintptr to unsafe.Pointer when it points to non-Go memory
• discuss/48305 doc comment revisions: headings, lists, and links
• issue/12445 spec: clarify how unsafe.Pointers may be used to determine offsets between addresses
• issue/45624 spec: expression to create pointer to simple types (new(expr) in Go 1.26)
• issue/46505 spec: allow conversion from slice to array
• issue/9859 spec: direct reference to embedded fields in struct literals

Slice (1.2)#

• design/read-only-slices Brad Fitzpatrick. Read-only slices. May 13, 2013
• design/read-only-slices-russ Russ Cox. Evaluation of read-only slices. May 2013.
• design/go12slice Russ Cox. Go Slice with Cap. June 2013.
• design/multidim-slice Brendan Tracey. Proposal: Multi-dimensional slices. November 17th, 2016.
• issue/41239 runtime: append growth sort of inconsistent and surprising
• discuss/why-slice-grow slices grow at 25% after 1024 but why 1024?
• cl/347917 runtime: make slice growth formula a bit smoother
  • doc/cl-347917-graph Graphs for CL 347917
• cl/418554 cmd/compile,runtime: redo growslice calling convention

Package Management (1.4, 1.5, 1.7)#

• design/go14internal Russ Cox. Go 1.4 “Internal” Packages. June 2014.
• design/go14nopkg Russ Cox. Go 1.4 src/pkg → src. June 2014.
• design/go14customimport Russ Cox. Go 1.4 Custom Import Path Checking. June 2014.
• design/go15vendor Russ Cox. Go 1.5 Vendor Experiment. July 2015
• design/go17binarypkg Russ Cox. Proposal: Binary-Only Packages. April 24, 2016
  • issue/2775 cmd/go: work when binaries are available but source is missing

Type alias (1.9)#

• design/type-alias Russ Cox, Robert Griesemer. Proposal: Type Aliases. December 16, 2016
  • talk/type-alias GopherCon 2016 - Lightning Talk: Robert Griesemer - Alias Declarations for Go, A proposal. Oct 9, 2016
  • issue/16339 proposal: Alias declarations for Go
  • issue/18130 all: support gradual code repair while moving a type between packages
• talk/refactor-video Russ Cox. Codebase Refactoring (with help from Go). GothamGo 2016. November 18, 2016.
  • doc/refactor Russ Cox. Codebase Refactoring (with help from Go).
• design/alias-decls Robert Griesemer & Rob Pike. Proposal: Alias declarations for Go. July 18, 2016.
• issue/76472 remove gotypesalias, asynctimerchan GODEBUG flag for 1.27
• issue/17487 cmd/compile: support alias
• issue/67547 go/types, types2: audit type assertions for potential Alias bugs
• issue/65294 x/tools: get tests passing with GODEBUG=gotypesalias=1
• doc/alias-names Robert Griesemer. What's in an (Alias) Name? September 17, 2024.

Defer (1.14)#

• design/open-defer Dan Scales, Keith Randall, and Austin Clements. Proposal: Low-cost defers through inline code, and extra funcdata to manage the panic case. 2019-09-23
  • issue/6980 cmd/compile: allocate some defers in stack frames
  • issue/14939 runtime: defer is slow #14939
• Unsolved defer recover() edge cases.
  • issue/10458 spec: panicking corner-case semantics
  • issue/23531 spec: recover() in nested defer
  • issue/26275 runtime: document the behaviour of Caller and Callers when used in deferred functions
  • issue/34530 spec: clarify when calling recover stops a panic
  • cl/189377 spec: specify the behavior of recover and recursive panics in more detail
• issue/34481 cmd/compile, runtime: a design for low-cost defers via inline code

Error values#

Error handling includes two separate works: error values and error formatting. Historically, there was a try proposal that had been investigated for a year, however, due to its lack of simplicity and impact to stack tracing, it was rejected. In 1.13, error values received a large revision, and the package errors includes different APIs, such as errors.Is. Until recently (1.21), #53435 allows wrapping multiple errors, and there is a community repository that tries to implement the original try proposal.

• doc/err2011 Andrew Gerrand. Error handling in Go. July 2011.
• doc/err-values Rob Pike. Errors are values. January 2015.
• doc/err-philosophy Dave Cheney. My philosophy for error handling. April 2016.
• doc/err-gracefully Dave Cheney. Don’t just check errors, handle them gracefully. April 2016.
• doc/err-stacktrace Dave Cheney. Stack traces and the errors package. June, 12 2016.
• doc/err-upspin Rob Pike. Error handling in Upspin. December 06, 2017.
• doc/err-work Damien Neil and Jonathan Amsterdam. Working with Errors in Go 1.13. October 17, 2019.
• design/err-handling-overview Russ Cox. Error Handling — Problem Overview.
• doc/err-value-faq Jonathan Amsterdam and Bryan C. Mills. Error Values: Frequently Asked Questions. August 2019.
• design/err-handle-check Marcel van Lohuizen. Error Handling — Draft Design. August 27, 2018.
• design/err-try Robert Griesemer. Proposal: A built-in Go error check function, "try". Jun 12, 2019.
  • issue/32437 Proposal: A built-in Go error check function, "try". Decision response.
• issue/71203 proposal: spec: reduce error handling boilerplate using ?
• design/err-inspect Jonathan Amsterdam, Damien Neil. Error Inspection — Draft Design. August 27, 2018.
• design/err-values-overview Russ Cox. Error Values — Problem Overview. August 27, 2018.
• design/error-values Jonathan Amsterdam, Russ Cox, Marcel van Lohuizen, Damien Neil. Proposal: Go 2 Error Inspection. January 25, 2019
  • issue/29934 Jonathan Amsterdam. proposal: Go 2 error values. Jan 25, 2019.
  • issue/29934-decision Damien Neil. Go 1.13 lunch decision about error values. May 6, 2019.
  • issue/29934-russ Russ Cox. Response, Response regarding "proposal: Go 2 error values". May 7, 2019.
• design/err-print Marcel van Lohuizen. Error Printing — Draft Design. August 27, 2018.
  • issue/30468 errors: performance regression in New.
• issue/40432 language: Go 2: error handling meta issue
• issue/40776 proposal: dynamic ignored error detector
• issue/41198 proposal: errors: add ErrUnimplemented as standard way for interface method to fail.
• issue/47811 proposal: errors: add Errors as a standard way to represent multiple errors as a single error
• issue/53435 proposal: wrapping multiple errors
• repo/try Try: Simplified Error Handling in Go
• discuss/71460 Ian Lance Taylor. discussion: spec: reduce error handling boilerplate using ? January 27, 2025.

Channel/Select#

• design/lockfree-channels Dmitry Vyukov. Go channels on steroids. Jan 28, 2014
  • issue/8899 runtime: lock-free channels
  • discuss/lockfree-channels update on "lock-free channels"
  • cl/112990043 runtime: fine-grained locking in select
  • cl/110580043 runtime: add fast paths to non-blocking channel operations
• issue/8898 runtime: special case timer channels
  • issue/61542 time: stop requiring Timer/Ticker.Stop for prompt GC
• issue/9120 runtime: remove implementation restriction on channel element size
• issue/37196 time: make Timer/Ticker channels not receivable with old values after Stop or Reset returns
• issue/8903 runtime: make chan-based generators faster.
• issue/21806 fairness in select statement.
• issue/40410 runtime: trim unnecessary fields from scase
• issue/40641 runtime: race between stack shrinking and channel send/recv leads to bad sudog values
• issue/37350 reflect: Select panics if array length greater than 1<<16
• doc/no-err-syntax Robert Griesemer. [ On | No ] syntactic support for error handling. June 2025.

Generics#

• doc/generics-discuss Summary of Go Generics Discussions
• doc/generics-dilemma Russ Cox. The Generic Dilemma. December 3, 2009.
• design/type-functions Ian Lance Taylor. Type Functions. June 2010.
• design/generalized-types Ian Lance Taylor. Generalized Types. March 2011.
• design/code-gen Russ Cox. Alternatives to Dynamic Code Generation in Go. September 2012.
• design/generalized-types2 Ian Lance Taylor. Generalized Types In Go. October 2013.
• design/type-parameters Ian Lance Taylor. Type Parameters in Go. December 2013.
• design/compile-time-function Bryan C. Mills. Compile-time Functions and First Class Types. September 2016.
• design/should-generics Ian Lance Taylor. Go should have generics. January 2011.
• design/should-generics2 Ian Lance Taylor. Go should have generics. Updated: April 2016.
  • issue/15292 proposal: spec: generic programming facilities
• design/generics-overview Russ Cox. Generics — Problem Overview. August 27, 2018.
• design/contracts Ian Lance Taylor, Robert Griesemer. Contracts — Draft Design. August 27, 2018, Updated: July 31, 2019.
  • cl/187317 Implementation prototype.
  • paper/featherweight-go Griesemer, Robert, et al. Featherweight Go. arXiv preprint arXiv:2005.11710 (2020).
  • talk/featherweight-go Phil Wadler: Featherweight Go. Jun 8, 2020.
• design/type-parameters2 Ian Lance Taylor, Robert Griesemer. Type Parameters - Draft Design. June 16, 2020, Updated: August 28, 2020.
  • cl/dev.go2go dev.go2go branch
  • doc/type-check-readme type checking.
  • doc/type-check-notes This file serves as a notebook/implementation log.
• discuss/generics-parenthesis Robert. Generics and parenthesis.
• discuss/generics-move Ian, Moving forward with the generics design.
• discuss/generics-implementation Implementing Generics
• design/generics-implementation-stenciling Generics implementation - Stenciling
• design/generics-implementation-dictionaries Generics implementation - Dictionaries
• design/generics-implementation-gcshape Generics implementation - GC Shape Stenciling
• design/generics-implementation-dictionaries-go1.18 Go 1.18 Implementation of Generics via Dictionaries and Gcshape Stenciling
• issue/43651 proposal: spec: add generic programming using type parameters
• design/type-parameters3 Type Parameters Proposal
• issue/45346 proposal: spec: generics: use type sets to remove type keyword in constraints
• issue/46477 proposal: spec: generics: type parameters on aliases
• issue/38907 proposal: spec: disallow impossible interface-interface type assertions
• discussion/48287 how to update APIs for generics
• Generics behavior
  • issue/48274 doc: update FAQ for the arrival of parametric polymorphism
  • issue/50202 spec: document that type parameters are not permitted as constant declaration types
  • issue/50272 spec: function type inference ignores type parameter constraints
  • issue/50954 go/types, types2: review error messages
  • issue/51110 spec: document behavior of type switches containing type parameter cases
  • any/comparable
    • issue/33232 spec: allow 'any' for 'interface{}' in non-constraint contexts
    • issue/46746 reflect: add Value.Equal, Value.Comparable
    • issue/49587 proposal: spec: add comparable w/o interfaces
    • issue/49927 builtin: add documentation for any and comparable to pseudo-package builtin
    • issue/49884 all: rewrite interface{} to any
    • issue/50646 spec: document/explain which interfaces implement comparable
    • issue/50646 spec: document definition of comparable
    • issue/51257 spec: any no longer implements comparable
    • issue/51338 proposal: spec: permit values to have type "comparable"
    • issue/52474 proposal: spec: permit non-interface types that support == to satisfy the comparable constraint
    • issue/52509 proposal: spec: allow interface types to instantiate comparable type parameters
    • issue/52531 proposal: spec: add new constraint kind satisfied by types that support == (including interface types)
    • issue/52614 proposal: type parameters are comparable unless they exclude comparable types
    • issue/52624 proposal: the comparable interface represents the comparable subset of run-time values
• Standard packages using generics
  • issue/45458 constraints: new package to define standard type parameter constraints
  • discuss/47319 proposal: constraints: new package to define standard type parameter constraints (discussion)
  • issue/45955 slices: new package to provide generic slice functions
  • discuss/47203 proposal: slices: new package to provide generic slice functions (discussion)
  • discuss/47331 proposal: container/set: new package to provide a generic set type (discussion)
  • discuss/47330 proposal: maps: new package to provide generic map functions (discussion)
  • issue/47649 maps: new package to provide generic map functions
  • issue/57436 maps: new standard library package based on x/exp/maps
  • issue/47657 proposal: sync, sync/atomic: add PoolOf, MapOf, ValueOf
  • issue/50792 constraints: move to x/exp for Go 1.18
  • issue/53427 proposal: x/sync/singleflight: add generic version
• Related packages
  • issue/47781 go/ast, go/token: additions to support type parameters
  • issue/47916 go/types: additions to support type parameters
  • issue/48525 x/tools/go/ssa: generics support
  • issue/50887 go/types, types2: document predicates on generic types
• issue/52654 spec: provide some way to refer to a generic function without instantiation
• issue/59488 cmp: new package with Ordered, Compare, Less; min, max as builtins
• issue/60648 cmp: document ordering for floating point values in cmp.Ordered
• issue/59531 all: ordering numeric values, including NaNs, and the consequences thereof
• issue/60519 math: remove Compare, Compare32
• issue/58650 spec: a general approach to type inference
• issue/59338 spec: infer type arguments from assignments of generic functions (reverse type inference)
• issue/58671 spec: type inference should be more lenient about untyped numeric literals
• issue/57644 proposal: spec: sum types based on general interfaces
• issue/70128 spec: remove notion of core types
  • issue/60994 proposal: go/types: add func CommonUnderlying(Type) Type, (formerly CoreType)
• issue/56548 spec: allow basic interface types to instantiate comparable type parameters
• design/parameterized-go-types Rob Findley, Robert Griesemer. Additions to go/types to support type parameters. 2021-08-17.
• issue/12854 spec: type inferred composite literals
  • issue/77245 spec: function type inference should work in all assignment contexts
• issue/61035 go/types, types2: fix SizesFor("gc", ...) to match actual gc behavior
• issue/52728 go/types: guarantee that a finite number of distinct instances are reachable via the API
• issue/57192 spec: interfaces that have different-size method sets never unify (but they possibly could)
• issue/63974 go/types, types2: switch to using go/version once we can use it in the compiler
• issue/51343 go/types, types2: simplify type-checking of method receivers with type parameters
• issue/55326 go/types, types2: remove discrepancy between type-checker and compiler error messages
• issue/54511 types2, go/types: share tests
• issue/69673 go/types: position-independent type checking
• issue/57410 cmd/compile: remove GOEXPERIMENT=nounified
• issue/68778 exportdata: support type parameterized aliases

• issue/60353 spec: when unifying against interface types, consider common methods
• issue/57433 slices: new standard library package based on x/exp/slices
• issue/51259 proposal: spec: support for struct members in interface/constraint syntax
• issue/50285 proposal: generic should infer type from variable definition
• issue/66651 proposal: spec: variadic type parameters
• issue/47796 types2, go/types: self-referential type parameter list is not accepted (allowed in Go 1.26)
  • issue/52190 proposal: generics: self referencing type constraints
• issue/75526 proposal: allow type parameters on methods (generic methods)
  • issue/77273 spec: generic methods for Go
• doc/comparable Robert Griesemer. All your comparable types. February 17, 2023.
• doc/deconstructing-type-parameters Ian Lance Taylor. Deconstructing Type Parameters. September 26, 2023.
• doc/type-inference Robert Griesemer. Everything You Always Wanted to Know About Type Inference - And a Little Bit More. October 9, 2023.
• doc/generic-slice-functions Valentin Deleplace. Robust generic functions on slices. February 22, 2024.
• doc/coretypes Robert Griesemer. Goodbye core types - Hello Go as we know and love it! March 26, 2025.
• doc/generic-interfaces Axel Wagner. Generic interfaces. July 7, 2025.
• issue/75883 spec: remove cycle restriction for type parameters
• doc/type-construction Mark Freeman. Type Construction and Cycle Detection. March 24, 2026.
• doc/generic-methods Mark Freeman. Generic Methods. August 26, 2026.
• talk/axel2024 Axel Wagner. Advanced Generics Patterns. GopherCon 2024, Chicago. July 2024.

Iterator#

• issue/24282 proposal: Go 2: improve for-loop ergonomics
• issue/40605 proposal: Go 2: iterators
• issue/43557 proposal: Go 2: function values as iterators
• issue/47707 proposal: Go 2: spec: for range with defined types
• issue/48567 proposal: use channels as iterators
• issue/50112 proposal: package collection and iterator design for go
• issue/54047 proposal: Go 2: add a new iterator syntax, package, interfaces
• discuss/54245 discussion: standard iterator interface
• issue/20733 proposal: spec: redefine range loop variables in each iteration
• issue/56010 redefining for loop variable semantics
• issue/60078 spec: less error-prone loop variable scoping
• discuss/56413 user-defined iteration using range over func values
• issue/61405 proposal: spec: add range over int, range over func
• doc/coro Coroutines for Go
• doc/undefined-behavior C and C++ Prioritize Performance over Correctness
• issue/54650 x/exp/slices: memory leak on Delete
• issue/66455 proposal: errors: add All and AllAs iterators
• issue/61898 proposal: x/exp/xiter: new package with iterator adapters
• issue/65236 spec: allow range-over-func to omit iteration variables
• issue/61899 slices: add iterator-related functions
• issue/61897 iter: new package for iterators
• issue/61900 maps: add iterator-related functions
• issue/61901 bytes, strings: add iterator forms of existing functions
• issue/65237 spec: document range-over-func
• design/loopvar Proposal: Less Error-Prone Loop Variable Scoping.
• issue/57969 cmd/compile: add GOEXPERIMENT=loopvar
• issue/61717 cmd/compile: add new range behind GOEXPERIMENT=range
• doc/loopvar-preview David Chase and Russ Cox. Fixing For Loops in Go 1.22. September 19, 2023.
• doc/range-functions Ian Lance Taylor. Range Over Function Types. August 20, 2024.
• issue/61902 regexp: add iterator forms of matching methods

Compatibility#

• doc/go1compat Go 1 and the Future of Go Programs
• discussion/55090 extending Go backward compatibility
  • issue/56986 extended backwards compatibility for Go
  • design/godebug Proposal: Extended backwards compatibility for Go
• discussion/55092 extending Go forward compatibility
  • issue/57001 extended forwards compatibility for Go
  • design/gotoolchain Proposal: Extended forwards compatibility in Go
• issue/33791 proposal: add explicit decision doc for large changes
• issue/28221 cmd/go, cmd/compile: record language version to support language transitions
• issue/31793 go/types, types2: provide configuration support for different language versions
• doc/compat Russ Cox. Backward Compatibility, Go 1.21, and Go 2. August 14, 2023.
• doc/toolchain Russ Cox. Forward Compatibility and Toolchain Management in Go 1.21. August 14, 2023.
• issue/65573 cmd/go: separate default GODEBUGs from go language version
• issue/76163 policy for removing GODEBUG flags
• discuss/80580 Austin Clements. a more robust proposal process. July 27, 2026.