cybercyst/go
1
0
Fork 0
mirror of https://github.com/golang/go.git synced 2025-05-05 15:43:04 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

wiki: redirect everything to go.dev/wiki 

For #61940.
Russ Cox 2023-12-14 22:14:45 -05:00
parent b527141b0d
commit b0657ab84c
161 changed files with 339 additions and 24459 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

287
AVX512.md

@ -1,287 +1,4 @@
Go 1.11 release introduces [AVX-512](https://en.wikipedia.org/wiki/AVX-512) support. The Go wiki on GitHub has moved to go.dev (#61940).
This page describes how to use new features as well as some important encoder details.
### Terminology Try <https://go.dev/wiki/AVX512> or <https://go.dev/wiki/>.
Most terminology comes from [Intel Software Developer's manual](https://software.intel.com/en-us/articles/intel-sdm).
Suffixes originate from Go assembler syntax, which is close to AT&T, which also uses size suffixes.
Some terms are listed to avoid ambiguity (for example, opcode can have different meanings).
<table>
<tr>
<th>Term</th>
<th>Description</th>
</tr>
<tr>
<td>Operand</td>
<td>
Same as "instruction argument".
</td>
</tr>
<tr>
<td>Opcode</td>
<td>
Name that refers to instruction group. For example, <code>VADDPD</code> is an opcode.<br>
It refers to both VEX and EVEX encoded forms and all operand combinations.<br>
Most Go assembler opcodes for AVX-512 match Intel manual entries, with exceptions for cases<br>
where additional size suffix is used (e.g. <code>VCVTTPD2DQY</code> is <code>VCVTTPD2DQ</code>).
</td>
</tr>
<tr>
<td>Opcode suffix</td>
<td>
Suffix that overrides some opcode properties. Listed after "." (dot).<br>
For example, <code>VADDPD.Z</code> has "Z" opcode suffix.<br>
There can be multiple dot-separated opcode suffixes.
</td>
</tr>
<tr>
<td>Size suffix</td>
<td>
Suffix that specifies instruction operand size if it can't be inferred from operands alone.<br>
For example, <code>VCVTSS2USIL</code> has "L" size suffix.
</td>
</tr>
<tr>
<td>Opmask</td>
<td>
Used for both <code>{k1}</code> notation and to describe instructions that have <code>K</code> registers operands.<br>
Related to masking support in EVEX prefix.
</td>
</tr>
<tr>
<td>Register block</td>
<td>
Multi-source operand that encodes register range.<br>
Intel manual uses <code>+n</code> notation for register blocks.<br>
For example, <code>+3</code> is a register block of 4 registers.
</td>
</tr>
<tr>
<td>FP</td>
<td>Floating-point</td>
</tr>
</table>
### New registers
EVEX-enabled instructions can access additional 16 `X` (128-bit xmm) and `Y` (256-bit ymm) registers, plus 32 new `Z` (512-bit zmm) registers in 64-bit mode. 32-bit mode only gets `Z0-Z7`.
New opmask registers are named `K0-K7`.
They can be used for both masking and for special opmask instructions (like `KADDB`).
### Masking support
Instructions that support masking can omit `K` register operand.
In this case, `K0` register is implied ("all ones") and merging-masking is performed.
This is effectively "no masking".
`K1-K7` registers can be used to override default opmask.
`K` register should be placed right before destination operand.
Zeroing-masking can be activated with `Z` opcode suffix. Zeroing-masking requires that a mask register other than K0 be specified.
For example, `VADDPD.Z (AX), Z30, K3, Z10` uses zeroing-masking and explicit `K` register.
- If `Z` opcode suffix is removed, it's merging-masking with `K3` mask.
- If `K3` operand is removed, it generates an assembler error.
- If both `Z` opcode suffix and `K3` operand are removed, it is merging-masking with `K0` mask.
It's compile-time error to use `K0` register for `{k1}` operands (consult [manuals](https://software.intel.com/en-us/articles/intel-sdm) for details).
### EVEX broadcast/rounding/SAE support
Embedded broadcast, rounding and SAE activated through opcode suffixes.
For reg-reg FP instructions with `{er}` enabled, rounding opcode suffix can be specified:
* `RU_SAE` to round towards +Inf
* `RD_SAE` to round towards -Inf
* `RZ_SAE` to round towards zero
* `RN_SAE` to round towards nearest
> To read more about rounding modes, see [MXCSR.RC info](http://qcd.phys.cmu.edu/QCDcluster/intel/vtune/reference/vc148.htm).
For reg-reg FP instructions with `{sae}` enabled, exception suppression can be specified with `SAE` opcode suffix.
For reg-mem instrictons with `m32bcst/m64bcst` operand, broadcasting can be turned on with `BCST` opcode suffix.
Zeroing opcode suffix can be combined with any of these.
For example, `VMAXPD.SAE.Z Z3, Z2, Z1` uses both `Z` and `SAE` opcode suffixes.
It is important to put zeroing opcode suffix last, otherwise it is a compilation error.
### Register block (multi-source) operands
Register blocks are specified using register range syntax.
It would be enough to specify just first (low) register, but Go assembler requires
explicit range with both ends for readability reasons.
For example, instructions with `+3` range can be used like `VP4DPWSSD Z25, [Z0-Z3], (AX)`.
Range `[Z0-Z3]` reads like "register block of Z0, Z1, Z2, Z3".
Invalid ranges result in compilation error.
### AVX1 and AVX2 instructions with EVEX prefix
Previously existed opcodes that can be encoded using EVEX prefix now can access AVX-512 features like wider register file, zeroing/merging masking, etc. For example, `VADDPD` can now use 512-bit vector registers.
See [encoder details](#encoder-details) for more info.
### Supported extensions
Best way to get up-to-date list of supported extensions is to do `ls -1` inside [test suite](https://github.com/golang/go/tree/master/src/cmd/asm/internal/asm/testdata/avx512enc) directory.
Latest list includes:
```
aes_avx512f
avx512_4fmaps
avx512_4vnniw
avx512_bitalg
avx512_ifma
avx512_vbmi
avx512_vbmi2
avx512_vnni
avx512_vpopcntdq
avx512bw
avx512cd
avx512dq
avx512er
avx512f
avx512pf
gfni_avx512f
vpclmulqdq_avx512f
```
128-bit and 256-bit instructions additionally require `avx512vl`.
That is, if `VADDPD` is available in `avx512f`, you can't use `X` and `Y` arguments
without `avx512vl`.
Filenames follow `GNU as` (gas) conventions.
[avx512extmap.csv](https://gist.github.com/Quasilyte/92321dadcc3f86b05c1aeda2c13c851f) can make naming scheme more apparent.
### Instructions with size suffix
Some opcodes do not match Intel manual entries.
This section is provided for search convenience.
| Intel opcode | Go assembler opcodes |
|--------------|----------------------|
| `VCVTPD2DQ` | `VCVTPD2DQX`, `VCVTPD2DQY` |
| `VCVTPD2PS` | `VCVTPD2PSX`, `VCVTPD2PSY` |
| `VCVTTPD2DQ` | `VCVTTPD2DQX`, `VCVTTPD2DQY` |
| `VCVTQQ2PS` | `VCVTQQ2PSX`, `VCVTQQ2PSY` |
| `VCVTUQQ2PS` | `VCVTUQQ2PSX`, `VCVTUQQ2PSY` |
| `VCVTPD2UDQ` | `VCVTPD2UDQX`, `VCVTPD2UDQY` |
| `VCVTTPD2UDQ` | `VCVTTPD2UDQX`, `VCVTTPD2UDQY` |
| `VFPCLASSPD` | `VFPCLASSPDX`, `VFPCLASSPDY`, `VFPCLASSPDZ` |
| `VFPCLASSPS` | `VFPCLASSPSX`, `VFPCLASSPSY`, `VFPCLASSPSZ` |
| `VCVTSD2SI` | `VCVTSD2SI`, `VCVTSD2SIQ` |
| `VCVTTSD2SI` | `VCVTSD2SI`, `VCVTSD2SIQ` |
| `VCVTTSS2SI` | `VCVTSD2SI`, `VCVTSD2SIQ` |
| `VCVTSS2SI` | `VCVTSD2SI`, `VCVTSD2SIQ` |
| `VCVTSD2USI` | `VCVTSD2USIL`, `VCVTSD2USIQ` |
| `VCVTSS2USI` | `VCVTSS2USIL`, `VCVTSS2USIQ` |
| `VCVTTSD2USI` | `VCVTTSD2USIL`, `VCVTTSD2USIQ` |
| `VCVTTSS2USI` | `VCVTTSS2USIL`, `VCVTTSS2USIQ` |
| `VCVTUSI2SD` | `VCVTUSI2SDL`, `VCVTUSI2SDQ` |
| `VCVTUSI2SS` | `VCVTUSI2SSL`, `VCVTUSI2SSQ` |
| `VCVTSI2SD` | `VCVTSI2SDL`, `VCVTSI2SDQ` |
| `VCVTSI2SS` | `VCVTSI2SSL`, `VCVTSI2SSQ` |
| `ANDN` | `ANDNL`, `ANDNQ` |
| `BEXTR` | `BEXTRL`, `BEXTRQ` |
| `BLSI` | `BLSIL`, `BLSIQ` |
| `BLSMSK` | `BLSMSKL`, `BLSMSKQ` |
| `BLSR` | `BLSRL`, `BLSRQ` |
| `BZHI` | `BZHIL`, `BZHIQ` |
| `MULX` | `MULXL`, `MULXQ` |
| `PDEP` | `PDEPL`, `PDEPQ` |
| `PEXT` | `PEXTL`, `PEXTQ` |
| `RORX` | `RORXL`, `RORXQ` |
| `SARX` | `SARXL`, `SARXQ` |
| `SHLX` | `SHLXL`, `SHLXQ` |
| `SHRX` | `SHRXL`, `SHRXQ` |
### Encoder details
Bitwise comparison with older encoder may fail for VEX-encoded instructions due to slightly different encoder tables order.
This difference may arise for instructions with both `{reg, reg/mem}` and `{reg/mem, reg}` forms for reg-reg case. One of such instructions is `VMOVUPS`.
This does not affect code behavior, nor makes it bigger/less efficient.
New encoding selection scheme is borrowed from [Intel XED](https://github.com/intelxed/xed).
EVEX encoding is used when any of the following is true:
* Instruction uses new registers (High 16 `X`/`Y`, `Z` or `K` registers)
* Instruction uses EVEX-related opcode suffixes like `BCST`
* Instruction uses operands combination that is only available for AVX-512
In all other cases VEX encoding is used.
This means that VEX is used whenever possible, and EVEX whenever required.
Compressed disp8 is applied whenever possible for EVEX-encoded instructions.
This also covers broadcasting disp8 which sometimes has different N multiplier.
Experienced readers can inspect [avx_optabs.go](https://github.com/golang/go/blob/master/src/cmd/internal/obj/x86/avx_optabs.go) to learn about N multipliers for any instruction.
For example, `VADDPD` has these:
* `N=64` for 512-bit form; `N=8` when broadcasting
* `N=32` for 256-bit form; `N=8` when broadcasting
* `N=16` for 128-bit form; `N=8` when broadcasting
### Examples
Exhaustive amount of examples can be found in Go assembler [test suite](https://github.com/golang/go/tree/master/src/cmd/asm/internal/asm/testdata/avx512enc).
Each file provides several examples for every supported instruction form in particular AVX-512 extension.
Every example also includes generated machine code.
Here is adopted "Vectorized Histogram Update Using AVX-512CD" from
[Intel® Optimization Manual](https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-optimization-manual.pdf):
```go
for i := 0; i < 512; i++ {
histo[key[i]] += 1
}
```
```asm
top:
VMOVUPS 0x40(SP)(DX*4), Z4 //; vmovups zmm4, [rsp+rdx*4+0x40]
VPXORD Z1, Z1, Z1 //; vpxord zmm1, zmm1, zmm1
KMOVW K1, K2 //; kmovw k2, k1
VPCONFLICTD Z4, Z2 //; vpconflictd zmm2, zmm4
VPGATHERDD (AX)(Z4*4), K2, Z1 //; vpgatherdd zmm1{k2}, [rax+zmm4*4]
VPTESTMD histo<>(SB), Z2, K0 //; vptestmd k0, zmm2, [rip+0x185c]
KMOVW K0, CX //; kmovw ecx, k0
VPADDD Z0, Z1, Z3 //; vpaddd zmm3, zmm1, zmm0
TESTL CX, CX //; test ecx, ecx
JZ noConflicts //; jz noConflicts
VMOVUPS histo<>(SB), Z1 //; vmovups zmm1, [rip+0x1884]
VPTESTMD histo<>(SB), Z2, K0 //; vptestmd k0, zmm2, [rip+0x18ba]
VPLZCNTD Z2, Z5 //; vplzcntd zmm5, zmm2
XORB BX, BX //; xor bl, bl
KMOVW K0, CX //; kmovw ecx, k0
VPSUBD Z5, Z1, Z1 //; vpsubd zmm1, zmm1, zmm5
VPSUBD Z5, Z1, Z1 //; vpsubd zmm1, zmm1, zmm5
resolveConflicts:
VPBROADCASTD CX, Z5 //; vpbroadcastd zmm5, ecx
KMOVW CX, K2 //; kmovw k2, ecx
VPERMD Z3, Z1, K2, Z3 //; vpermd zmm3{k2}, zmm1, zmm3
VPADDD Z0, Z3, K2, Z3 //; vpaddd zmm3{k2}, zmm3, zmm0
VPTESTMD Z2, Z5, K2, K0 //; vptestmd k0{k2}, zmm5, zmm2
KMOVW K0, SI //; kmovw esi, k0
ANDL SI, CX //; and ecx, esi
JZ noConflicts //; jz noConflicts
ADDB $1, BX //; add bl, 0x1
CMPB BX, $16 //; cmp bl, 0x10
JB resolveConflicts //; jb resolveConflicts
noConflicts:
KMOVW K1, K2 //; kmovw k2, k1
VPSCATTERDD Z3, K2, (AX)(Z4*4) //; vpscatterdd [rax+zmm4*4]{k2}, zmm3
ADDL $16, DX //; add edx, 0x10
CMPL DX, $1024 //; cmp edx, 0x400
JB top //; jb top
```

264
Articles.md

@ -1,264 +1,4 @@
The Go wiki on GitHub has moved to go.dev (#61940).
Please keep all entries in reverse chronological order (most recent first) Try <https://go.dev/wiki/Articles> or <https://go.dev/wiki/>.
Table of Contents
=================
* [Indexes](#article-indexes)
* [General](#general)
* [Concurrency / Channels](#concurrency--channels)
* [Containers & Docker](#containers--docker)
* [Cross Platform Development](#cross-platform-development)
* [Error Handling](#error-handling)
* [Interfaces / OOP](#interfaces--oop)
* [Mobile Applications](#mobile-applications)
* [Modules](#modules)
* [Performance and Profiling](#performance-and-profiling)
* [Pointers/References/Memory](#pointers-references-and-memory-management)
* [Reflection](#reflection)
* [Security](#security)
* [Testing](#testing)
* [Web & API Development](#web--api-development)
* [Misc](#misc)
* [Chinese](#chinese)
* [Czech](#czech)
* [German](#german)
* [Japanese](#japanese)
* [Korean](#korean)
## Article Indexes
* [Collection of #golang posts on Medium](https://medium.com/tag/golang) _latest_
* [Go articles from Dr. Dobbs](http://www.drdobbs.com/sitesearch?sort=publishDate+desc&queryText=golang&type=site) _latest_
* [Slideshare Collection of #golang presentations](http://www.slideshare.net/search/slideshow?searchfrom=header&q=golang&ud=any&ft=all&lang=**&sort=) _latest_
* [Short Go tutorials on SocketLoop](https://www.socketloop.com/tagsearch/golang) _latest_
* [An Introduction to Go](https://tutorialedge.net/course/golang/) _latest_
## General
* [Darker Corners of Go](https://rytisbiel.com/2021/03/06/darker-corners-of-go/) _2021-03-13_
* [Working with Golang Maps](https://www.loginradius.com/engineering/blog/working-with-go-maps/) _2020-09-25_
* [Practical Go: Real world advice for writing maintainable Go programs](https://dave.cheney.net/practical-go/presentations/gophercon-singapore-2019.html) _2019-05-01_
* [Here are some amazing advantages of Go that you don’t hear much about](https://www.freecodecamp.org/news/here-are-some-amazing-advantages-of-go-that-you-dont-hear-much-about-1af99de3b23a/) _2018-02-01_
* [Go Defer Simplified with Practical Visuals](https://blog.learngoprogramming.com/golang-defer-simplified-77d3b2b817ff) _2017-11-23_
* [The Zoo of Go Funcs](https://blog.learngoprogramming.com/go-functions-overview-anonymous-closures-higher-order-deferred-concurrent-6799008dde7b) _2017-11-09_
* [Ultimate Guide to Go Variadic Functions](https://blog.learngoprogramming.com/golang-variadic-funcs-how-to-patterns-369408f19085) _2017-11-02_
* [Go Funcs-Baby Gopher's Visual Guide](https://blog.learngoprogramming.com/golang-funcs-params-named-result-values-types-pass-by-value-67f4374d9c0a) _2017-10-27_
* [Ultimate Visual Guide to Go Enums](https://blog.learngoprogramming.com/golang-const-type-enums-iota-bc4befd096d3) _2017-10-19_
* [Learn Go Constants](https://blog.learngoprogramming.com/learn-golang-typed-untyped-constants-70b4df443b61) _2017-10-10_
* [Learn Go Variables](https://blog.learngoprogramming.com/learn-go-lang-variables-visual-tutorial-and-ebook-9a061d29babe) _2017-10-04_
* [Introduction to Go Packages](https://blog.learngoprogramming.com/definitive-guide-to-go-packages-focus-on-the-fundamentals-to-empower-your-skills-d14aae7cd321) _2017-09-26_
* [About Go Language — An Overview](https://blog.learngoprogramming.com/about-go-language-an-overview-f0bee143597c) _2017-09-20_
* [Debugging code generation in Go](https://rakyll.org/codegen/) _2016-10-15_
* [Go tooling essentials](https://rakyll.org/go-tool-flags/) _2016-09-25_
* [Go from PHP engineer's perspective](http://sobit.me/2016/02/25/go-from-php-engineers-perspective/) _2016-02-25_
* [Go Proverbs, Illustrated](http://www.gregosuri.com/2015/12/04/go-proverbs-illustrated/) _2015-12-04_
* [A whirlwind tour of Go’s runtime environment variables](http://dave.cheney.net/2015/11/29/a-whirlwind-tour-of-gos-runtime-environment-variables) _2015-11-29_
* [Idiomatic Doc Comments: Document your function, not your function signature](http://whipperstacker.com/2015/10/14/idiomatic-doc-comments-document-your-function-not-your-function-signature/) _2015-10_14_
* [Best Practices for a new Go Developer](https://medium.com/@IndianGuru/best-practices-for-a-new-go-developer-8660384302fc) _2015-09-01_
* [Golang Refactoring Tools](http://blog.ralch.com/tutorial/golang-tools-refactoring/) _2015-08-30_
* [Working with Files in Go](http://www.devdungeon.com/content/working-files-go) _2015-08-23_
* [Defer Fun](https://blog.klauspost.com/defer-fun/) _2015-07-25_
* [Things I learned teaching Go - Francesc Campoy](https://medium.com/@francesc/dotgo-things-i-learned-teaching-go-e999f33298cf) _2014-11-24_
* [Understanding Go Packages](http://thenewstack.io/understanding-golang-packages/) _2014-11-01_
* [Structuring Applications in Go](https://medium.com/@benbjohnson/structuring-applications-in-go-3b04be4ff091#.kj6eym1u4) _2014-06-06_
* [Functional Options for Friendly APIs](http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis) _2014-10-17_
* [Go Programming for Beginners](http://thenewstack.io/the-new-stack-intros-go-programming-for-beginners/) _2014-10-01_
* [Switching from Python to Go](https://www.spacemonkey.com/blog/posts/go-space-monkey) _2014-04-21_
* [Google Go: The Good, the Bad, and the Meh](http://blog.carlsensei.com/post/42828735125) _2013-02-10_
* [What I Love About Go](http://npf.io/2013/01/what-i-love-about-go) _2013-01-25_
* [Why I program in Go](http://tech.t9i.in/2013/01/why-program-in-go/) _2013-01-05_
* [Go: A New Language for a New Year](http://kylelemons.net/2012/01/go-new-language-new-year/) _2012-01-06_
* [Why you PHP guys should learn Golang](http://www.mikespook.com/2012/08/why-you-php-guys-should-learn-golang/) _2012-08-10_
* [Why I went from Python to Go (and not node.js)](http://jordanorelli.tumblr.com/post/31533769172/why-i-went-from-python-to-go-and-not-node-js) _2012-09-14_
* [How and Why to Write Enums in Go](https://blog.boot.dev/golang/golang-enum/) _2021-04-19_
## Concurrency / Channels
* [Learning Go concurrency through illustrations](https://medium.com/@trevor4e/learning-gos-concurrency-through-illustrations-8c4aff603b3) _2018-06-21_
* [Using contexts to avoid leaking goroutines](https://rakyll.org/leakingctx/) _2016-10-25_
* [Concurrency in Go](http://www.minaandrawos.com/2015/12/06/concurrency-in-golang/) _2015-12-06_
* [Very basic concurrency for beginners in Go](https://medium.com/@matryer/very-basic-concurrency-for-beginners-in-go-663e63c6ba07#.n831uhdiq) _2015-11-18_
* [Exploting Powerful Cloud Services with Go](https://medium.com/@sathishvj/exploiting-your-powerful-cloud-servers-with-go-lang-s-concurrency-eae5f4c7526) _2015-10-11_
* [Golang lock-free values with atomic.Value](https://texlution.com/post/golang-lock-free-values-with-atomic-value/) _2015-08-21_
* [Golang Pearl: Thread-safe writes and double checked locking in Go](http://blog.launchdarkly.com/golang-pearl-thread-safe-writes-and-double-checked-locking-in-go/) _2015-07-21_
* [Golang: Funny Play with Channel](http://www.mikespook.com/2012/05/golang-funny-play-with-channel/) _2012-05-25_
* [Unlimited Buffering with Low Overhead](http://rogpeppe.wordpress.com/2010/02/10/unlimited-buffering-with-low-overhead/) _2010-02-10_
* [Concurrent Idioms #1: Broadcasting values in Go with linked channels](http://rogpeppe.wordpress.com/2009/12/01/concurrent-idioms-1-broadcasting-values-in-go-with-linked-channels/) _2009-12-01_
## Containers & Docker
* [Deploying a Go app to a minimal Docker container](http://www.giantflyingsaucer.com/blog/?p=5720) _2015-10-01_
* [Fetching a remote configuration using Docker and Consul](http://www.giantflyingsaucer.com/blog/?p=5701) _2015-09-30_
* [Joining the Docker Ship and Go](http://thenewstack.io/make-a-restful-json-api-go/) _2015-07-01_
* [Building Minimal Docker Images for Go](http://blog.codeship.com/building-minimal-docker-containers-for-go-applications/) _2015-04-23_
## Cross-Platform Development
* [Releasing cross-platform Go binaries using Goxc and BinTray in 5 minutes](http://jbu.io/2015/11/29/releasing-cross-platform-go-binaries-using-goxc-and-bintray-in-5-minutes/) _2015-11-29_
* [Calling Go from Swift](https://rakyll.org/swift/) _2015-10-3_
* [On Go, portability, and system interfaces](http://garrett.damore.org/2015/09/on-go-portability-and-system-interfaces.html) _2015-09-22_
* [Go cross compilation](https://rakyll.org/cross-compilation/) _2015-09-8_
## Error Handling
* [Returning Errors](https://npf.io/2015/10/errors/) _2015-10-10_
* [Inspecting Errors](http://dave.cheney.net/2014/12/24/inspecting-errors) _2014-12-24_
## Interfaces / OOP
* [Generics in Golang with Code Generation](http://blog.ralch.com/tutorial/golang-code-generation-and-generics/) _2015-10-18_
* [Composition with Go](http://www.goinggo.net/2015/09/composition-with-go.html) _2015-09-13_
* [Sorting Inventory Items in Go - the sort.Interface](https://adampresley.github.io/2015/09/06/sorting-inventory-items-in-go.html) _2015-09-06_
* [Loose Coupling in Go Lang](https://blog.8thlight.com/javier-saldana/2015/02/06/loose-coupling-in-go-lang.html) _2015-02-06_
* [How to use interfaces in Go](http://jordanorelli.tumblr.com/post/32665860244/how-to-use-interfaces-in-go) _2012-10-01_
* [Go Object Oriented Design](http://nathany.com/good) _2013-01-14_
* [It is ridiculously easy to refactor Go](http://www.onebigfluke.com/2013/01/it-is-ridiculously-easy-to-refactor-go.html) _2013-01-27_
* [Functional Iteration in Go](http://hackthology.com/functional-iteration-in-go.html) _2013-12-13_
* [Interfaces in Go - Russ Cox](http://research.swtch.com/interfaces) _2009-12-01_
## Mobile Applications
Start by reading the [overview of mobile development](Mobile) documentation first.
* [Go Mobile: Next generation of mobile apps](https://www.linkedin.com/pulse/go-mobile-next-generation-apps-daniele-baroncelli) _2015-09-18_
* [iOS Apps with Go - Video by Josh Deprez](https://www.youtube.com/watch?v=bftMhhMIJNo) _2015-09-17_
* [5 Part Series - Mobile Go](https://medium.com/using-go-in-mobile-apps) _2015-01-08_
## Modules
* [Introduction to Go Modules](https://roberto.selbach.ca/intro-to-go-modules/) _2018-08-18_
## Performance and Profiling
* [Mutex profile](https://rakyll.org/mutexprofile/) _2016-12-19_
* [How to Optimize Garbage Collection in Go](http://www.cockroachlabs.com/blog/how-to-optimize-garbage-collection-in-go/) _2015-11-23_
* [Golang Escape Analysis](http://www.agardner.me/golang/garbage/collection/gc/escape/analysis/2015/10/18/go-escape-analysis.html) _2015-10-18_
* [A Pattern for Optimizing Go](http://blog.signalfx.com/a-pattern-for-optimizing-go) _2015-09-24_
* [Golang Performance Tips](https://joshrendek.com/2015/09/golang-performance-tips/) _2015-09-20_
* [Answering your own (performance) questions in Go](http://www.sanarias.com/blog/915LearningtoansweryourownquestionsinGo) _2015-09-15_
* [Concise Guide to profiling go programs](https://medium.com/@tjholowaychuk/profiling-golang-851db2d9ae24) _2014-08-09_
* [Go Performance Observations](http://hashrocket.com/blog/posts/go-performance-observations) _2014-08-07_
* [Debugging performance issues in Go programs - Intel](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs) _2014-05-10_
* [How to write benchmarks in Go](http://dave.cheney.net/2013/06/30/how-to-write-benchmarks-in-go) _2013-06-30_
* [Profiling Go Programs - Go blog](https://go.dev/blog/profiling-go-programs) _2011-06-24_
## Pointers, References and Memory Management
* [Equality and Type Aliases](https://akutz.wordpress.com/2015/09/02/golang-equality-and-type-aliases/) _2015-09-02_
* [Pointers vs References](http://spf13.com/post/go-pointers-vs-references/) _2014-06-01_
* [Recycling Memory Buffers in Go](https://blog.cloudflare.com/recycling-memory-buffers-in-go/) _2013-08-24_
* [Learning Go Types](http://www.laktek.com/2012/01/27/learning-go-types/) _2012-01-27_
* [Saving a Third of Our Memory by Re-ordering Go Struct Fields](https://wagslane.dev/posts/go-struct-ordering/) _2020-08-07_
## Reflection
* [Go Reflection Index](https://jimmyfrasche.github.io/go-reflection-codex/) by Jimmy Frasche _2014-01-26_
## Security
* [Mutual TLS authentication in Go](http://www.levigross.com/2015/11/21/mutual-tls-authentication-in-go/) _2015-11-21_
* [Whispered Secrets - The case for building software with privacy as a primary concern](http://www.slideshare.net/feyeleanor/whispered-secrets-52966860) _2015-09-19_
## Testing
* [Getting Started with BDD in Go Using Ginkgo](https://semaphoreci.com/community/tutorials/getting-started-with-bdd-in-go-using-ginkgo) _2016-07-12_
* [Integration testing in Go using Docker](https://divan.github.io/posts/integration_testing/) _2015-12-07_
* [Debugging Go Programs with Delve](https://blog.gopheracademy.com/advent-2015/debugging-with-delve/) _2015-12-03_
* [Upgrade Your Appengine Tests with Testify](http://csfortheslothful.blogspot.com/2015/11/upgrade-your-appengine-tests-with.html) _2015_11_21_
## Web & API Development
Start by reading the [overview of server programming](LearnServerProgramming) documentation first.
* [Get started with Go and WebAssembly](https://medium.com/@sendilkumarn/getting-started-into-go-and-webassembly-8491b133a616) _2018-08-14_
* [HTTP/2 Server Push](https://rakyll.org/http2push/) _2016-12-10_
* [Preventing Cross-Site Request Forgery in Go](https://elithrar.github.io/article/preventing-csrf-attacks-in-go/) _2015-12-14_
* [goa: Untangling Microservices](https://blog.gopheracademy.com/advent-2015/goaUntanglingMicroservices/) _2015-12-07_
* [A Weekend with Go, Beego and React](http://foreman-shlomizadok.rhcloud.com/2015/11/03/a-weekend-with-go-lang-beego-react/) _2015-11-03_
* [HTTP Session Handling on Heroku](https://devcenter.heroku.com/articles/go-sessions) _2015-09-09_
* [Go Resiliency Patterns](https://github.com/eapache/go-resiliency) _2015-09-01_
* [http.Handler and Error Handling in Go](https://elithrar.github.io/article/http-handler-error-handling-revisited/) _2015-07-02_
* [Deploy a golang photo archive tool to the cloud on IBM BlueMix](http://www.ibm.com/developerworks/cloud/library/cl-golang-photo-archive-bluemix/index.html) _2015-06-05_
* [A Journey into Microservices - Part 1](https://sudo.hailoapp.com/services/2015/03/09/journey-into-a-microservice-world-part-1/), [Part 2](https://sudo.hailoapp.com/services/2015/03/09/journey-into-a-microservice-world-part-2/), [Part 3](https://sudo.hailoapp.com/services/2015/03/09/journey-into-a-microservice-world-part-3/) _2015-03_09_
* [Making a RESTful JSON API in Go](http://thenewstack.io/make-a-restful-json-api-go/) _2015-01-01_
* [Building a Web Server in Go](http://thenewstack.io/building-a-web-server-in-go/) _2014-09-01_
* [The Ultimate Guide to JSON in Go](https://blog.boot.dev/golang/json-golang/) _2021-04-28_
## Misc
* [Environment variables in Golang](https://www.loginradius.com/engineering/blog/environment-variables-in-golang/) _2020-09-28_
* [Using MongoDB as Datasource in GoLang](https://www.loginradius.com/blog/engineering/mongodb-as-datasource-in-golang/) _2020-09-21_
* [Go-powered Open Source IoT Integration Framework "Flogo"](http://www.kai-waehner.de/blog/2016/11/03/open-source-project-flogo-overview/) _2016-11-07_
* [Build Slack Slash Commands with Go](http://www.programmableweb.com/news/how-to-use-slack-api-to-build-slash-commands-powered-google-app-engine-and-go/how-to/2015/09/16) _2015-09-15_
* [String Matching by Damian Gryski](http://blog.gopheracademy.com/advent-2014/string-matching/) _2014-12-05_
* [State machines in Go (#golang)](http://denis.papathanasiou.org/?p=1190) _2013-02-10_
* [Go & Assembly](http://www.doxsey.net/blog/go-and-assembly) _2013-02-05_
* [Function Types in Go (golang)](http://jordanorelli.tumblr.com/post/42369331748/function-types-in-go-golang) _2013-02-05_
* [Optimizing Real World Go](http://bpowers.github.com/weblog/2013/01/05/optimizing-real-world-go/) _2013-01-05_
* [Methods as Objects in Go](http://ernestmicklei.com/2012/11/26/methods-as-objects-in-go/) _2012-12-26_
* [Applying The Clean Architecture to Go applications](http://manuel.kiessling.net/2012/09/28/applying-the-clean-architecture-to-go-applications/) _2012-09-08_
* [An introduction to cross compilation with Go](http://dave.cheney.net/2012/09/08/an-introduction-to-cross-compilation-with-go) _2012-09-08_
* [Function Call by Name in Golang](http://www.mikespook.com/2012/07/function-call-by-name-in-golang/) _2012-07-05_
* [Using the Go Regexp Package](http://blog.kamilkisiel.net/blog/2012/07/05/using-the-go-regexp-package/) _2012-07-05_
* [Zero Downtime upgrades of TCP servers in Go](http://blog.nella.org/?p=879) _2012-05-29_
* [Go Reflection Codex](http://jimmyfrasche.github.io/go-reflection-codex/)
* [Go JSON Marshalling and Unmarshalling cheatsheet](https://eager.io/blog/go-and-json/) _2015-09-30_
## Chinese
* [Test Go module](http://chenxiaoyu.org/2012/12/07/golang-module-test-benchmark.html)
* [Build web application with golang](https://github.com/astaxie/build-web-application-with-golang)
* [Go语言评估报告](https://docs.google.com/document/d/1NosYIbM6tfBqKh49BrHOngBfXuT1MfrvYXwc_ikwuMk/edit)
* [Why you PHP guys should learn Golang](http://www.mikespook.com/2012/08/%e4%b8%ba%e4%bb%80%e4%b9%88phper%e5%ba%94%e5%bd%93%e5%ad%a6%e4%b9%a0golang/)
* [Function Call by Name in Golang](http://www.mikespook.com/2012/07/%e5%9c%a8-golang-%e4%b8%ad%e7%94%a8%e5%90%8d%e5%ad%97%e8%b0%83%e7%94%a8%e5%87%bd%e6%95%b0/)
* [Golang: Funny Play with Channel](http://www.mikespook.com/2012/06/golang-channel-%e6%9c%89%e8%b6%a3%e7%9a%84%e5%ba%94%e7%94%a8/)
* [Using MyMySQL - A interface of database/sql](http://www.mikespook.com/2012/05/mymysql-%e7%9a%84-databasesql-%e6%8e%a5%e5%8f%a3%e4%bd%bf%e7%94%a8/)
* [Go did What on the Stack?](http://www.mikespook.com/2011/03/go%e5%9c%a8stack%e4%b8%8a%e5%b9%b2%e4%ba%86%e7%a5%9e%e9%a9%ac%ef%bc%9f/)
* [Gobs on the wire (Translation)](http://www.mikespook.com/2011/03/%e7%bf%bb%e8%af%91%e9%a3%9e%e7%bf%94%e7%9a%84-gob/)
* [Go Environment Setup (Translation)](http://www.mikespook.com/2012/02/%E7%BF%BB%E8%AF%91go-%E7%8E%AF%E5%A2%83%E8%AE%BE%E7%BD%AE/)
* [Error Handling and Go (Translation)](http://www.mikespook.com/2011/08/%E9%94%99%E8%AF%AF%E5%A4%84%E7%90%86%E5%92%8Cgo/)
* [The Go Tool (Translation)](http://www.mikespook.com/2012/02/%E7%BF%BB%E8%AF%91go-%E5%B7%A5%E5%85%B7/)
* [Less is exponentially more (Translation)](http://www.mikespook.com/2012/06/%E7%BF%BB%E8%AF%91%E5%B0%91%E6%98%AF%E6%8C%87%E6%95%B0%E7%BA%A7%E7%9A%84%E5%A4%9A/)
* [Zero Downtime upgrades of TCP servers in Go (Translation)](http://www.mikespook.com/2012/05/%E7%BF%BB%E8%AF%91%E7%94%A8-go-%E5%AE%9E%E7%8E%B0%E9%9B%B6%E5%81%9C%E6%9C%BA%E5%8D%87%E7%BA%A7-tcp-%E6%9C%8D%E5%8A%A1/)
* [Using Go Modules (Translation)](https://www.4async.com/2019/03/2019-03-20-using-go-modules/)
## Czech
* [Google Go - 1st birthday](http://www.abclinuxu.cz/clanky/google-go-1.-narozeniny)
* [Google Go - what we find in the kit](http://www.abclinuxu.cz/clanky/google-go-co-najdeme-ve-stavebnici)
* [Google Go - advanced topics](http://www.abclinuxu.cz/clanky/google-go-pokrocilejsi-temata)
* [Google Go by examples I.](http://www.abclinuxu.cz/clanky/google-go-v-prikladech-1)
* [Google Go by examples II.](http://www.abclinuxu.cz/clanky/google-go-v-prikladech-2)
* [Error handling in Go](http://www.abclinuxu.cz/clanky/osetrovani-chyb-v-go)
* [Google Go - The Laws of Reflection](http://www.abclinuxu.cz/clanky/google-go-pravidla-reflexe)
* [Google Go - 2nd birthday](http://www.abclinuxu.cz/clanky/google-go-2.-narozeniny)
## German
* [Programmiersprachen im Multicore Zeitalter - Google GO und Nebenläufigkeit](http://ps.informatik.uni-siegen.de/downloads/Seminare/multicore-ws2011/donner.pdf) ` [PDF] ` _2012-02-02_
## Japanese
* [WindowsでGo言語のまとめ](http://esten.wankuma.com/)
* [Go言語で jQuery ライクな操作が出来る goquery を試した。](http://mattn.kaoriya.net/software/lang/go/20120914184828.htm)
* [Go言語向けの ORM、gorp がなかなか良い](http://mattn.kaoriya.net/software/lang/go/20120914222828.htm)
* [GAE/GでGoogle Cloud Storageを利用するには（１）](http://takashi-yokoyama.blogspot.jp/2012/08/gaeggoogle-cloud-storage.html)
* [Go言語のWebフレームワーク"goweb"をGAE/Gで動かす](http://takashi-yokoyama.blogspot.jp/2012/07/gowebgowebgaeg.html)
* [Ubuntu 12.04にgolangを”ソースから”インストールする。](http://takashi-yokoyama.blogspot.jp/2012/07/ubuntu-1204golang.html)
* [GAE/Gで時間のチェック（Datastore編）](http://takashi-yokoyama.blogspot.jp/2012/06/gaegdatastore.html)
## Korean
* [The Go Programming Language](http://www.slideshare.net/golanger/abou-go)
* [You can read Go code](http://goo.gl/vUeSzl)
* [Go channel tutorial](http://blog.sabzil.org/2014/12/golang-channels-tutorial)
* [Go character encoding](http://www.slideshare.net/suapapa/go-character-encoding)
* [Using Google API in Go](http://www.slideshare.net/golanger/using-google-api-in-go)
* [Go로 Git 들여다보기](http://goo.gl/nCDV3I)
* [Go: 90% 완벽?!, 100% of the time 슬라이드 번역 ](http://100coding.com/go/slide)
* [Go 동시성 패턴 advanced 영상 번역](http://www.youtube.com/watch?v=4g2skln42eo)
* [Go + Revel + Gorp 간단 게시판 만들기](http://100coding.com/go/tutorial/1)
* [Go + Revel + Gorm 으로 만드는 블로그](https://github.com/jaehue/goblog/wiki/Hello-World)

15
AssemblyPolicy.md

@ -1,15 +1,4 @@
This document describes when and how to add assembly code to the Go cryptography packages. The Go wiki on GitHub has moved to go.dev (#61940).
In general, the rules are: Try <https://go.dev/wiki/AssemblyPolicy> or <https://go.dev/wiki/>.
* We prefer portable Go, not assembly. Code in assembly means (N packages * M architectures) to maintain, rather than just N packages.
* Minimize use of assembly. We'd rather have a small amount of assembly for a 50% speedup rather than twice as much assembly for a 55% speedup. Explain the decision to place the assembly/Go boundary where it is in the commit message, and support it with benchmarks.
* Use higher level programs to generate non-trivial amounts of assembly, either standalone Go programs or `go get`-able programs, like [avo](https://github.com/mmcloughlin/avo). Output of other reproducible processes (like formally verified code generators) will also be considered. Discuss the implementation strategy on the issue tracker in advance.
* Use small, testable units (25–75 lines) called from higher-level logic written in Go. If using small, testable functions called from logic written in Go is too slow, use small, testable assembly units with Go-compatible wrappers, so that Go tests can still test the individual units.
* Any assembly function needs a reference Go implementation, that’s tested side-by-side with the assembly. Follow [golang.org/wiki/TargetSpecific](https://go.dev/wiki/TargetSpecific) for structure and testing practices.
* The interface of the assembly units and of the reference Go implementation must be the same across architectures, unless the platforms have fundamentally different capabilities (such as high-level cryptographic instructions).
* Unless the Go Security team explicitly commits to owning the specific implementation, an external contributor must commit to maintaining it. If changes are required (for example as part of a broader refactor) and the maintainer is not available, the assembly will be removed.
* The code must be tested in our CI. This means there need to be builders that support the instructions, and if there are multiple (or fallback) paths they must be tested separately. (Tip: use `GODEBUG=cpu.X=off` to disable detection of CPU features.)
* Document in the Go code why the implementation requires assembly (specific performance benefit, access to instructions, etc), so we can reevaluate as the compiler improves.
Not all assembly currently in the standard library adheres to this policy. Changes to existing assembly will be discouraged until that implementation is updated to be compliant. New assembly must be compliant.

67
Benchmarks.md

@ -1,67 +1,4 @@
These are benchmarks collected from the community used to measure the effects of changes to the Go core (compiler, runtime, garbage collector, and libraries). They should have the following properties: The Go wiki on GitHub has moved to go.dev (#61940).
- they matter; someone cares, perhaps in a dollars-and-cents way, that they run well Try <https://go.dev/wiki/Benchmarks> or <https://go.dev/wiki/>.
- they are go-gettable and don't require customized steps for building the benchmark
- they run under `go test -bench ...`
- they run relatively quickly, ideally a single "run" takes less than a second (there should perhaps be a separate set of longer-running benchmarks)
- their timings are not gratuitously noisy
- they run cleanly in a restricted environment, such as a Docker or rkt container
- they're not gratuitously redundant with other benchmarks already in the list; we don't need ten microbenchmarks of Go transcendental functions
**These benchmarks change over time, and that is okay.** Their intended use is for performance testing of proposed changes; is the geometric mean better, were any benchmarks made substantially worse?
Information for each benchmark includes (or should include):
- a short name for the benchmark
- the path to `go get` the benchmark
- a regexp for the benchmark suite excluding individual benchmarks that might be noisy, long-running, or redundant
- (ideally) a contact person for questions about the benchmarks
| short name | notes | go get path | benchmark regexp | contact |
| ---------- | ----- | ----------- | ---------------- | ------- |
| ajstarks_deck_generate | | `github.com/ajstarks/deck/generate` | `Benchmark(Polygon\|Arc)` | |
| benhoyt_goawk | | `github.com/benhoyt/goawk/interp` | `BenchmarkR` | |
| bindata | | `github.com/kevinburke/go-bindata` | `Benchmark` | |
| capnproto2 | | `zombiezen.com/go/capnproto2/` | `Benchmark(TextMovementBetweenSegments\|Growth_MultiSegment)` | |
| cespare_mph | | `github.com/cespare/mph` | `BenchmarkBuild` | |
| cespare_xxhash | | `github.com/cespare/xxhash` | `BenchmarkHashes/xxhash-string,n=10_MB` | |
| ericlagergren_decimal | | `github.com/ericlagergren/decimal/benchmarks` | `BenchmarkPi_decimal_Go_9` | |
| ethereum_bitutil | | `github.com/ethereum/go-ethereum/common/bitutil` | `Benchmark(BaseTest2KB\|FastTest2KB\|Encoding4KBVerySparse)` | |
| ethereum_core | | `github.com/ethereum/go-ethereum/core` | `BenchmarkChainRead_full_10k` | |
| ethereum_corevm | | `github.com/ethereum/go-ethereum/core/vm` | `BenchmarkOpDiv128` | |
| ethereum_ecies | | `github.com/ethereum/go-ethereum/crypto/ecies` | `BenchmarkGenSharedKeyP256` | |
| ethereum_ethash | | `github.com/ethereum/go-ethereum/consensus/ethash` | `BenchmarkHashimotoLight` | |
| ethereum_sha3 | | `github.com/ethereum/go-ethereum/crypto/sha3` | `BenchmarkSha3_224_MTU` | |
| ethereum_storage | | `github.com/ethereum/go-ethereum/swarm/storage` | `BenchmarkJoin_8` | |
| ethereum_trie | | `github.com/ethereum/go-ethereum/trie` | `Benchmark` | |
| gonum_blas_native | | `gonum.org/v1/gonum/blas/gonum` | `Benchmark(DasumMediumUnitaryInc\|Dnrm2MediumPosInc)` | |
| gonum_community | | `gonum.org/v1/gonum/graph/community/` | `BenchmarkLouvainDirectedMultiplex` | |
| gonum_lapack_native | | `gonum.org/v1/gonum/lapack/gonum` | `BenchmarkDgeev/Circulant10` | |
| gonum_mat | | `gonum.org/v1/gonum/mat` | `Benchmark(MulWorkspaceDense1000Hundredth\|ScaleVec10000Inc20)` | |
| gonum_path | | `gonum.org/v1/gonum/graph/path/` | `Benchmark(AStarUndirectedmallWorld_10_2_2_2_Heur\|Dominators/nested_if_n256)` | |
| gonum_topo | | `gonum.org/v1/gonum/graph/topo/` | `Benchmark(TarjanSCCGnp_1000_half\|TarjanSCCGnp_10_tenth)` | |
| gonum_traverse | | `gonum.org/v1/gonum/graph/traverse/` | `BenchmarkWalkAllBreadthFirstGnp_(10\|1000)_tenth` | |
| gtank_blake2s | | `github.com/gtank/blake2s` | `BenchmarkHash8K` | |
| gtank_ed25519 | | `github.com/gtank/ed25519` | `Benchmark(IsOnCurve\|ScalarMult)` | |
| hugo_helpers | | `github.com/gohugoio/hugo/helpers` | `Benchmark(StripHTML\|ReaderContains)` | |
| hugo_hugolib | | `github.com/gohugoio/hugo/hugolib` | `BenchmarkParsePage` | |
| hugo_hugolib_sitebuilding | | `github.com/gohugoio/hugo/hugolib` | `BenchmarkSiteBuilding/YAML,num_pages=10,num_tags=10,tags_per_page=20,shortcodes,render-12` | |
| k8s_api | | `k8s.io/kubernetes/pkg/api/testing` | `BenchmarkEncodeCodecFromInternalProtobuf` | |
| k8s_schedulercache | | `k8s.io/kubernetes/pkg/scheduler/cache` | `BenchmarkList1kNodes30kPods` | |
| minio | | `github.com/minio/minio/cmd` | `BenchmarkGetObject5MbFS` | |
| nelsam_gxui_interval | | `github.com/nelsam/gxui/interval` | `Benchmark` | |
| pilosa_bitmaps | benchmarks in `roaring/` subdirectory | `github.com/pilosa/pilosa` | `BenchmarkBitmap_IntersectionCount` | jaffee@pilosa.com |
| semver | | `github.com/Masterminds/semver` | `BenchmarkValidateVersionTildeFail` | |
| spexs2 | | `github.com/egonelbre/spexs2/_benchmark/` | `BenchmarkRun/10k/1` | |
| uber_zap | | `go.uber.org/zap/benchmarks` | `BenchmarkAddingFields/(Zap.Sugar\|^[ais])` | |
| uuid | | `github.com/satori/go.uuid/` | `Benchmark(NewV5\|MarshalToString)` | |
There is a [benchmark runner](https://github.com/dr2chase/bent) that automates downloading, building, and running these benchmarks under various (user-defined) configurations. Benchmarking noise on Linux can be somewhat reduced with [perflock](https://github.com/aclements/perflock).
A few have been proposed but have so far failed to make the cut (for fetch, build, or noise problems):
| short name | notes | go get path | benchmark regexp | contact |
| ---------- | ----- | ----------- | ---------------- | ------- |
| eolian_dsp | | `buddin.us/eolian/dsp` | `Benchmark` | |
| ethereum_whisperv5 | | `github.com/ethereum/go-ethereum/whisper/whisperv5` | `Benchmark` | |
| kanzi | | `github.com/flanglet/kanzi/go/src/kanzi/benchmark` | `Benchmark` | |

86
Blogs.md

@ -1,86 +1,4 @@
A set of blogs dedicated to Go. The Go wiki on GitHub has moved to go.dev (#61940).
NOTE: Please don't add individual blog entries to this page. Those belong in [articles](Articles) instead. Try <https://go.dev/wiki/Blogs> or <https://go.dev/wiki/>.
## Arabic
* [لغة غو بالعربي](https://argolang.com) - موقع عربي مخصص للغة البرمجة غو
## English
* [The official Go Blog](https://go.dev/blog) - For in depth posts by the Go team
* [Gopher Academy Blog](http://blog.gopheracademy.com/)
* [Dave Cheney's Blog](http://dave.cheney.net)
* [Dave Cheney's Resources for Go Programmers](http://dave.cheney.net/resources-for-new-go-programmers)
* [spf13's Blog](http://spf13.com/post/)
* [Mat Ryer's Medium Blog](https://medium.com/@matryer)
* [Matt Aimonetti's Blog](http://matt.aimonetti.net/)
* [Marcio.io](http://marcio.io/)
* [Carlos Becker's Blog](http://carlosbecker.com/)
* [Ardan Labs](https://www.ardanlabs.com/blog/)
* [The Golang Weekly](http://golangweekly.com/)
* [Alex Edward's Go Posts](http://www.alexedwards.net/blog/category/golang)
* [GoLang Tutorials](http://golangtutorials.blogspot.com/)
* [Mathias Lafeldt's Blog](https://mlafeldt.github.io/)
* [Marcelo Magallon's Blog](http://blog.ksub.org/bytes/)
* [Mina Andrawos's Go Posts](http://www.minaandrawos.com/category/golang-2/)
* [Aliaksandr Pliutau's Blog](http://pliutau.com/)
* [Johan Brandhorst's Blog](https://jbrandhorst.com)
* [Christoph Berger's Applied Go Blog](https://appliedgo.net)
* [Jon Calhoun's Blog](https://www.calhoun.io/)
* [Inanc Gumus's Learn Go Programming Blog](https://blog.learngoprogramming.com)
* [Elliot Forbes - TutorialEdge.net Go Tutorials](https://tutorialedge.net/course/golang/)
* [Timo Savola's Go Posts](http://savo.la/go)
* [Packt Hub](https://hub.packtpub.com/)
* [GoCenter Community Blog](https://jfrog.com/resource-center/?src=gocenter) - Blogs from GoCenter.io about Go modules and community.
* [Golang on the Boot.dev Blog](https://blog.boot.dev/golang/)
* [Golang Tutorials ](https://www.w3basic.com/golang/) - Golang Tutorials and Blog
* [Go articles at golang.dk](https://www.golang.dk/articles)
* [Bitfield Consulting](https://bitfieldconsulting.com/golang)
* [Mahmud Ridwan's Go Posts](https://hjr265.me/tags/go/)
## Bahasa Indonesia
* [Go blog dalam Bahasa Indonesia](https://golang-id.org/blog)
## Portuguese
* [Eduardo Nunes Pereira](https://medium.com/@eduardonunespereira)
* [Gopher Brasil](http://gopher.net.br)
* [Bruno Gomes's Blog](https://dev.to/bgskurono)
## Chinese
* [无忌-Jincheng's Blog](https://jincheng9.github.io/)
* [Howtoing运维教程](https://www.howtoing.com)
* [虞双齐的博客-Golang](https://yushuangqi.com/tags/golang.html)
* [Tony Bai -- 一个程序员的心路历程](http://tonybai.com/)
* [Arthur 的博客](http://www.zenlife.tk/index)
* [鸟窝](http://colobu.com/)
* [飞雪无情的博客](http://www.flysnow.org)
* [午夜咖啡](http://jolestar.com/)
* [蝈蝈俊的技术心得](http://www.cnblogs.com/ghj1976/)
* [FuXiaohei.Me -- 傅小黑的自留地](http://fuxiaohei.me/)
* [无闻的小站](https://github.com/Unknwon/wuwen.org)
* [astaxie](https://my.oschina.net/astaxie)
* [风笑痴](http://lunny.info/)
* [ipfans's Blog](https://www.4async.com/)
* [Cyeam -- 你不要用战术的勤奋掩盖战略的懒惰。](http://blog.cyeam.com/)
* [战魂小筑](http://www.cppblog.com/sunicdavy)
* [My Candy](http://mengqi.info/)
* [fatedier blog](http://blog.fatedier.com)
* [siddontang 的专栏-my thought for program。](http://blog.csdn.net/siddontang)
* [domac 博客 life should be func](http://lihaoquan.me)
* [七牛云 - 七牛团队博客](http://blog.qiniu.com/)
* [博客 - PingCAP](https://pingcap.com/bloglist)
* [LittleFeng 的博客 -- Python、Golang、Java、后端技术](https://allenwind.github.io)
* [Legendtkl](http://legendtkl.com/)
* [行思錄,Travel Coder - Arch, Coding, Life Learning](https://liudanking.com)
* [jasper的技术小窝](http://www.opscoder.info)
* [三月沙](https://sanyuesha.com/)
* [大桥下的蜗牛](https://blog.lab99.org/)
* [煎鱼的迷之博客](https://eddycjy.com/posts/)
* [Stefno - 博客园](https://www.cnblogs.com/qcrao-2018/)
* [No Headback](http://xargin.com/)
* [Go 语言基础](https://github.com/weirubo/learn_go)
* [chai2010 的博客](https://chai2010.cn/)

1043
Books.md

File diff suppressed because it is too large Load Diff

28
BoundingResourceUse.md

@ -1,28 +1,4 @@
To bound a program's use of a limited resource - like memory - have goroutines synchronize their use of that resource using a buffered channel (i.e., use the channel as a semaphore): The Go wiki on GitHub has moved to go.dev (#61940).
```go Try <https://go.dev/wiki/BoundingResourceUse> or <https://go.dev/wiki/>.
const (
AvailableMemory = 10 << 20 // 10 MB
AverageMemoryPerRequest = 10 << 10 // 10 KB
MaxOutstanding = AvailableMemory / AverageMemoryPerRequest
)
var sem = make(chan int, MaxOutstanding)
func Serve(queue chan *Request) {
for {
sem <- 1 // Block until there's capacity to process a request.
req := <-queue
go handle(req) // Don't wait for handle to finish.
}
}
func handle(r *Request) {
process(r) // May take a long time & use a lot of memory or CPU
<-sem // Done; enable next request to run.
}
```
## References
Effective Go's discussion of channels: https://go.dev/doc/effective_go#channels

220
CSSStyleGuide.md

@ -1,220 +1,4 @@
# Go CSS Coding Guidelines The Go wiki on GitHub has moved to go.dev (#61940).
**Please [discuss changes](https://go.dev/issue/new?title=wiki%3A+CSSStyleGuide+change&body=&labels=Documentation) before editing this page**, even _minor_ ones. Many people have opinions and this is not the place for edit wars. Try <https://go.dev/wiki/CSSStyleGuide> or <https://go.dev/wiki/>.
Go's naming conventions are adapted from [Medium's style guide](https://gist.github.com/fat/a47b882eb5f84293c4ed#javascript) and the work being done in the [SUIT CSS framework](https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md). Which is to say, it relies on _structured class names_ and _meaningful hyphens_ (i.e., not using hyphens merely to separate words). This is to help work around the current limits of applying CSS to the DOM (i.e., the lack of style encapsulation) and to better communicate the relationships between classes.
We require plain CSS over preprocessors like LESS, SASS, etc. This is to avoid additional tooling dependencies.
## JavaScript
syntax: `js-<targetName>`
JavaScript-specific classes reduce the risk that changing the structure or theme of components will inadvertently affect any required JavaScript behavior and complex functionality. You must use these classes if you interact with the DOM via JavaScript. In practice this looks like this:
```
<a href="/login" class="Button Button--primary js-login"></a>
```
Again, JavaScript-specific classes should not, under any circumstances, be styled.
## Components
Syntax: `[namespace-]<ComponentName>[-descendantName][--modifierName]`
Component driven development offers several benefits when reading and writing HTML and CSS:
* It helps to distinguish between the classes for the root of the component, descendant elements, and modifications.
* It keeps the specificity of selectors low.
* It helps to decouple presentation semantics from document semantics.
You can think of components as custom elements that enclose specific semantics, styling, and behavior.
### namespace (optional)
If necessary, components can be prefixed with a namespace. For example, you may wish to avoid the potential for collisions between libraries and your custom components by prefixing all your components with a namespace.
```
.godoc-Button { /* … */ }
.godoc-Tabs { /* … */ }
```
This makes it clear, when reading the HTML, which components are part of your library.
### ComponentName
The component's name must be written in camel case.
```
.MyComponent { /* … */ }
<article class="MyComponent">
…
</article>
```
### ComponentName--modifierName
A component modifier is a class that modifies the presentation of the base component in some form. Modifier names must be written in camel case and be separated from the component name by two hyphens. The class should be included in the HTML _in addition_ to the base component class.
```
/* Core button */
.Button { /* … */ }
/* Default button style */
.Button--default { /* … */ }
<button class="Button Button--primary">…</button>
```
### ComponentName-descendantName
A component descendant is a class that is attached to a descendant node of a component. It's responsible for applying presentation directly to the descendant on behalf of a particular component. Descendant names must be written in camel case.
```
<article class="Tweet">
<header class="Tweet-header">
<img class="Tweet-avatar" src="{$src}" alt="{$alt}">
…
</header>
<div class="Tweet-body">
…
</div>
</article>
```
### ComponentName[aria-<state of component>]
Almost always, component states can be represented using ARIA (aria-expanded, aria-disabled, etc.) so they are recommended for state-based modifications of components. In the very rare case that there is a state that cannot be represented using ARIA, a CSS class of the format `is-stateName` can be used. The CSS state name must be Camel case. Never style these attributes/classes directly; they should always be used as an adjoining class or attribute.
JS can add/remove these attributes/classes. Every component must define its own styles for the state (as they are scoped to the component).
```
.Tweet { /* … */ }
.Tweet[aria-expanded=true] { /* … */ }
.Tweet.is-blorked { /* … */ }
<article class="Tweet is-blorked" aria-expanded="true">
…
</article>
```
### Colors
Prefer lower-case hex values, RGB, or RGBA over named, HSL, or HSLA values. Use short-form hex values where applicable.
Right:
```
#fff;
#f1f2f3;
rgb(50, 50, 50);
rgba(50, 50, 50, 0.2);
```
Wrong:
```
#FFFFFF;
#F1F2F3;
white;
hsl(120, 100%, 50%);
hsla(120, 100%, 50%, 1);
```
## Formatting
The following are some high level page formatting style rules.
### Spacing
CSS rules should be comma separated but live on new lines:
Right:
```
.Content,
.Content-edit {
…
}
```
Wrong:
```
.Content, .Content-edit {
…
}
```
CSS blocks should be separated by a single new line. not two. not 0.
Right:
```
.Content {
…
}
.Content-edit {
…
}
```
Wrong:
```
.Content {
…
}
.Content-edit {
…
}
```
### Quotes
Quotes are optional in CSS. We use single quotes as it is visually clearer that the string is not a selector or a style property.
Right:
```
background-image: url('/img/you.jpg');
font-family: 'Helvetica Neue Light', 'Helvetica Neue', Helvetica, Arial;
```
Wrong:
```
background-image: url(/img/you.jpg);
font-family: Helvetica Neue Light, Helvetica Neue, Helvetica, Arial;
```
## Write Simple Selectors
Avoid sequences of simple selectors ("compound selectors").
The only exceptions are state-based selectors that are dynamically added to indicate a state change (for example, a tweet that has "[aria-expanded=true]").
Right:
```
/* State-based simple selector. */
tweet[aria-expanded=true] {
...
}
```
Wrong:
```
/* Sequence of simple selectors. */
button.foo.bar {
...
}
```
## Images
Add height and width attributes to images in the html markup to help minimize layout shift during page load.
```
<img src="url/to/image.png" height="240" width="160">
```

46
ChromeOS.md

@ -1,46 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
You don't need to compile from source in Developer mode, you can just use the [Chromebrew](https://github.com/skycocker/chromebrew)-provided version. Try <https://go.dev/wiki/ChromeOS> or <https://go.dev/wiki/>.
If your Chromebook is relatively new, you can enable the Linux VM now built into ChromeOS to install Go without developer mode. Follow the steps from the following Google Support article to enable this feature- https://support.google.com/chromebook/answer/9145439. This has been tested on a Samsung Chromebook Plus on version 71.0.3578.127. If this feature is not available for you, you will need to enable Developer Mode.
This tutorial will show you how to install, build, and run Go on Chrome OS.
Please note this has only been tested on a 64GB LTE Pixel, however it should work on other Chromebooks. Note that enabling developer mode reduces the security guarantees offered by Chrome OS.
# Install Go
First download the latest version of Go for Linux from the [Go Downloads page](https://go.dev/dl/).
After that, open a shell by hitting (CTRL+ALT+T) and typing in `shell` then hit enter. Then extract it using the following command (when replacing `< Go Linux package >` with the name of the file you downloaded):
```
sudo tar xpvf ~/Downloads/< Go Linux package > -C /usr/local
```
Go should now be installed you can test this by typing `/usr/local/go/bin/go`. If it installed correctly, you should see the Go help prompt. Go is now installed.
# Create a Workspace
To keep this simple just create a folder called `/usr/local/go/work`. Also, create a folder called `src` inside `/usr/local/go/work/`.
# Set PATH
Add the following to `~/.bashrc`:
```
export GOPATH="/usr/local/go/work"
export PATH="${PATH}:/usr/local/go/bin:${GOPATH}/bin"
```
This will allow you to run your Go programs in your shell.
# Test if it worked
First create a folder inside of your `/usr/local/go/src` folder. After that create a file in your folder called `hello.go` with the following in it:
```go
package main
import "fmt"
func main() {
fmt.Println("Hello, Chrome OS!")
}
```
Now, run `go install hello`. Then, run `${GOPATH}/bin/hello` (or just `hello` if you setup your GOPATH above) and you should see `Hello, Chrome OS!`.
***
# Reporting bugs
Please go to [Issues](https://github.com/golang/go/issues) to report any issues you have.

54
CodeReview.md

@ -1,54 +1,4 @@
Be sure to familiarize yourself with the code review process from the official [Contribution Guide](https://go.dev/doc/contribute) first. The Go wiki on GitHub has moved to go.dev (#61940).
# Reviewer Parlance Try <https://go.dev/wiki/CodeReview> or <https://go.dev/wiki/>.
There are several terms code reviews may use that you should become familiar with.
* ` LGTM ` — looks good to me
* ` SGTM ` — sounds good to me
* ` PTAL ` — please take a look
* ` s/foo/bar/ ` — please replace ` foo ` with ` bar `; this is [sed syntax](http://en.wikipedia.org/wiki/Sed#Usage)
* ` s/foo/bar/g ` — please replace ` foo ` with ` bar ` throughout your entire change
# CL Directives
* `R=foo` — assign a reviewer within the [Go CL dashboard](https://swtch.com/godash/)
* `RELNOTE=yes` or `RELNOTE=<subject>` — tag for release notes; scraped by the [relnote](https://golang.org/x/build/cmd/relnote) tool
* `DO NOT SUBMIT` (in the commit message) — block submission; see the "Work in progress" section below
* `Updates #1234` or `Fixes #1234` (in the commit message) — link the CL from the GitHub issue and optionally close the issue after the CL is merged
# Email
Messages from a code review are typically sent to three places:
* the reviewers, if any
* the golang-codereviews group
* the owner
Please do NOT reply code review via email, as the message [will not be relayed to Gerrit](https://code.google.com/p/gerrit/issues/detail?id=228). Always click on the link and post reply in Gerrit.
# Work in progress
If you have changes that aren't ready to be reviewed, you can put a giant **`DO NOT REVIEW`** as the second line of the CL description, so that people who see it know not to look any further. Don't make it the first line, since then it will become the subject for the entire review, even after you've changed the description.
Similarly, if you would like to ensure that your changes are not merged by mistake, you can put **`DO NOT SUBMIT`** as the second line of the CL description.
If you don't need Gerrit's features, but just want to backup your work, share work between multiple clients, or have a staging UI to examine your changes, you can use a regular git remote.
To use GitHub as a git remote, you can either fork github.com/golang/go or create a new repo. There are trade-offs. Forked repos will have a faster first push. Non-forked repos can be private. Forked repos are associated in GitHub's system. As a result, they are easily discoverable and support cross-repo comparisons in the GitHub UI; however, this also means that references to issues in commit messages in forked repos will create references to your fork in the issue.
To add your git remote, run something like:
```bash
$ git remote add fork git@github.com:yourusername/go.git
```
You can then push changes to the "fork" remote with `git push fork branchname`.
Gerrit's code review model is to rewrite a single commit until it is correct. GitHub will try to prevent you from accidentally overwriting your existing branch. You can work around this by forcing the push: `git push --force fork branchname`. Alternatively, you can set up your forked remote as a mirror by cloning it initially with:
```bash
$ git remote add --mirror=push fork git@github.com:yourusername/go.git
```
Then running `git push fork` will update GitHub to perfectly mirror *everything* (all branches, all tags, etc.). This is handy, but take care when using this on multiple clients. You are bypassing the usual git safeguards, so it is easy to overwrite (and thus lose) work pushed by a different client.

617
CodeReviewComments.md

@ -1,617 +1,4 @@
# Go Code Review Comments The Go wiki on GitHub has moved to go.dev (#61940).
This page collects common comments made during reviews of Go code, so Try <https://go.dev/wiki/CodeReviewComments> or <https://go.dev/wiki/>.
that a single detailed explanation can be referred to by shorthands.
This is a laundry list of common style issues, not a comprehensive style guide.
You can view this as a supplement to [Effective Go](https://go.dev/doc/effective_go).
Additional comments related to testing can be found at [Go Test Comments](https://github.com/golang/go/wiki/TestComments)
Google has published a longer [Go Style Guide](https://google.github.io/styleguide/go/decisions).
**Please [discuss changes](https://go.dev/issue/new?title=wiki%3A+CodeReviewComments+change&body=&labels=Documentation) before editing this page**, even _minor_ ones. Many people have opinions and this is not the place for edit wars.
* [Gofmt](#gofmt)
* [Comment Sentences](#comment-sentences)
* [Contexts](#contexts)
* [Copying](#copying)
* [Crypto Rand](#crypto-rand)
* [Declaring Empty Slices](#declaring-empty-slices)
* [Doc Comments](#doc-comments)
* [Don't Panic](#dont-panic)
* [Error Strings](#error-strings)
* [Examples](#examples)
* [Goroutine Lifetimes](#goroutine-lifetimes)
* [Handle Errors](#handle-errors)
* [Imports](#imports)
* [Import Blank](#import-blank)
* [Import Dot](#import-dot)
* [In-Band Errors](#in-band-errors)
* [Indent Error Flow](#indent-error-flow)
* [Initialisms](#initialisms)
* [Interfaces](#interfaces)
* [Line Length](#line-length)
* [Mixed Caps](#mixed-caps)
* [Named Result Parameters](#named-result-parameters)
* [Naked Returns](#naked-returns)
* [Package Comments](#package-comments)
* [Package Names](#package-names)
* [Pass Values](#pass-values)
* [Receiver Names](#receiver-names)
* [Receiver Type](#receiver-type)
* [Synchronous Functions](#synchronous-functions)
* [Useful Test Failures](#useful-test-failures)
* [Variable Names](#variable-names)
## Gofmt
Run [gofmt](https://pkg.go.dev/cmd/gofmt/) on your code to automatically fix the majority of mechanical style issues. Almost all Go code in the wild uses `gofmt`. The rest of this document addresses non-mechanical style points.
An alternative is to use [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports), a superset of `gofmt` which additionally adds (and removes) import lines as necessary.
## Comment Sentences
See https://go.dev/doc/effective_go#commentary. Comments documenting declarations should be full sentences, even if that seems a little redundant. This approach makes them format well when extracted into godoc documentation. Comments should begin with the name of the thing being described and end in a period:
```go
// Request represents a request to run a command.
type Request struct { ...
// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ...
```
and so on.
## Contexts
Values of the context.Context type carry security credentials,
tracing information, deadlines, and cancellation signals across API
and process boundaries. Go programs pass Contexts explicitly along
the entire function call chain from incoming RPCs and HTTP requests
to outgoing requests.
Most functions that use a Context should accept it as their first parameter:
```
func F(ctx context.Context, /* other arguments */) {}
```
A function that is never request-specific may use context.Background(),
but err on the side of passing a Context even if you think you don't need
to. The default case is to pass a Context; only use context.Background()
directly if you have a good reason why the alternative is a mistake.
Don't add a Context member to a struct type; instead add a ctx parameter
to each method on that type that needs to pass it along. The one exception
is for methods whose signature must match an interface in the standard library
or in a third party library.
Don't create custom Context types or use interfaces other than Context in
function signatures.
If you have application data to pass around, put it in a parameter,
in the receiver, in globals, or, if it truly belongs there, in a Context value.
Contexts are immutable, so it's fine to pass the same ctx to multiple
calls that share the same deadline, cancellation signal, credentials,
parent trace, etc.
## Copying
To avoid unexpected aliasing, be careful when copying a struct from another package.
For example, the bytes.Buffer type contains a `[]byte` slice. If you copy a `Buffer`,
the slice in the copy may alias the array in the original, causing subsequent method
calls to have surprising effects.
In general, do not copy a value of type `T` if its methods are associated with the
pointer type, `*T`.
## Crypto Rand
Do not use package `math/rand` to generate keys, even throwaway ones.
Unseeded, the generator is completely predictable. Seeded with `time.Nanoseconds()`,
there are just a few bits of entropy. Instead, use `crypto/rand`'s Reader,
and if you need text, print to hexadecimal or base64:
``` go
import (
"crypto/rand"
// "encoding/base64"
// "encoding/hex"
"fmt"
)
func Key() string {
buf := make([]byte, 16)
_, err := rand.Read(buf)
if err != nil {
panic(err) // out of randomness, should never happen
}
return fmt.Sprintf("%x", buf)
// or hex.EncodeToString(buf)
// or base64.StdEncoding.EncodeToString(buf)
}
```
## Declaring Empty Slices
When declaring an empty slice, prefer
```go
var t []string
```
over
```go
t := []string{}
```
The former declares a nil slice value, while the latter is non-nil but zero-length. They are functionally equivalent—their `len` and `cap` are both zero—but the nil slice is the preferred style.
Note that there are limited circumstances where a non-nil but zero-length slice is preferred, such as when encoding JSON objects (a `nil` slice encodes to `null`, while `[]string{}` encodes to the JSON array `[]`).
When designing interfaces, avoid making a distinction between a nil slice and a non-nil, zero-length slice, as this can lead to subtle programming errors.
For more discussion about nil in Go see Francesc Campoy's talk [Understanding Nil](https://www.youtube.com/watch?v=ynoY2xz-F8s).
## Doc Comments
All top-level, exported names should have doc comments, as should non-trivial unexported type or function declarations. See https://go.dev/doc/effective_go#commentary for more information about commentary conventions.
## Don't Panic
See https://go.dev/doc/effective_go#errors. Don't use panic for normal error handling. Use error and multiple return values.
## Error Strings
Error strings should not be capitalized (unless beginning with proper nouns or acronyms) or end with punctuation, since they are usually printed following other context. That is, use `fmt.Errorf("something bad")` not `fmt.Errorf("Something bad")`, so that `log.Printf("Reading %s: %v", filename, err)` formats without a spurious capital letter mid-message. This does not apply to logging, which is implicitly line-oriented and not combined inside other messages.
## Examples
When adding a new package, include examples of intended usage: a runnable Example,
or a simple test demonstrating a complete call sequence.
Read more about [testable Example() functions](https://go.dev/blog/examples).
## Goroutine Lifetimes
When you spawn goroutines, make it clear when - or whether - they exit.
Goroutines can leak by blocking on channel sends or receives: the garbage collector
will not terminate a goroutine even if the channels it is blocked on are unreachable.
Even when goroutines do not leak, leaving them in-flight when they are no longer
needed can cause other subtle and hard-to-diagnose problems. Sends on closed channels
panic. Modifying still-in-use inputs "after the result isn't needed" can still lead
to data races. And leaving goroutines in-flight for arbitrarily long can lead to
unpredictable memory usage.
Try to keep concurrent code simple enough that goroutine lifetimes are obvious.
If that just isn't feasible, document when and why the goroutines exit.
## Handle Errors
See https://go.dev/doc/effective_go#errors. Do not discard errors using `_` variables. If a function returns an error, check it to make sure the function succeeded. Handle the error, return it, or, in truly exceptional situations, panic.
## Imports
Avoid renaming imports except to avoid a name collision; good package names
should not require renaming. In the event of collision, prefer to rename the most
local or project-specific import.
Imports are organized in groups, with blank lines between them.
The standard library packages are always in the first group.
```go
package main
import (
"fmt"
"hash/adler32"
"os"
"github.com/foo/bar"
"rsc.io/goversion/version"
)
```
<a href="https://pkg.go.dev/golang.org/x/tools/cmd/goimports">goimports</a> will do this for you.
## Import Blank
Packages that are imported only for their side effects (using the syntax `import
_ "pkg"`) should only be imported in the main package of a program, or in tests
that require them.
## Import Dot
The import . form can be useful in tests that, due to circular dependencies, cannot be made part of the package being tested:
```go
package foo_test
import (
"bar/testutil" // also imports "foo"
. "foo"
)
```
In this case, the test file cannot be in package foo because it uses bar/testutil, which imports foo. So we use the 'import .' form to let the file pretend to be part of package foo even though it is not. Except for this one case, do not use import . in your programs. It makes the programs much harder to read because it is unclear whether a name like Quux is a top-level identifier in the current package or in an imported package.
## In-Band Errors
In C and similar languages, it's common for functions to return values like -1
or null to signal errors or missing results:
```go
// Lookup returns the value for key or "" if there is no mapping for key.
func Lookup(key string) string
// Failing to check for an in-band error value can lead to bugs:
Parse(Lookup(key)) // returns "parse failure for value" instead of "no value for key"
```
Go's support for multiple return values provides a better solution.
Instead of requiring clients to check for an in-band error value, a function should return
an additional value to indicate whether its other return values are valid. This return
value may be an error, or a boolean when no explanation is needed.
It should be the final return value.
``` go
// Lookup returns the value for key or ok=false if there is no mapping for key.
func Lookup(key string) (value string, ok bool)
```
This prevents the caller from using the result incorrectly:
``` go
Parse(Lookup(key)) // compile-time error
```
And encourages more robust and readable code:
``` go
value, ok := Lookup(key)
if !ok {
return fmt.Errorf("no value for %q", key)
}
return Parse(value)
```
This rule applies to exported functions but is also useful
for unexported functions.
Return values like nil, "", 0, and -1 are fine when they are
valid results for a function, that is, when the caller need not
handle them differently from other values.
Some standard library functions, like those in package "strings",
return in-band error values. This greatly simplifies string-manipulation
code at the cost of requiring more diligence from the programmer.
In general, Go code should return additional values for errors.
## Indent Error Flow
Try to keep the normal code path at a minimal indentation, and indent the error handling, dealing with it first. This improves the readability of the code by permitting visually scanning the normal path quickly. For instance, don't write:
```go
if err != nil {
// error handling
} else {
// normal code
}
```
Instead, write:
```go
if err != nil {
// error handling
return // or continue, etc.
}
// normal code
```
If the `if` statement has an initialization statement, such as:
```go
if x, err := f(); err != nil {
// error handling
return
} else {
// use x
}
```
then this may require moving the short variable declaration to its own line:
```go
x, err := f()
if err != nil {
// error handling
return
}
// use x
```
## Initialisms
Words in names that are initialisms or acronyms (e.g. "URL" or "NATO") have a consistent case. For example, "URL" should appear as "URL" or "url" (as in "urlPony", or "URLPony"), never as "Url". As an example: ServeHTTP not ServeHttp. For identifiers with multiple initialized "words", use for example "xmlHTTPRequest" or "XMLHTTPRequest".
This rule also applies to "ID" when it is short for "identifier" (which is pretty much all cases when it's not the "id" as in "ego", "superego"), so write "appID" instead of "appId".
Code generated by the protocol buffer compiler is exempt from this rule. Human-written code is held to a higher standard than machine-written code.
## Interfaces
Go interfaces generally belong in the package that uses values of the
interface type, not the package that implements those values. The
implementing package should return concrete (usually pointer or struct)
types: that way, new methods can be added to implementations without
requiring extensive refactoring.
Do not define interfaces on the implementor side of an API "for mocking";
instead, design the API so that it can be tested using the public API of
the real implementation.
Do not define interfaces before they are used: without a realistic example
of usage, it is too difficult to see whether an interface is even necessary,
let alone what methods it ought to contain.
``` go
package consumer // consumer.go
type Thinger interface { Thing() bool }
func Foo(t Thinger) string { … }
```
``` go
package consumer // consumer_test.go
type fakeThinger struct{ … }
func (t fakeThinger) Thing() bool { … }
…
if Foo(fakeThinger{…}) == "x" { … }
```
``` go
// DO NOT DO IT!!!
package producer
type Thinger interface { Thing() bool }
type defaultThinger struct{ … }
func (t defaultThinger) Thing() bool { … }
func NewThinger() Thinger { return defaultThinger{ … } }
```
Instead return a concrete type and let the consumer mock the producer implementation.
``` go
package producer
type Thinger struct{ … }
func (t Thinger) Thing() bool { … }
func NewThinger() Thinger { return Thinger{ … } }
```
## Line Length
There is no rigid line length limit in Go code, but avoid uncomfortably long lines.
Similarly, don't add line breaks to keep lines short when they are more readable long--for example,
if they are repetitive.
Most of the time when people wrap lines "unnaturally" (in the middle of function calls or
function declarations, more or less, say, though some exceptions are around), the wrapping would be
unnecessary if they had a reasonable number of parameters and reasonably short variable names.
Long lines seem to go with long names, and getting rid of the long names helps a lot.
In other words, break lines because of the semantics of what you're writing (as a general rule)
and not because of the length of the line. If you find that this produces lines that are too long,
then change the names or the semantics and you'll probably get a good result.
This is, actually, exactly the same advice about how long a function should be. There's no rule
"never have a function more than N lines long", but there is definitely such a thing as too long
of a function, and of too repetitive tiny functions, and the solution is to change where the function
boundaries are, not to start counting lines.
## Mixed Caps
See https://go.dev/doc/effective_go#mixed-caps. This applies even when it breaks conventions in other languages. For example an unexported constant is `maxLength` not `MaxLength` or `MAX_LENGTH`.
Also see [Initialisms](https://github.com/golang/go/wiki/CodeReviewComments#initialisms).
## Named Result Parameters
Consider what it will look like in godoc. Named result parameters like:
```go
func (n *Node) Parent1() (node *Node) {}
func (n *Node) Parent2() (node *Node, err error) {}
```
will be repetitive in godoc; better to use:
```go
func (n *Node) Parent1() *Node {}
func (n *Node) Parent2() (*Node, error) {}
```
On the other hand, if a function returns two or three parameters of the same type,
or if the meaning of a result isn't clear from context, adding names may be useful
in some contexts. Don't name result parameters just to avoid declaring a var inside
the function; that trades off a minor implementation brevity at the cost of
unnecessary API verbosity.
```go
func (f *Foo) Location() (float64, float64, error)
```
is less clear than:
```go
// Location returns f's latitude and longitude.
// Negative values mean south and west, respectively.
func (f *Foo) Location() (lat, long float64, err error)
```
Naked returns are okay if the function is a handful of lines. Once it's a medium
sized function, be explicit with your return values. Corollary: it's not worth it
to name result parameters just because it enables you to use naked returns.
Clarity of docs is always more important than saving a line or two in your function.
Finally, in some cases you need to name a result parameter in order to change
it in a deferred closure. That is always OK.
## Naked Returns
A `return` statement without arguments returns the named return values. This is known as a "naked" return.
```go
func split(sum int) (x, y int) {
x = sum * 4 / 9
y = sum - x
return
}
```
See [Named Result Parameters](#named-result-parameters).
## Package Comments
Package comments, like all comments to be presented by godoc, must appear adjacent to the package clause, with no blank line.
```go
// Package math provides basic constants and mathematical functions.
package math
```
```go
/*
Package template implements data-driven templates for generating textual
output such as HTML.
....
*/
package template
```
For "package main" comments, other styles of comment are fine after the binary name (and it may be capitalized if it comes first), For example, for a `package main` in the directory `seedgen` you could write:
``` go
// Binary seedgen ...
package main
```
or
```go
// Command seedgen ...
package main
```
or
```go
// Program seedgen ...
package main
```
or
```go
// The seedgen command ...
package main
```
or
```go
// The seedgen program ...
package main
```
or
```go
// Seedgen ..
package main
```
These are examples, and sensible variants of these are acceptable.
Note that starting the sentence with a lower-case word is not among the
acceptable options for package comments, as these are publicly-visible and
should be written in proper English, including capitalizing the first word
of the sentence. When the binary name is the first word, capitalizing it is
required even though it does not strictly match the spelling of the
command-line invocation.
See https://go.dev/doc/effective_go#commentary for more information about commentary conventions.
## Package Names
All references to names in your package will be done using the package name,
so you can omit that name from the identifiers. For example, if you are in package chubby,
you don't need type ChubbyFile, which clients will write as `chubby.ChubbyFile`.
Instead, name the type `File`, which clients will write as `chubby.File`.
Avoid meaningless package names like util, common, misc, api, types, and interfaces. See https://go.dev/doc/effective_go#package-names and
https://go.dev/blog/package-names for more.
## Pass Values
Don't pass pointers as function arguments just to save a few bytes. If a function refers to its argument `x` only as `*x` throughout, then the argument shouldn't be a pointer. Common instances of this include passing a pointer to a string (`*string`) or a pointer to an interface value (`*io.Reader`). In both cases the value itself is a fixed size and can be passed directly. This advice does not apply to large structs, or even small structs that might grow.
## Receiver Names
The name of a method's receiver should be a reflection of its identity; often a one or two letter abbreviation of its type suffices (such as "c" or "cl" for "Client"). Don't use generic names such as "me", "this" or "self", identifiers typical of object-oriented languages that gives the method a special meaning. In Go, the receiver of a method is just another parameter and therefore, should be named accordingly. The name need not be as descriptive as that of a method argument, as its role is obvious and serves no documentary purpose. It can be very short as it will appear on almost every line of every method of the type; familiarity admits brevity. Be consistent, too: if you call the receiver "c" in one method, don't call it "cl" in another.
## Receiver Type
Choosing whether to use a value or pointer receiver on methods can be difficult, especially to new Go programmers. If in doubt, use a pointer, but there are times when a value receiver makes sense, usually for reasons of efficiency, such as for small unchanging structs or values of basic type. Some useful guidelines:
* If the receiver is a map, func or chan, don't use a pointer to them. If the receiver is a slice and the method doesn't reslice or reallocate the slice, don't use a pointer to it.
* If the method needs to mutate the receiver, the receiver must be a pointer.
* If the receiver is a struct that contains a sync.Mutex or similar synchronizing field, the receiver must be a pointer to avoid copying.
* If the receiver is a large struct or array, a pointer receiver is more efficient. How large is large? Assume it's equivalent to passing all its elements as arguments to the method. If that feels too large, it's also too large for the receiver.
* Can function or methods, either concurrently or when called from this method, be mutating the receiver? A value type creates a copy of the receiver when the method is invoked, so outside updates will not be applied to this receiver. If changes must be visible in the original receiver, the receiver must be a pointer.
* If the receiver is a struct, array or slice and any of its elements is a pointer to something that might be mutating, prefer a pointer receiver, as it will make the intention clearer to the reader.
* If the receiver is a small array or struct that is naturally a value type (for instance, something like the time.Time type), with no mutable fields and no pointers, or is just a simple basic type such as int or string, a value receiver makes sense. A value receiver can reduce the amount of garbage that can be generated; if a value is passed to a value method, an on-stack copy can be used instead of allocating on the heap. (The compiler tries to be smart about avoiding this allocation, but it can't always succeed.) Don't choose a value receiver type for this reason without profiling first.
* Don't mix receiver types. Choose either pointers or struct types for all available methods.
* Finally, when in doubt, use a pointer receiver.
## Synchronous Functions
Prefer synchronous functions - functions which return their results directly or finish any callbacks or channel ops before returning - over asynchronous ones.
Synchronous functions keep goroutines localized within a call, making it easier to reason about their lifetimes and avoid leaks and data races. They're also easier to test: the caller can pass an input and check the output without the need for polling or synchronization.
If callers need more concurrency, they can add it easily by calling the function from a separate goroutine. But it is quite difficult - sometimes impossible - to remove unnecessary concurrency at the caller side.
## Useful Test Failures
Tests should fail with helpful messages saying what was wrong, with what inputs, what was actually got, and what was expected. It may be tempting to write a bunch of assertFoo helpers, but be sure your helpers produce useful error messages. Assume that the person debugging your failing test is not you, and is not your team. A typical Go test fails like:
```go
if got != tt.want {
t.Errorf("Foo(%q) = %d; want %d", tt.in, got, tt.want) // or Fatalf, if test can't test anything more past this point
}
```
Note that the order here is actual != expected, and the message uses that order too. Some test frameworks encourage writing these backwards: 0 != x, "expected 0, got x", and so on. Go does not.
If that seems like a lot of typing, you may want to write a [[table-driven test|TableDrivenTests]].
Another common technique to disambiguate failing tests when using a test helper with different input is to wrap each caller with a different TestFoo function, so the test fails with that name:
```go
func TestSingleValue(t *testing.T) { testHelper(t, []int{80}) }
func TestNoValues(t *testing.T) { testHelper(t, []int{}) }
```
In any case, the onus is on you to fail with a helpful message to whoever's debugging your code in the future.
## Variable Names
Variable names in Go should be short rather than long. This is especially true for local variables with limited scope. Prefer `c` to `lineCount`. Prefer `i` to `sliceIndex`.
The basic rule: the further from its declaration that a name is used, the more descriptive the name must be. For a method receiver, one or two letters is sufficient. Common variables such as loop indices and readers can be a single letter (`i`, `r`). More unusual things and global variables need more descriptive names.
See also the longer discussion in [the Google Go Style Guide](https://google.github.io/styleguide/go/decisions#variable-names).

248
CodeReviewConcurrency.md

@ -1,248 +1,4 @@
# Code Review: Go Concurrency The Go wiki on GitHub has moved to go.dev (#61940).
This page is an addition to the [Go Code Review Comments]( Try <https://go.dev/wiki/CodeReviewConcurrency> or <https://go.dev/wiki/>.
https://github.com/golang/go/wiki/CodeReviewComments) list. The goal of this list is to help to find
concurrency-related bugs when reviewing Go code.
You may also read through this list just once to refresh your memory and to make sure you are aware
of all these concurrency gotchas.
> ⚠️ This page is community authored and maintained. It includes information that is disputed and may be misleading or incorrect.
<hr>
Insufficient synchronisation and race conditions
- [HTTP handler functions are thread-safe?](#http-handlers)
- [Global functions and variables are protected by mutexes or otherwise thread-safe?](
https://go.dev/doc/articles/race_detector#Unprotected_global_variable)
- [*Reads* of fields and variables are protected?](#sync-balance)
- [The loop variable is passed into the goroutine function as an argument?](
https://go.dev/doc/articles/race_detector#Race_on_loop_counter)
- [Methods on thread-safe types don't return pointers to protected structures?](#return-pointer)
- [`Load()` or `Delete()` calls on a `sync.Map` after `Load()` is not a race condition?
](#sync-map-race)
Testing
- [Running tests with `-race` flag in CI/CD?](https://go.dev/doc/articles/race_detector)
Scalability
- [A channel is intentionally created with zero capacity?](#zero-cap-ch)
- [*Not* using `sync.RWMutex` to protect very short operations?](#rwmutex)
Time
- [`time.Ticker` is stopped using `defer tick.Stop()`?](#ticker-stop)
- [Comparing `time.Time` using `Equal()`, not `==`?](#time-eq)
- [Keeping the monotonic component in `time.Time` argument of `time.Since()`?](#time-since)
- [When comparing *system times* via `t.Before(u)`, the monotonic component is stripped
from the argument?](#time-before)
<hr>
### Insufficient synchronisation and race conditions
<a name="http-handlers"></a>
[#](#http-handlers) RC.1. **The HTTP handler function is safe to call concurrently from
multiple goroutines?** It's easy to overlook HTTP handlers should be thread-safe because they are
usually not called explicitly from anywhere in the project code, but only from the internals of the
HTTP server.
<a name="sync-balance"></a>
[#](#sync-balance) RC.2. Is there some **field or variable access not protected by a mutex** where
the field or the variable is a primitive or of a type that is not explicitly thread-safe (such as
`atomic.Value`), while this field can be updated from a concurrent goroutine? It's not safe to skip
synchronising reads even to primitive variables because of non-atomic hardware writes and potential
memory visibility problems.
See also a [Typical Data Race: Primitive unprotected variable](
https://go.dev/doc/articles/race_detector#Primitive_unprotected_variable).
<a name="return-pointer"></a>
[#](#return-pointer) RC.3. **A method on a thread-safe type doesn't return a pointer to a protected
structure?** This is a subtle bug which leads to the unprotected access problem described in the
previous item. Example:
```go
type Counters struct {
mu sync.Mutex
vals map[Key]*Counter
}
func (c *Counters) Add(k Key, amount int) {
c.mu.Lock()
defer c.mu.Unlock()
count, ok := c.vals[k]
if !ok {
count = &Counter{sum: 0, num: 0}
c.vals[k] = count
}
count.sum += amount
count.n += 1
}
func (c *Counters) GetCounter(k Key) *Counter {
c.mu.Lock()
defer c.mu.Unlock()
return c.vals[k] // BUG! Returns a pointer to the structure which must be protected
}
```
One possible solution is to return a copy, not a pointer to the structure in `GetCounter()`:
```go
type Counters struct {
mu sync.Mutex
vals map[Key]Counter // Note that now we are storing the Counters directly, not pointers.
}
...
func (c *Counters) GetCounter(k Key) Counter {
c.mu.Lock()
defer c.mu.Unlock()
return c.vals[k]
}
```
<a name="sync-map-race"></a>
[#](#sync-map-race) RC.4. If there is more than one goroutine that can update a `sync.Map`, **you
don't call `m.Store()` or `m.Delete()` depending on the success of a previous `m.Load()` call?**
In other words, the following code is racy:
```go
var m sync.Map
// Can be called concurrently from multiple goroutines
func DoSomething(k Key, v Value) {
existing, ok := m.Load(k)
if !ok {
m.Store(k, v) // RACE CONDITION - two goroutines can execute this in parallel
... some other logic, assuming the value in `k` is now `v` in the map
}
...
}
```
Such a race condition could be benign in some cases: for example, the logic between the `Load()` and
`Store()` calls computes the value to be cached in the map, and this computation always returns the
same result and doesn't have side effects.
> ⚠️ **Potentially misleading information**. "Race condition" can refer to logic errors, like this example, which can be benign. But the phrase is also commonly used to refer to violations of the memory model, which are never benign.
If the race condition is not benign, use methods [`sync.Map.LoadOrStore()`](
https://pkg.go.dev/sync/#Map.LoadOrStore) and [`LoadAndDelete()`](
https://pkg.go.dev/sync/#Map.LoadAndDelete) to fix it.
### Scalability
<a name="zero-cap-ch"></a>
[#](#zero-cap-ch) Sc.1. **Is this intentional that a channel is created with zero capacity**, like
`make(chan *Foo)`? A goroutine which sends a message to a zero-capacity channel is blocked until
another goroutine receives this message. Omitting the capacity in the `make()` call might be just
a mistake which will limit the scalability of the code, and it's likely unit test won't find such
a bug.
> ⚠️ **Misleading information**. Buffered channels do not inherently increase "scalability" versus unbuffered channels. However, buffered channels can easily obscure deadlocks and other fundamental design errors that would be immediately apparent with unbuffered channels.
<a name="rwmutex"></a>
[#](#rwmutex) Sc.2. Locking with `RWMutex` incurs extra overhead compared to plain `sync.Mutex`,
and, furthermore, there might be some [scalability issue with the current implementation of
`RWMutex` in Go](https://github.com/golang/go/issues/17973). Unless the case is very clear (such as
an `RWMutex` used to synchronize many read-only operations each lasting hundreds of milliseconds or
more, and the writes which require an exclusive lock seldom happen), **there should be some
benchmarks proving that `RWMutex` indeed helps to improve the performance.** A typical example where
`RWMutex` certainly does more harm than good is a simple protection of a variable in a struct:
```go
type Box struct {
mu sync.RWMutex // DON'T DO THIS -- use a simple Mutex instead.
x int
}
func (b *Box) Get() int {
b.mu.RLock()
defer b.mu.RUnlock()
return b.x
}
func (b *Box) Set(x int) {
b.mu.Lock()
defer b.mu.Unlock()
b.x = x
}
```
### Time
<a name="ticker-stop"></a>
[#](#ticker-stop) Tm.1. **Is `time.Ticker` stopped using `defer tick.Stop()`?** It's a memory leak
not to stop the ticker when the function which uses the ticker in a loop returns.
<a name="time-eq"></a>
[#](#time-eq) Tm.2. **Are `time.Time` structs compared using `Equal()` method, not just `==`?**
Quoting the [documentation for `time.Time`](https://pkg.go.dev/time/#Time):
> Note that the Go `==` operator compares not just the time instant but also the Location and the
> monotonic clock reading. Therefore, `Time` values should not be used as map or database keys
> without first guaranteeing that the identical Location has been set for all values, which can be
> achieved through use of the `UTC()` or `Local()` method, and that the monotonic clock reading has
> been stripped by setting `t = t.Round(0)`. In general, prefer `t.Equal(u)` to `t == u`, since
> `t.Equal()` uses the most accurate comparison available and correctly handles the case when only
> one of its arguments has a monotonic clock reading.
<a name="time-since"></a>
[#](#time-since) Tm.3. **Before calling `time.Since(t)`, the monotonic component is _not_ stripped
from `t`?** This is a consequence of the previous item. If the monotonic component is stripped from
the `time.Time` structure before passing it into `time.Since()` function (via calling either
`UTC()`, `Local()`, `In()`, `Round()`, `Truncate()`, or `AddDate()`) **the result of `time.Since()`
might be negative** on very rare occasions, such as if the system time has been synced via NTP between
the moment when the start time was originally obtained and the moment when `time.Since()` is called.
If the monotonic component is *not* stripped, `time.Since()` will always return a positive duration.
<a name="time-before"></a>
[#](#time-before) Tm.4. **If you want to compare *system times* via `t.Before(u)`, do you strip
the monotonic component from the argument,** e.g. via `u.Round(0)`? This is another point related to
[Tm.2](#time-eq). Sometimes, you need to compare two `time.Time` structs only by the system
time stored in them, specifically. You may need this before storing one of these `Time` structs on
disk or sending them over the network. Imagine, for example, some sort of telemetry agent which
pushes a telemetry metric together with time periodically to some remote system:
```go
var latestSentTime time.Time
func pushMetricPeriodically(ctx context.Context) {
t := time.NewTicker(time.Second)
defer t.Stop()
for {
select {
case <-ctx.Done: return
case <-t.C:
newTime := time.Now().Round(0) // Strip monotonic component to compare system time only
// Check that the new time is later to avoid messing up the telemetry if the system time
// is set backwards on an NTP sync.
if latestSentTime.Before(newTime) {
sendOverNetwork(NewDataPoint(newTime, metric()))
latestSentTime = newTime
}
}
}
}
```
This code would be wrong without calling `Round(0)`, i. e. stripping the monotonic component.
## Reading List
[Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments): a checklist for
reviewing Go code, not concurrency-specific.
Go concurrency:
- [The Go Memory Model](https://go.dev/ref/mem)
- [Section about concurrency in *Effective Go*](
https://go.dev/doc/effective_go#concurrency)
- Posts in The Go Blog:
- [Share Memory By Communicating](https://go.dev/blog/codelab-share)
- [Go Concurrency Patterns: Timing out, moving on](https://go.dev/blog/concurrency-timeouts)
- [Go Concurrency Patterns: Context](https://go.dev/blog/context)
- [Go Concurrency Patterns: Pipelines and cancellation](https://go.dev/blog/pipelines)
- [Advanced Go Concurrency Patterns](https://go.dev/blog/io2013-talk-concurrency) (video)
- [Rethinking Classical Concurrency Patterns](https://www.youtube.com/watch?v=5zXAHh5tJqQ) (video)
- [Understanding Real-World Concurrency Bugs in Go](https://songlh.github.io/paper/go-study.pdf)
Concurrency, but not specific to Go:
- [Mechanical Sympathy: Single Writer Principle](
https://mechanical-sympathy.blogspot.com/2011/09/single-writer-principle.html)

69
CodeTools.md

@ -1,69 +1,4 @@
An overview of tools that will help improve your Go code The Go wiki on GitHub has moved to go.dev (#61940).
## All-in-one Try <https://go.dev/wiki/CodeTools> or <https://go.dev/wiki/>.
- [golangci-lint](https://github.com/golangci/golangci-lint) - Bundle of `gofmt`, `golint`, `govet` and many other tools that shares work between the different linters for better performance. Recommended by the original author to replace gometalinter (Drop-in replacement).
- DEPRECATED: [gometalinter](https://github.com/alecthomas/gometalinter) - Automates the installation, configuration and application of `gofmt`, `golint`, `govet` and several other code validation tools.
## Code Formatting
### Articles
- [Formatting Go Code with gofmt](http://golangtutorials.blogspot.com/2011/06/formatting-go-code-with-gofmt.html)
### Tools
- [air](https://github.com/cosmtrek/air) - Live reload for Go apps
- [gofmt](https://pkg.go.dev/cmd/gofmt/) - Start with the standard Go code formatter.
- [golint](https://github.com/golang/lint) - Detects style mistakes in Go code (deprecated).
- [staticcheck](https://staticcheck.io/) - Go programming language linter.
- [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) - Format code and fix your import statements.
- [gofumpt](https://github.com/mvdan/gofumpt) - A stricter gofmt.
- [revive](https://github.com/mgechev/revive) - Fast, configurable, extensible, flexible, and beautiful linter for Go.
## Code generation, Templating and Generics
- [json-to-go](https://mholt.github.io/json-to-go/) - Generate Go structs from JSON.
- [Go gen](http://clipperhouse.github.io/gen/) - Type-driven code generation (generics)
- [gojson](https://github.com/ChimeraCoder/gojson) - Another Go struct generator.
- [gotemplate](https://github.com/ncw/gotemplate) - Package-based templating system for Go.
- [sqlgen](https://github.com/drone/sqlgen) - Generate Go code for SQL interactions.
- [zek](https://github.com/miku/zek) - Generate Go struct from XML.
- [apidocgen](https://github.com/alovn/apidocgen) - Generate web apis markdown docs and mocks.
- [goaccessor](https://github.com/yujiachen-y/goaccessor) - Getters and setters generator.
## Refactoring
### Articles
- [gorename - easy refactoring](https://texlution.com/post/gorename/)
- [Refactoring Tools](http://blog.ralch.com/tutorial/golang-tools-refactoring/) - An overview of refactoring tools for Go.
- [Quick renaming with gofmt](http://technosophos.com/2015/09/26/quick-go-hack-renaming-structs.html)
### Tools
- [eg](https://pkg.go.dev/golang.org/x/tools/cmd/eg) - Example-based refactoring tool for Go.
- [gofmt](https://pkg.go.dev/cmd/gofmt/) - Start with the standard Go code formatter.
- [gorename](https://golang.org/x/tools/refactor/rename) - Renaming tool for Go.
## Error Detection
### Articles
- [Go Inspection Tools](https://blog.ralch.com/articles/golang-tools-inspection/) - An overview of tools for Go code inspection.
### Tools
- [AlignCheck, StructCheck, VarCheck](https://github.com/opennota/check/) - A suite of tools for checking your code.
- [errcheck](https://github.com/kisielk/errcheck) - Ensure you check your error conditions.
- [go vet](https://pkg.go.dev/cmd/vet/) - Read this first on how to use the `go vet` command.
- [SafeSQL](https://github.com/stripe/safesql) - Protect against unsafe SQL in your code (deprecated).
## Navigation
- [Go Guru - User Manual](https://go.dev/s/using-guru) - A tool for understanding Go code.
- [Pythia](https://github.com/fzipp/pythia) - A browser-based UI for Go Guru.
## Visualization
- [godepgraph](http://github.com/kisielk/godepgraph) - A tool for generating dependency graphs of Go code.

38
Comments.md

@ -1,38 +1,4 @@
# Comments The Go wiki on GitHub has moved to go.dev (#61940).
Every package should have a package comment. It should immediately precede the ` package ` statement in one of the files in the package. (It only needs to appear in one file.) It should begin with a single sentence that begins "Package _packagename_" and give a concise summary of the package functionality. This introductory sentence will be used in godoc's list of all packages. Try <https://go.dev/wiki/Comments> or <https://go.dev/wiki/>.
Subsequent sentences and/or paragraphs can give more details. Sentences should be properly punctuated.
```go
// Package superman implements methods for saving the world.
//
// Experience has shown that a small number of procedures can prove
// helpful when attempting to save the world.
package superman
```
Nearly every top-level type, const, var and func should have a comment. A comment for bar should be in the form "_bar_ floats on high o'er vales and hills.". The first letter of _bar_ should not be capitalized unless it's capitalized in the code.
```go
// enterOrbit causes Superman to fly into low Earth orbit, a position
// that presents several possibilities for planet salvation.
func enterOrbit() os.Error {
...
}
```
All text that you indent inside a comment, godoc will render as a pre-formatted block. This facilitates code samples.
```go
// fight can be used on any enemy and returns whether Superman won.
//
// Examples:
//
// fight("a random potato")
// fight(LexLuthor{})
//
func fight(enemy interface{}) bool {
...
}
```

79
CommitMessage.md

@ -1,79 +1,4 @@
# Commit messages The Go wiki on GitHub has moved to go.dev (#61940).
Commit messages, also known as CL (changelist) descriptions, should be formatted per https://go.dev/doc/contribute#commit_messages. For example, Try <https://go.dev/wiki/CommitMessage> or <https://go.dev/wiki/>.
```
net/http: handle foo when bar
[longer description here in the body]
Fixes #12345
```
Notably, for the subject (the first line of description):
* the name of the package affected by the change goes before the colon
* the part after the colon uses the verb tense + phrase that completes the blank in, *"this change modifies Go to ___________"*
* the verb after the colon is lowercase
* there is no trailing period
* it should be kept as short as possible (many git viewing tools prefer under ~76 characters, though Go isn't super strict about this).
For the body (the rest of the description):
* the text should be wrapped to ~76 characters (to appease git viewing tools, mainly), unless you really need longer lines (e.g. for ASCII art, tables, or long links).
* the Fixes line goes after the body with a blank newline separating the two. (It is acceptable but not required to use a trailing period, such as `Fixes #12345.`).
* there is **no** Markdown in the commit message.
* we **do not** use `Signed-off-by` lines. Don't add them. Our Gerrit server & GitHub bots enforce CLA compliance instead.
* when referencing CLs, prefer saying "CL nnn" or using a go.dev/cl/nnn shortlink over a direct Gerrit URL or git hash, since that's more future-proof.
* when moving code between repos, include the CL, repository name, and git hash that it was moved from/to, so it is easier to trace history/blame.
Please _don't_ use alternate GitHub-supported aliases like `Close` or `Resolves` instead of `Fixes`.
To link a commit to an issue without marking it fixed—for example, if the commit is working toward a fix but not yet a complete fix—GitHub requires only that the issue is mentioned by number in the commit message. By convention, Go commits mention this at the bottom of the message using `For`, where `Fixes` might be expected, even if the number is also mentioned in the body of the commit message.
For example:
```
Refactor func Foo.
This will make the handling of <corner case>
shorter and easier to test.
For #12345
```
It is common in other Git projects to use `Updates` instead of `For`, and that is acceptable too, even though it makes little sense (the commit does not update the issue). More precise phrasings are fine too. Don't be too pedantic in code reviews: it's not worth asking people to change from `Updates` or something else to `For`, or vice versa.
# Reverts
You can roll back a change using the Gerrit `Revert` button.
Gerrit will generate a description for you.
Edit the description to add the Gerrit CL number being rolled back next to or instead of the Git revision number.
Do not use the Gerrit UI to create a revert of a revert, as that notifies people right away.
Instead, mail it as a new change, and in the description explain that it is a roll forward of CL NNNNNN which was rolled back by CL NNNNNN.
# Other repos
For non-"go" repos ("crypto", "tools", "net", etc), the subject is still the name of the package, but you need to fully-qualify the issue number with the GitHub org/repo syntax:
```
cipher/rot13: add new super secure cipher
Fixes golang/go#1234
````
Notably, the first line subject should **not** contain the `x/crypto/` prefix. We only do that for the issue tracker.
# Non-normative references
- [Please heed my plea and write good CL descriptions for Go—and for any other project you work on.](https://groups.google.com/d/msg/golang-dev/6M4dmZWpFaI/SyU5Sl4zZLYJ)
- [The CL description is a public document that explains to the future what has been done and why.](https://groups.google.com/d/msg/golang-dev/s07ZUR8ZDHo/i-rIsknbAwAJ)
# GitHub Pull Requests
If you're using GitHub Pull Requests, your commit message is constructed by GerritBot based on your
PR's title & description. See https://go.dev/wiki/GerritBot#how-does-gerritbot-determine-the-final-commit-message.
If somebody asks you to modify your commit message, you'll need to modify your PR.
![](images/github-to-gerrit.png)

142
CommonMistakes.md

@ -1,142 +1,4 @@
Table of Contents The Go wiki on GitHub has moved to go.dev (#61940).
=================
+ [Introduction](#introduction) Try <https://go.dev/wiki/CommonMistakes> or <https://go.dev/wiki/>.
+ [Using reference to loop iterator variable](#using-reference-to-loop-iterator-variable)
+ [Using goroutines on loop iterator variables](#using-goroutines-on-loop-iterator-variables)
# Introduction
When new programmers start using Go or when old Go programmers start using a new concept, there are some common mistakes that many of them make. Here is a non-exhaustive list of some frequent mistakes that show up on the mailing lists and in IRC.
# Using reference to loop iterator variable
In Go, the loop iterator variable is a single variable that takes different values in each loop iteration. This is very efficient, but might lead to unintended behavior when used incorrectly. For example, see the following program:
```go
func main() {
var out []*int
for i := 0; i < 3; i++ {
out = append(out, &i)
}
fmt.Println("Values:", *out[0], *out[1], *out[2])
fmt.Println("Addresses:", out[0], out[1], out[2])
}
```
It will output unexpected results:
```
Values: 3 3 3
Addresses: 0x40e020 0x40e020 0x40e020
```
Explanation: in each iteration we append the address of `i` to the `out` slice, but since it is the same variable, we append the same address which eventually contains the last value that was assigned to `i`. One of the solutions is to copy the loop variable into a new variable:
```diff
for i := 0; i < 3; i++ {
+ i := i // Copy i into a new variable.
out = append(out, &i)
}
```
The new output of the program is what was expected:
```
Values: 0 1 2
Addresses: 0x40e024 0x40e028 0x40e032
```
Explanation: the line `i := i` copies the loop variable `i` into a new variable scoped to the for loop body block, also called `i`. The address of the new variable is the one that is appended to the array, which makes it outlive the for loop body block. In each loop iteration a new variable is created.
While this example might look a bit obvious, the same unexpected behavior could be more hidden in some other cases. For example, the loop variable can be an array and the reference can be a slice:
```go
func main() {
var out [][]int
for _, i := range [][1]int{{1}, {2}, {3}} {
out = append(out, i[:])
}
fmt.Println("Values:", out)
}
```
Output:
```
Values: [[3] [3] [3]]
```
The same issue can be demonstrated also when the loop variable is being used in a Goroutine (see the following section).
# Using goroutines on loop iterator variables
When iterating in Go, one might attempt to use goroutines to process data in parallel. For example, you might write something like this, using a closure:
```go
for _, val := range values {
go func() {
fmt.Println(val)
}()
}
```
The above for loops might not do what you expect because their ` val ` variable is actually a single variable that takes on the value of each slice element. Because the closures are all only bound to that one variable, there is a very good chance that when you run this code you will see the last element printed for every iteration instead of each value in sequence, because the goroutines will probably not begin executing until after the loop.
The proper way to write that closure loop is:
```go
for _, val := range values {
go func(val interface{}) {
fmt.Println(val)
}(val)
}
```
By adding val as a parameter to the closure, ` val ` is evaluated at each iteration and placed on the stack for the goroutine, so each slice element is available to the goroutine when it is eventually executed.
It is also important to note that variables declared within the body of a loop are not shared between iterations, and thus can be used separately in a closure. The following code uses a common index variable ` i ` to create separate ` val `s, which results in the expected behavior:
```go
for i := range valslice {
val := valslice[i]
go func() {
fmt.Println(val)
}()
}
```
Note that without executing this closure as a goroutine, the code runs as expected. The following example prints out the integers between 1 and 10.
```go
for i := 1; i <= 10; i++ {
func() {
fmt.Println(i)
}()
}
```
Even though the closures all still close over the same variable (in this case, ` i `), they are executed before the variable changes, resulting in the desired behavior.
https://go.dev/doc/faq#closures_and_goroutines
You may find another, similar situation like the following:
```go
for _, val := range values {
go val.MyMethod()
}
func (v *val) MyMethod() {
fmt.Println(v)
}
```
The above example also will print last element of values, the reason is same as closure. To fix the issue declare another variable inside the loop.
```go
for _, val := range values {
newVal := val
go newVal.MyMethod()
}
func (v *val) MyMethod() {
fmt.Println(v)
}
```

115
CompilerOptimizations.md

@ -1,115 +1,4 @@
# Compiler And Runtime Optimizations The Go wiki on GitHub has moved to go.dev (#61940).
This page lists optimizations done by the compilers. Note that these are not guaranteed by the language specification. Try <https://go.dev/wiki/CompilerOptimizations> or <https://go.dev/wiki/>.
## Interface values
### Zero-width types in interface values
Putting a zero-width type in an interface value doesn't allocate.
* **gc:** 1.0+
* **gccgo:** ?
### Word-sized value in an interface value
Putting a word-sized-or-less non-pointer type in an interface value doesn't allocate.
* **gc:** 1.0-1.3, but *not* in 1.4+
* **gccgo:** never
## `string` and `[]byte`
### Map lookup by `[]byte`
For a map `m` of type `map[string]T` and `[]byte b`, `m[string(b)]` doesn't allocate. (the temporary string copy of the byte slice isn't made)
* **gc:** 1.4+
* **gccgo:** ?
### `range` over `[]byte`(s)
No allocation when converting a `string` into a `[]byte` for ranging over the bytes:
```go
s := "foo"
for i, c := range []byte(s) {
// ...
}
```
### conversion for string comparison
No allocation done when converting a `[]byte` into a `string` for comparison purposes
```go
var b1 string
var b2 []byte
var x = string(b1) == string(b2) // memeq
var y = string(b1) < string(b2) // lexicographical comparison
```
* **gc:** 1.5+ (CL 3790)
* **gccgo:** ?
## Escape analysis and Inlining
Use `-gcflags -m` to observe the result of escape analysis and inlining
decisions for the gc toolchain.
(TODO: explain the output of `-gcflags -m`).
### Escape analysis
Gc compiler does global escape analysis across function and package boundaries. However, there are lots of cases where it gives up. For example, anything assigned to any kind of indirection (`*p = ...`) is considered escaped. Other things that can inhibit analysis are: function calls, package boundaries, slice literals, subslicing and indexing, etc. Full rules are too complex to describe, so check the `-m` output.
* **gc:** 1.0+
* **gccgo:** 8.0+.
### Function Inlining
Only short and simple functions are inlined. To be inlined a function must conform to the rules:
- function should be simple enough, the number of AST nodes must less than the budget (80);
- function doesn't contain complex things like closures, defer, recover, select, etc;
- function isn't prefixed by go:noinline;
- function isn't prefixed by go:uintptrescapes, since the escape information will be lost during inlining;
- function has body;
- etc.
* **gc:** 1.0+
* **gccgo:** -O1 and above.
## Idioms
### Optimized memclr
For a slice or array s, loops of the form
```go
for i := range s {
s[i] = <zero value for element of s>
}
```
are converted into efficient runtime memclr calls. [Issue](https://github.com/golang/go/issues/5373) and [commit](https://go.dev/change/f03c9202c43e0abb130669852082117ca50aa9b1).
* **gc:** 1.5+
* **gccgo:** ?
## Non-scannable objects
Garbage collector does not scan underlying buffers of slices, channels and maps when element type does not contain pointers (both key and value for maps). This allows to hold large data sets in memory without paying high price during garbage collection. For example, the following map won't visibly affect GC time:
```go
type Key [64]byte // SHA-512 hash
type Value struct {
Name [32]byte
Balance uint64
Timestamp int64
}
m := make(map[Key]Value, 1e8)
```
* **gc:** 1.5+
* **gccgo:** ?

173
Conferences.md

@ -1,173 +1,4 @@
# Go Conferences and Major Events The Go wiki on GitHub has moved to go.dev (#61940).
## Upcoming Try <https://go.dev/wiki/Conferences> or <https://go.dev/wiki/>.
Please keep all items in chronological order.
<!--
There is also a map of the confirmed 2019 conferences at [j.mp/goconmap](http://j.mp/goconmap).
The map will be updated about once a week from the entries below. Errors in the map can be reported to van@golang.org.
-->
| Name | Date | Location | Website | CFP |
| --- | --- | --- | --- | --- |
| FOSDEM | 2024-02-03-04 | Brussels, Belgium | https://fosdem.org/2024/ | Go Devroom CFP https://github.com/go-devroom/cfp |
| GopherCon EU, Athens | 2024-02-06-08 | Athens, Greece | https://gophercon.eu/ | https://sessionize.com/gceu24a |
| GopherCon Brazil | 2024-05-09-10 | Florianópolis, SC, Brazil | https://gopherconbr.org/en/ | https://www.papercall.io/gopherconbrazil2024 |
| GopherCon EU, Berlin | 2024-06-17-20 | Berlin, Germany | https://gophercon.eu/ | https://sessionize.com/gceu24b |
## Archives
Please keep all items in reverse chronological order (most recent first)
| Name | Date | Location | Talk, Video Archives |
|------|------------|----------|----------------|
| GoLab | 2023-11-19-21 | Florence, Italy | https://golab.io |
| GopherChina | 2023-11-19 | ShangHai, China | http://gopherchina2023sh.bagevent.com |
| GopherCon AU 2023 | 2023-11-08-10 | Sydney, Australia | https://gophercon.com.au/ |
| Fyne Conf 2023 | 2023-11-03 | Edinburgh, UK | https://conf.fyne.io |
| GopherCon Singapore 2023 | 2023-11-02-03 | Singapore | https://2023.gophercon.sg |
| GoWest | 2023-10-27 | Lehi, Utah, USA | https://www.gowestconf.com/ |
| GopherCon | 2023-09-26-29 | San Diego | https://www.gophercon.com/ |
| GopherCon India | 2023-09-09-10 | Pune, India | https://gopherconindia.org |
| GopherCon UK | 2023-08-16-18 | London, UK | https://www.gophercon.co.uk/ |
| GopherCon Korea | 2023-08-05-06 | Seoul, Korea | https://festa.io/events/3435 |
| GopherCon Europe 2023 | 2023-06-26-29 | Berlin, Germany | https://gophercon.eu/, https://www.youtube.com/playlist?list=PLtoVuM73AmsJWvXYd_9rbYXcbv1UdzeLT |
| GopherChina | 2023-06-09-11 | Beijing, China | https://www.bagevent.com/event/8057917 |
| GothamGo | 2023-06-09 | New York City | https://gothamgo.com/ |
| Go Conference 2023 | 2023-06-02 | Online | https://gocon.jp/2023/ (talks coming soon) |
| Conf42: Golang 2023 | 2023-04-20 | Online | https://www.conf42.com/golang2023, https://www.youtube.com/playlist?list=PLIuxSyKxlQrBDOCy9ThDZ0kJX7skLE2ks |
| GopherCon Israel 2023 | 2023-02-07 | Tel Aviv, Israel | https://www.gophercon.org.il |
| Go Devroom FOSDEM | 2023-02-04 | Brussels, Belgium | https://fosdem.org/2023/schedule/track/go/ |
| GoWest Conference 2022 | 2022-10-21 | Online/ Salt Lake City, Ut USA| https://gowestconf.com |
| GopherCon | 2022-10-06-08 | Chicago | https://www.gophercon.com/ |
| GopherCon India 2022 | 2022-08-28 | Pune, India | https://gopherconindia.org |
| GopherCon Europe 2022 | 2022-07-28-31 | Berlin, Germany | https://gophercon.eu/ |
| GopherCon | 2021-12-05-08 | San Diego & Online | https://www.gophercon.com/ |
| GoWest Conference 2021 | 2021-10-22 | Online/ Salt Lake City, Ut USA| https://gowestconf.com |
| GopherCon Europe | 2021-05-26-28 | Online | https://gophercon.eu |
| O'Reilly OSS Superstream: Go | 2021-04-29 | Online | [website](https://learning.oreilly.com/attend/open-source-software-superstream-series-gogenerics-extensibility-and-the-future-of-go-in-open-source-programming/0636920053215/0636920053214)|
| GopherCon Russia 2021 Online | 2021-04-23-25 | Online | https://www.gophercon-russia.ru/en |
| | **2020** | | | |
| GopherCon Singapore 2020 | tbd due to COVID-19 | Singapore | https://2020.gophercon.sg/ <br> CFP: https://www.papercall.io/gopherconsg-2020 |
| GopherConIndia 2020 | tbd due to COVID-19 | Goa, India | https://gopherconindia.com/ <br> CFP: https://www.papercall.io/gci20 |
| All Systems Go | 2020-12-03 | Online | https://allsystemsgo.space
| GopherChina 2020 | 2020-11-21/22 | ShangHai, China | https://www.gopherchina.org |
| GoLab 2020 | 2020-10-19-25 | Online | https://golab.io |
| Go West Online | 2020-10-02 | Online | https://www.gowestconf.com/ |
| ~GopherCon UK~ | ~2020-08-21-23~ | ~London, UK~ | https://www.gophercon.co.uk/ <br> CANCELLED DUE TO COVID-19 |
| GopherCon Russia 2020/2 Online | 2020-08-08-09 | Moscow, Russia | https://www.gophercon-russia.ru/en |
| GopherCon Turkey (Online) | 2020-07-25 | Istanbul, Turkey | https://gophercon.ist/ |
| GopherCon Europe | 2020-07 | Berlin, Germany | https://gophercon.berlin/ |
| GopherCon Africa 2020 | 2020-07-14-16 | Lagos, Nigeria | https://www.gophercon.africa/ |
| GoWayFest 4.0 (online edition) | 2020-07-11-12 | Minsk, Belarus | https://goway.io <br> CFP: https://www.papercall.io/gowayfest4 |
| GoCon Sendai | 2020-07-04| Sendai, Japan | http://sendai.gocon.jp/ |
| ~GoCon Canada~ | ~2020-05-25-26~ | ~Toronto, Canada~ | https://gocon.ca <br> CANCELLED DUE TO COVID-19 |
| GoWest | 2020-05-08| Salt Lake City, UT USA | https://gowestconf.com CFP: https://www.papercall.io/gowestconf |
| GoRemoteFest| 2020-04-26 | [Online](https://www.youtube.com/channel/UCUZnOzWTIeDU8kel4eNNUNw) | https://www.goremotefest.com|
| ~~EU Go Contributor Summit~~| ~~2020-04-23~~ | ~~Berlin, Germany~~ | CANCELLED DUE TO COVID-19 COVID-19 CORONAVIRUS|
| ~~dotGo~~ | ~~2020-03-30~~ | ~~Paris, France~~ | https://2020.dotgo.eu/ <br> CANCELLED DUE TO COVID-19 COVID-19 CORONAVIRUS |
| GopherCon Russia 2020 Online | 2020-03-28 | Moscow, Russia | https://www.gophercon-russia.ru/en |
| ~~Capital Go 2020~~ | ~~2020-03-26-27~~ | ~~McLean, Virginia USA~~ | http://capitalgolang.com <br> CANCELLED DUE TO COVID-19 CORONAVIRUS |
| GopherCon Israel | 2020-02-03 | Tel Aviv, Israel | https://www.gophercon.org.il/ |
| Go Devroom FOSDEM | 2020-02-02 | Brussels, Belgium | https://fosdem.org/2020/schedule/track/go/ |
| GoDays | 2020-01-21-23 | Berlin, Germany | https://www.godays.io/ CFP: https://www.godays.io/cfp |
| | **2019** | | | |
| Gopherpalooza | 2019-11-07-08 | Mountain View, CA USA | http://gopherpalooza.com/ |
| GopherCon Vietnam 2019 | 2019-11-02 | Ho Chi Minh City, Vietnam | https://gophercon.vn|
| Golang Piter | 2019-11-01 | St. Petersburg, Russia | https://golangpiter.com |
| Go Conference Tokyo | 2019-10-28 | Tokyo, Japan | https://gocon.jp/ |
| GoLab 2019 | 2019-10-20-22 | Florence, Italy | https://golab.io |
| GolangConf 2019 | 2019-10-07 | Moscow, Russia | CfP: https://www.papercall.io/golangconf|
| GopherConBR 2019 | 2019-09-27-28 | Florianópolis, Brazil | http://2019.gopherconbr.org |
| OpenGo 2019 | 2019-09-23-25 | Hollywood, FL USA | https://opengo.io/ |
| GopherCon UK | 2019-08-21-23 | London, UK | https://www.gophercon.co.uk/ |
| GopherCon 2019 | 2019-07-24-27 | San Diego, CA USA | https://www.gophercon.com/ |
| GopherShip | 2019-07-20 | Moscow, Russia | https://gophership.ru |
| Go Conference '19 Summer in Fukuoka| 2019-07-13 | Fukuoka, Japan | https://fukuoka.gocon.jp/ |
| GoWayFest 3.0 | 2019-07-05 | Minsk, Belarus | https://goway.io <br> CFP: https://www.papercall.io/gowayfest3 |
| Gophercon Poland | 2019-06-27 | Gdansk, Poland | https://twitter.com/GopherConPL <br> CFP: https://eventil.com/events/GopherConPL/cfp |
| GoGoConf | 2019-06-14 | Krakow, Poland | https://www.gogoconf.rocks <br> CFP: https://www.papercall.io/gogoconf|
| GopherCon Europe | 2019-06-01-05-30 | Tenerife, Canary Islands, Spain | https://www.gophercon.es <br> CFP: https://www.papercall.io/gophercon-eu-2019|
| GoCon Canada | 2019-05-31 | Toronto, Canada | https://gocon.ca<br> CFP: https://www.papercall.io/goconca |
| Go Conference Tokyo | 2019-05-18 | Tokyo, Japan | https://gocon.jp/<br> CFP: https://www.papercall.io/gocon-tokyo-2019 |
| GopherCon Singapore 2019 | 2019-05-03 | Singapore | https://2019.gophercon.sg/<br>CFP: https://www.papercall.io/gopherconsg2019 |
| GopherChina 2019 | 2019-04-27 | China BeiJing | https://gopherchina.org/ |
| GopherCon Russia | 2019-04-13 | Moscow, Russia | https://www.gophercon-russia.ru/en |
| GothamGo | 2019-04-12 | New York City, NY USA | http://gothamgo.com/<br>CFP https://www.papercall.io/gothamgo2019 |
| CodeFest X | 2019-03-30-31 | Novosibirsk, Russia | |
| dotGo 2019 | 2019-03-25 | Paris, France | https://2019.dotgo.eu/ |
| GopherCon Israel | 2019-02-11 | Tel Aviv, Israel | https://www.gophercon.org.il/ |
| Go Devroom FOSDEM | 2019-02-02 | Brussels, Belgium | https://fosdem.org/2019/schedule/track/go/ |
| GoDays | 2019-01-30 | Berlin, Germany | https://www.godays.io/ |
| GopherCon India 2019 | 2019-01-18-19 | Goa, India | https://gopherconindia.com/ |
| | **2018** | | | |
| GopherCon Vietnam 2018 | 2018-12-08 | Ho Chi Minh City, Vietnam | http://gophercon.vn |
| Go Conference Tokyo | 2018-11-25 | Tokyo, Japan | https://gocon.connpass.com/event/109368/ |
| GoGoConf | 2018-10-25 | Krakow, Poland | https://www.gogoconf.rocks |
| GoLab 2018 | 2018-10-22-23 | Florence, Italy | https://golab.io |
| Gopherpalooza 2018 | 2018-10-12 | San Francisco, CA | http://gopherpalooza.com/ |
| Go Stockholm Conference | 2018-10-06 | Stockholm, Sweden | https://www.eventbrite.com/e/go-stockholm-conference-tickets-49325007425 |
| GoWayFest 2.0 | 2018-09-28 | Minsk, Belarus | https://goway.io |
| GopherCon Brasil 2018 | 2018-09-27-29 | Florianópolis, Brazil | https://2018.gopherconbr.org/en<br>CFP https://www.papercall.io/gopherconbrasil2018 |
| GopherCon Denver 2018 | 2018-08-27-30 | Denver, CO | https://www.gophercon.com/<br>Talks: https://www.youtube.com/playlist?list=PL2ntRZ1ySWBdatAqf-2_125H4sGzaWngM<br>Lightning Talks: https://www.youtube.com/playlist?list=PL2ntRZ1ySWBdMEZScpaoRX-vyt6pRUvfM |
| GopherCon UK 2018 | 2018-08-01-03 | London, UK | https://www.gophercon.co.uk/ |
| Go Northwest 2018 | 2018-07-30 | Seattle, WA, USA | http://gonorthwest.io/ |
| GopherCon Europe - Iceland | 2018-06-01-02 | Reykjavik, Iceland | [Talks](https://www.youtube.com/playlist?list=PLtoVuM73AmsJuBoOoI-12WR36nhvtlJ-A&disable_polymer=true)<br>[Website](https://gophercon.is) |
| GopherCon SG 2018 | 2018-05-04 | Singapore | https://2018.gophercon.sg/ |
| GothamGo 2018 | 2018-04-27 | New York, USA | http://gothamgo.com/ |
| Go Conference Tokyo | 2018-04-15 | Tokyo, Japan | https://gocon.connpass.com/event/82515/ |
| GopherCon China 2018 | 2018-04-14-15 | Shanghai, China | http://www.gopherchina.org/ |
| GopherCon Russia 2018 | 2018-03-17 | Moscow, Russia | http://gophercon-russia.ru/en<br>https://github.com/GopherConRu/talks |
| GopherCon India 2018 | 2018-03-09-10 | Pune, India | http://www.gophercon.in/ |
| Go Devroom FOSDEM 2018 | 2018-02-03-04 | Brussels, Belgium | https://fosdem.org/2018/schedule/track/go/ |
| | **2017** | | | |
| GopherCon Brasil 2017 | 2017-11-17-19 | Florianópolis, Brazil | https://2017.gopherconbr.org/en |
| dotGo | 2017-11-06 | Paris, France | https://www.dotgo.eu |
| Go Conference Tokyo | 2017-11-05 | Tokyo, Japan | https://gocon.connpass.com/event/66615/ |
| GothamGo | 2017-10-05-06 | New York, USA | http://gothamgo.com/ |
| Golang UK | 2017-08-16-18 | London, UK | https://golanguk.com |
| GopherCon Denver | 2017-07-12-15 | Denver, CO | http://gophercon.com |
| GopherCon Singapore 2017 | 2017-05-25-26 | Singapore | https://2017.gophercon.sg |
| Capital Go Language Conference | 2017-04-24-25 | Washington, DC | http://www.capitalgolang.com/ |
| GopherChina 2017 | 2017-04-15-16 | Shanghai | http://www.bagevent.com/event/357764 |
| Go Conference Tokyo | 2017-03-25 | Tokyo, Japan |https://gocon.connpass.com/event/52441/ |
| GopherCon India 2017 | 2017-02-24-25 | Pune, India | http://www.gophercon.in/
| Go Devroom FOSDEM | 2017-02-05 | Brussels, Belgium | https://fosdem.org/2017/schedule/track/go/ |
| GoLab | 2017-01-20-21 | Florence, Italy | http://golab.io |
| | **2016** | | | |
| GothamGo | 2016-11-18 | New York, USA | http://gothamgo.com/ |
| GopherCon Brasil | 2016-11-04-05 | Florianópolis, Brazil | https://2016.gopherconbr.org/en/ |
| dotGo | 2016-10-10 | Paris, France | http://2016.dotgo.eu |
| Golang UK | 2016-08-18 | London, UK | http://golanguk.com |
| GopherCon Denver | 2016-07-11 | Denver, CO | http://gophercon.com |
| Gopherfest | 2016-05-16 | San Francisco, USA | http://www.gopherfest.org/ |
| Go Conference Tokyo | 2016-04-23 | Tokyo, Japan | http://gocon.connpass.com/event/27521/ |
| Gopher China | 2016-04-16 | Beijing, China | http://www.gopherchina.org |
| GopherCon Dubai | 2016-02-23 | Dubai, UAE | http://www.gophercon.ae |
| GopherCon India | 2016-02-19 | Bengaluru, India | [videos](https://www.youtube.com/watch?v=4Dr8FXs9aJM&list=PLxFC1MYuNgJT_ynbXGuYAZbSnUnq-6VQA) |
| FOSDEM | 2016-01-30 | Brussels, Belgium | https://video.fosdem.org/2016/h1302/ |
| Gopher Gala | 2016-01-22 | Earth | |
| | **2015** | | |
| GoLab | 2015-12-15 | Florence, Italy | http://golab.io |
| Go Conference Tokyo | 2015-12-06 | Tokyo, Japan | https://gocon.connpass.com/event/22930/ |
| GopherFest SV | 2015-11-18 | Facebook, Menlo Park, CA | [videos](https://www.youtube.com/playlist?list=PLtLJO5JKE5YALxdnGgvgwxTSmANOvyAo9) |
| dotGo | 2015-11-09 | Paris, France | [videos](https://www.youtube.com/playlist?list=PLMWwKlp9xoYX4mlNDdkCOfsUG_40WCMCX) |
| GothamGo | 2015-10-02 | NY, NY | [videos](https://www.youtube.com/playlist?list=PLeGxIOPLk9ELh9tsPZMzau6CzMjfMzp9-) |
| GolangUK | 2015-08-21 | London, UK | [videos](https://www.youtube.com/playlist?list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd) |
| GopherCon Denver | 2015-07-07 | Denver, CO | [keynotes](https://www.youtube.com/playlist?list=PL2ntRZ1ySWBf-_z-gHCOR2N156Nw930Hm), [lightning](https://www.youtube.com/playlist?list=PL2ntRZ1ySWBeHqlHM8DmvS8axgbrpvF9b) |
| Go Conference Tokyo | 2015-06-20 | Tokyo, Japan | https://gocon.connpass.com/event/14063/ |
| GopherfestSF | 2015-06-25 | San Francisco, CA | [videos](https://www.youtube.com/playlist?list=PLtLJO5JKE5YB55ExLApKU0S8_eN5eaGkU) |
| GopherCon India | 2015-03-17 | Bengaluru, India | [videos](https://www.youtube.com/playlist?list=PLxFC1MYuNgJTY3uQ5Ja4F5Sz305nnrBOq) |
| Go Devroom FOSDEM | 2015-03-04 | Brussels, Belgium | [videos](https://www.youtube.com/playlist?list=PLtLJO5JKE5YDK74RZm67xfwaDgeCj7oqb) |
| Gopher China | 2015-04-25 | Shanghai, China | |
| London Go Gathering | 2015-02-03 | London, UK | [videos](https://www.youtube.com/playlist?list=PLtLJO5JKE5YCZYDAt8-uyJbVgq1FIUpVM)|
| | **2014** | | |
| Go Conference Tokyo | 2014-11-30 | Tokyo, Japan | https://gocon.connpass.com/event/9748/ |
| GothamGo | 2014-11-15 | NYC, NY | [videos](https://vimeo.com/channels/852217) |
| dotGo | 2014-09-10 | Paris, France | [videos](https://www.youtube.com/playlist?list=PLMW8Xq7bXrG58Qk-9QSy2HRh2WVeIrs7e) |
| Go Devroom FOSDEM | 2014-06-30 |Brussels, Belgium | [videos](https://www.youtube.com/playlist?list=PLtLJO5JKE5YDKG4WcaNts3IVZqhDmmuBH) |
| Go Conference Tokyo | 2014-05-31 | Tokyo, Japan | https://gocon.connpass.com/event/6370/ |
| GopherCon Denver | 2014-04-24 | Denver, CO | [videos](https://www.youtube.com/playlist?list=PL2ntRZ1ySWBcD_BiJiDJUcyrb2w3bTulF) |
| | **2013** | | |
| Go Conference Tokyo | 2013-10-14 | Tokyo, Japan | https://gocon.connpass.com/event/3510/ |
| Go Conference Tokyo | 2013-04-13 | Tokyo, Japan | https://gocon.connpass.com/event/1906/ |

51
Configuring-GoLand-for-WebAssembly.md

@ -1,51 +1,4 @@
### [← Back](https://github.com/golang/go/wiki/WebAssembly) to the main WebAssembly page. The Go wiki on GitHub has moved to go.dev (#61940).
# Configuring GoLand for WebAssembly (Wasm) projects Try <https://go.dev/wiki/Configuring-GoLand-for-WebAssembly> or <https://go.dev/wiki/>.
## Initial project configuration
When you first open or start a WebAssembly project in GoLand, it won't understand the "*syscall/js*" package.
That's easily fixable, by changing the **GOOS** and **GOARCH** values in the project settings, as per the screenshots below.
![GoLand Wasm Setup pic1](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Setup1.png)
**Note** - The screenshot below shows how to access **Settings** on a Linux desktop. If you're using macOS, you'll probably need to access them through the standard macOS **Preferences** option.
![GoLand Wasm Setup pic2](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Setup2.png)
![GoLand Wasm Setup pic3](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Setup3.png)
![GoLand Wasm Setup pic4](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Setup4.png)
## Configuring Run/Debug settings
With the initial project settings changed, you'll probably want to configure the Run/Debug settings next.
That will let you recompile the .wasm file by just launching `Run` (<kbd>Shift</kbd>+<kbd>F10</kbd> on Linux).
![GoLand Wasm Build pic2](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build2.png)
![GoLand Wasm Build pic3](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build3.png)
![GoLand Wasm Build pic4](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build4.png)
![GoLand Wasm Build pic5](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build5.png)
![GoLand Wasm Build pic6](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build6.png)
![GoLand Wasm Build pic7](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build7.png)
![GoLand Wasm Build pic8](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build8.png)
![GoLand Wasm Build pic9](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build9.png)
![GoLand Wasm Build pic10](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build10.png)
![GoLand Wasm Build pic11](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build11.png)
![GoLand Wasm Build pic12](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build12.png)
Finished, your GoLand setup should now be complete.
### [← Back](https://github.com/golang/go/wiki/WebAssembly) to the main WebAssembly page.

9
Contributing-to-gopls.md

@ -1,5 +1,4 @@
--- The Go wiki on GitHub has moved to go.dev (#61940).
> This page has been subsumed into the [committed markdown](https://github.com/golang/tools/blob/master/gopls/doc/contributing.md) of x/tools repository
> Try <https://go.dev/wiki/Contributing-to-gopls> or <https://go.dev/wiki/>.
> Please do not edit this page!
---

150
CoreDumpDebugging.md

@ -1,150 +1,4 @@
Originally published at https://rakyll.org/coredumps/. The Go wiki on GitHub has moved to go.dev (#61940).
--- Try <https://go.dev/wiki/CoreDumpDebugging> or <https://go.dev/wiki/>.
Debugging is highly useful to examine the execution flow
and to understand the current state of a program.
A core file is a file that contains the memory dump of a running
process and its process status. It is primarily used for post-mortem
debugging of a program, as well as to understand a program's state
while it is still running. These two cases make debugging of core dumps
a good diagnostics aid to postmortem and analyze production
services.
I will use a simple hello world web server in this article,
but in real life our programs might get very
complicated easily.
The availability of core dump analysis gives you an
opportunity to resurrect a program from specific snapshot
and look into cases that might only reproducible in certain
conditions/environments.
__Note__: This flow only works on Linux at this point end-to-end,
I am not quite sure about the other Unixes but it is not
yet supported on macOS. Windows is not supported at this point.
Before we begin, you need to make sure that your ulimit
for core dumps are at a reasonable level. It is by default
0 which means the max core file size can only be zero.
I usually set it to unlimited on my development machine by typing:
```
$ ulimit -c unlimited
```
Then, make sure you have [delve](https://github.com/derekparker/delve)
installed on your machine.
Here is a `main.go` that contains a simple handler and it starts an HTTP server.
```
$ cat main.go
package main
import (
"fmt"
"log"
"net/http"
)
func main() {
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, "hello world\n")
})
log.Fatal(http.ListenAndServe("localhost:7777", nil))
}
```
Let's build this and have a binary.
```
$ go build .
```
Let’s assume, in the future, there is something messy going on with
this server but you are not so sure about what it might be.
You might have instrumented your program in various ways but it
might not be enough for getting any clue from the existing
instrumentation data.
Basically, in a situation like this, it would be nice to have a
snapshot of the current process, and then use that snapshot to dive
into to the current state of your program with your existing debugging
tools.
There are several ways to obtain a core file. You might have been
already familiar with crash dumps, these are basically core dumps
written to disk when a program is crashing. Go doesn't enable crash dumps
by default but gives you this option on Ctrl+backslash when
`GOTRACEBACK` env variable is set to "crash".
```
$ GOTRACEBACK=crash ./hello
(Ctrl+\)
```
It will crash the program with stack trace printed and core dump file
will be written.
Another option is to retrieve a core dump from a running process
without having to kill a process.
With `gcore`, it is possible to get the core
files without crashing. Let’s start the server again:
```
$ ./hello &
$ gcore 546 # 546 is the PID of hello.
```
We have a dump without crashing the process. The next step
is to load the core file to delve and start analyzing.
```
$ dlv core ./hello core.546
```
Alright, this is it! This is no different than the typical delve interactive.
You can backtrace, list, see variables, and more. Some features will be disabled
given a core dump is a snapshot and not a currently running process, but
the execution flow and the program state will be entirely accessible.
```
(dlv) bt
0 0x0000000000457774 in runtime.raise
at /usr/lib/go/src/runtime/sys_linux_amd64.s:110
1 0x000000000043f7fb in runtime.dieFromSignal
at /usr/lib/go/src/runtime/signal_unix.go:323
2 0x000000000043f9a1 in runtime.crash
at /usr/lib/go/src/runtime/signal_unix.go:409
3 0x000000000043e982 in runtime.sighandler
at /usr/lib/go/src/runtime/signal_sighandler.go:129
4 0x000000000043f2d1 in runtime.sigtrampgo
at /usr/lib/go/src/runtime/signal_unix.go:257
5 0x00000000004579d3 in runtime.sigtramp
at /usr/lib/go/src/runtime/sys_linux_amd64.s:262
6 0x00007ff68afec330 in (nil)
at :0
7 0x000000000040f2d6 in runtime.notetsleep
at /usr/lib/go/src/runtime/lock_futex.go:209
8 0x0000000000435be5 in runtime.sysmon
at /usr/lib/go/src/runtime/proc.go:3866
9 0x000000000042ee2e in runtime.mstart1
at /usr/lib/go/src/runtime/proc.go:1182
10 0x000000000042ed04 in runtime.mstart
at /usr/lib/go/src/runtime/proc.go:1152
(dlv) ls
> runtime.raise() /usr/lib/go/src/runtime/sys_linux_amd64.s:110 (PC: 0x457774)
105: SYSCALL
106: MOVL AX, DI // arg 1 tid
107: MOVL sig+0(FP), SI // arg 2
108: MOVL $200, AX // syscall - tkill
109: SYSCALL
=> 110: RET
111:
112: TEXT runtime·raiseproc(SB),NOSPLIT,$0
113: MOVL $39, AX // syscall - getpid
114: SYSCALL
115: MOVL AX, DI // arg 1 pid
```

86
Courses.md

@ -1,86 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
Go is a great language for CS majors. This page presents some university courses that use Go. For a list of free and commercial Go training classes, see [the Learn wiki](Learn). Try <https://go.dev/wiki/Courses> or <https://go.dev/wiki/>.
# Language
* University of Helsinki, Department of Computer Science used to have a course named Introduction to Go, taught by K. Bäckman: http://www.cs.helsinki.fi/courses/582336 in Spring 2010.
* University of Sofia "St. Kliment Ohridski", Faculty of Mathematics and Informatics has elective course named "Programming with Go", taught by K. Vladimiroff: http://fmi.golang.bg (bulgarian) and their [[public lectures](https://github.com/fmi/go-lectures)] - (also in bulgarian)
* Free University of Berlin (Germany) had a course [Introduction to Go Programming](http://w3.inf.fu-berlin.de/lehre/WS12/go/) in Spring 2013.
* J.W. Goethe University (Frankfurt/Main, Germany) had a course [Introduction to Go Programming](http://www.sepl.informatik.uni-frankfurt.de/2014-ws/b-ps2/index.de.html) in Spring 2015 (in german)
* University of Pennsylvania had a course on [Go Programming](https://www.seas.upenn.edu/~cis193/) in Spring 2017.
* SUNY Potsdam (Potsdam, NY) "Selected languages course with Go", taught by Dr. Brian C. Ladd (Associate Professor of Computer Science). First class in Spring 2017
* University of Milan has a course named "Computer Programming" taught by Paolo Boldi: http://boldi.di.unimi.it/Corsi/Inf2018/
* University of Zagreb (Croatia), Faculty of Electrical Engineering and Computing, has an ongoing course [Go programming language](https://www.fer.unizg.hr/en/course/gpl) since 2020, held by Z. Bratković and B. Banelli. Videos available from academic year [2019./2020.](https://www.youtube.com/watch?v=mq18_oSNkHE&list=PLDG0WuJlyEw3GuJ4FAoP-ea8PCsU5J-9K&pp=iAQB) and [2020./2021.](https://www.youtube.com/watch?v=Ms_5seF6Smg&list=PLDG0WuJlyEw1o7cQ7Raf_SHgak4G57zCW&pp=iAQB) (Croatian)
# Programming Concepts
* President University (Cikarang, West Java, Indonesia) had a course [Programming Concepts](http://president.ac.id/study/undergraduate/school-of-computer-science/information-technology) for every junior students (using C, Go and Javascript).
# Web
* CS 4830: Science and Engineering of the WWW taught by Ryanne Dolan at University of Missouri: http://4830.ryannedolan.info/
* CSCI 130: Web Programming taught by [Todd McLeod](https://www.udemy.com/user/toddmcleod/) at California State University Fresno
* CSCI 194: Adv. Web Programming taught by [Todd McLeod](https://www.udemy.com/user/toddmcleod/) at California State University Fresno
* CIT 90: Data Drive Websites taught by [Todd McLeod](https://www.udemy.com/user/toddmcleod/) at Fresno City College
* CIT 94: Server Side Scripting taught by [Todd McLeod](https://www.udemy.com/user/toddmcleod/) at Fresno City College
# Concurrency
* Go is being used at the end of a yearlong freshman computer science class at KTH: http://yourbasic.org/golang/concurrent-programming/
* Go, Concurrent and Systems Programming from Rochester Institute of Technology: http://www.cs.rit.edu/~ats/go-2011-2/index.xml
* Free University of Berlin (Germany) had a course on [Concurrent Programming](http://w3.inf.fu-berlin.de/lehre/SS13/alp4/) with Go as a reference language in 2013.
* University of Duisburg-Essen (Germany) had a lecture about Go and CSP within their course on [Concurrent systems modelling](http://www.ti.inf.uni-due.de/teaching/ss2014/mod_ns/) in summer 2014. [[Slides](http://www.ti.inf.uni-due.de/fileadmin/public/teaching/mod_ns/folien/SS2014/google-go-2x2.pdf)]
* University of Stavanger, Norway. We use Go to teach concurrency principles in DAT320 Operating Systems. http://www.uis.no/studies/study-courses/?code=DAT320_1&parentcat=9835
* University of Tromsø, Norway. [Concurrent and Data-Intensive Programming (INF-2200)](https://uit-inf-2202-f16.github.io/).
* University of Victoria (Canada) used Go in the section on Concurrency as a part of [Programming Languages (CSC 330)](https://heat.csc.uvic.ca/coview/course/2017091/CSC330)
# Distributed Computing
* Distributed Computer Systems (CS 138) at Brown: http://cs.brown.edu/courses/cs138/s16/syllabus.html
* Distributed Systems course (COS 418) at Princeton: https://www.cs.princeton.edu/courses/archive/fall16/cos418/
* Distributed Systems course (15-440) at CMU: http://www.cs.cmu.edu/~dga/15-440/F12/index.html (see also http://da-data.blogspot.se/2013/02/teaching-distributed-systems-in-go.html)
* 6.824 Distributed Systems at MIT is using Go in its labs: http://pdos.csail.mit.edu/6.824/.
* CSE 223B, Spring 2014: Distributed Computing and Systems at UC San Diego http://cseweb.ucsd.edu/classes/sp14/cse223B-a/index.html
* Dixie State University teaches Go in an introductory course to programming languages and later on in distributed systems.
* CS 352, Computer Organization and Design, at the University of Wisconsin, Eau Claire: http://cs.uwec.edu/~buipj/teaching/cs.352.f13/lab_01_high_performance_computing.html
* KTH Stockholm uses Go to teach concurrency: DD1396 Parallel and Concurrent Programming. https://www.kth.se/student/kurser/kurs/DD1396
* Norwegian University of Science and Technology: TTK4145 Real-Time Programming http://www.itk.ntnu.no/fag/TTK4145/information/
* University of Stavanger, Norway. We use Go to build a replicated state machine based on Paxos in DAT520 Distributed Systems. http://www.uis.no/studies/study-courses/?code=DAT520_1&parentcat=9835
* Moscow State University, Russia. Go is used in graduate course on "Selected Topics in Distributed Systems Engineering"
* D7024E - Mobile and Distributed Computing Systems at Luleå University of Technology. Go is used to implement the DHT algorithm Chord and create a data replication system. http://www.ltu.se/edu/course/D70/D7024E/D7024E-Mobila-och-distribuerade-datorsystem-1.67844?l=en&kursView=kursplan
* University of Tromsø, Norway. [Distributed Systems Fundamentals (INF-3200)](https://uit.no/education/courses/course?p_document_id=291961) and [Advanced Distributed Systems (INF-3203)](https://uit.no/education/courses/course?p_document_id=292883).
# Networking
* Computer Networking (COS 461) at Princeton: http://www.cs.princeton.edu/courses/archive/spring16/cos461/ (See Assignment 1 https://github.com/PrincetonUniversity/COS461-Spring2016/tree/master/notebook/assignment1 and Assignment 4 http://www.cs.princeton.edu/courses/archive/spring16/cos461/assignments/.
# Compiler Design
* Compiler Design (CS712/CS812) at the University of New Hampshire: http://www.cs.unh.edu/~cs712/. In Fall 2016 we are compiling a subset of Go to LLVM code.
* Introduction to Compilers (6197, Spanish) at Rey Juan Carlos University of Madrid: http://lsub.org/comp. Students write a compiler in Go that implements a language for drawing graphics.
# Security
* [Learn Cryptography in Go](https://boot.dev/learn/learn-cryptography) on Boot.dev. A code-in-the-browser course where cryptography principles are taught in the Go language.
* [Computer Systems Security](https://cs.brown.edu/courses/cs166/) (CS166) At Brown University. In particular, the final [Dropbox Project](https://cs.brown.edu/courses/cs166/files/assignments/dropbox.pdf).

26
CreatingSubRepository.md

@ -1,26 +1,4 @@
This page outlines the steps that need to be done to create a new golang.org/x repository, in order for it to have the same properties as all existing golang.org/x repositories: The Go wiki on GitHub has moved to go.dev (#61940).
- a golang.org/x redirect
- automatic git mirroring from Gerrit to GitHub
- automatic importing of GitHub PRs into Gerrit CLs
## Steps Try <https://go.dev/wiki/CreatingSubRepository> or <https://go.dev/wiki/>.
1. Create a new empty Gerrit repository at https://go.googlesource.com, complete with a description.
- Create an initial commit with `LICENSE`, `PATENTS`, `CONTRIBUTING.md`, and `README.md` files and push it directly to the Gerrit repository. See [example commit](https://go.googlesource.com/govulncheck-action/+/a197ae39e55573b3a0e752b9bd72f457a458adf6).
- See the internal team instructions at go/go-gerrit#new-repository for how to create a repository.
2. Create a [new empty GitHub repository](https://github.com/organizations/golang/repositories/new) at https://github.com/golang with the same name and description.
- Turn off Wikis, Issues, Projects in repository settings.
- On "Manage access" tab:
- Add "golang org admins" team with Admin access.
- Add "gophers" team with Write access.
- Add "robots" team with Write access (can only be done by a maintainer of golang organization; ask someone else if you're not).
3. Modify the `x/build/repos` package.
4. Update x/website's version of x/build to include modified `x/build/repos` package.
5. Redeploy all affected commands (or ask an x/build [owner](https://dev.golang.org/owners) to deploy if you're not; the order shouldn't matter):
1. `x/build/cmd/gitmirror`
2. `x/build/maintner/maintnerd`
- Note that it's expected for the new repo not to appear in maintner until first issue or PR is created (see [#25744](https://go.dev/issue/25744)).
3. `x/build/cmd/gerritbot`
4. `x/build/cmd/coordinator`
5. `x/website/cmd/golangorg`
6. You're done.

99
CustomPprofProfiles.md

@ -1,99 +1,4 @@
Originally published at https://rakyll.org/custom-profiles/. The Go wiki on GitHub has moved to go.dev (#61940).
---- Try <https://go.dev/wiki/CustomPprofProfiles> or <https://go.dev/wiki/>.
Go provides several pprof profiles out of the box to gather
profiling data from Go programs.
The builtin profiles provided by the [runtime/pprof](https://pkg.go.dev/runtime/pprof/) package:
* **profile**: CPU profile determines where a program spends its time while actively consuming CPU cycles (as opposed while sleeping or waiting for I/O).
* **heap**: Heap profile reports the currently live allocations; used to monitor current memory usage or check for memory leaks.
* **threadcreate**: Thread creation profile reports the sections of the program that lead the creation of new OS threads.
* **goroutine**: Goroutine profile report the stack traces of all current goroutines.
* **block**: Block profile show where goroutines block waiting on synchronization primitives (including timer channels). Block profile is not enabled by default; use runtime.SetBlockProfileRate to enable it.
* **mutex**: Mutex profile reports the lock contentions. When you think your CPU is not fully utilized due to a mutex contention, use this profile. Mutex profile is not enabled by default, see runtime.SetMutexProfileFraction to enable.
Additional to the builtin profiles, [runtime/pprof](https://pkg.go.dev/runtime/pprof/) package allows you to export your custom profiles, and instrument your code to record
execution stacks that contributes to this profile.
Imagine we have a blob server, and we are writing a Go client for it. And our users want to be able to profile the opened blobs on the client. We can create a profile and record the events of blob opening and closing, so the user can tell how many open blobs they are at any time.
Here is a blobstore package that allows you to open some blobs. We will create a new custom profile and start
recording execution stacks that contributes to opening of blobs:
``` go
package blobstore
import "runtime/pprof"
var openBlobProfile = pprof.NewProfile("blobstore.Open")
// Open opens a blob, all opened blobs need
// to be closed when no longer in use.
func Open(name string) (*Blob, error) {
blob := &Blob{name: name}
// TODO: Initialize the blob...
openBlobProfile.Add(blob, 2) // add the current execution stack to the profile
return blob, nil
}
```
And once users want to close the blob, we need to remove the execution stack associated with the current blob from the profile:
```go
// Close closes the blob and frees the
// underlying resources.
func (b *Blob) Close() error {
// TODO: Free other resources.
openBlobProfile.Remove(b)
return nil
}
```
And now, from the programs using this package, we should be able to retrieve `blobstore.Open` profile data and use our daily pprof tools to examine and visualize them.
Let's write a small main program than opens some blobs:
```
package main
import (
"fmt"
"math/rand"
"net/http"
_ "net/http/pprof" // as a side effect, registers the pprof endpoints.
"time"
"myproject.org/blobstore"
)
func main() {
for i := 0; i < 1000; i++ {
name := fmt.Sprintf("task-blob-%d", i)
go func() {
b, err := blobstore.Open(name)
if err != nil {
// TODO: Handle error.
}
defer b.Close()
// TODO: Perform some work, write to the blob.
}()
}
http.ListenAndServe("localhost:8888", nil)
}
```
Start the server, then use go tool to read and visualize the profile data:
```
$ go tool pprof http://localhost:8888/debug/pprof/blobstore.Open
(pprof) top
Showing nodes accounting for 800, 100% of 800 total
flat flat% sum% cum cum%
800 100% 100% 800 100% main.main.func1 /Users/jbd/src/hello/main.go
```
You will see that there are 800 open blobs and all openings are coming from main.main.func1. In this small example, there is nothing more to see, but in a complex server you can examine the hottest spots that works with an open blob and find out bottlenecks or leaks.

21
Darwin.md

@ -1,21 +1,4 @@
# Go on Darwin The Go wiki on GitHub has moved to go.dev (#61940).
| **Kernel version** | **Distributions** | **Architectures** | **Initial support version** | **Final support version** | Try <https://go.dev/wiki/Darwin> or <https://go.dev/wiki/>.
|:-------------------|:--------------------------------|:-----------------------|:---------------|:----------|
| 18 | macOS Mojave 10.14, iOS 12 | amd64, arm64, 386 | Go 1.12 | |
| 17 | macOS High Sierra 10.13, iOS 11 | amd64, arm64, 386 | Go 1.7.1 _***_ | |
| 16 | macOS Sierra 10.12, iOS 10 | amd64, arm, arm64, 386 | Go 1.7.1 _**_ | |
| 15 | OS X El Capitan 10.11 | amd64, 386 | Go 1 _*_ | |
| 15 | iOS 9 | arm, arm64 | Go 1.5 | |
| 14 | OS X Yosemite 10.10 | amd64, 386 | Go 1 _*_ | |
| 14 | iOS 7, iOS 8 | arm, arm64 | Go 1.5 | |
| 13 | OS X Mavericks 10.9 | amd64, 386 | Go 1 _*_ | Go 1.10.8 |
| 12 | OS X Mountain Lion 10.8 | amd64, 386 | Go 1 _*_ | Go 1.10.8 |
| 11 | OS X Lion 10.7 | amd64, 386 | Go 1 _*_ | Go 1.7.6 |
| 10 | Mac OS X Snow Leopard 10.6 | amd64, 386 | Go 1 | Go 1.4.3 |
_*_ Go 1.5 or above is recommended.
_**_ See https://github.com/golang/go/issues/16570 and https://github.com/golang/go/issues/19772.
_***_ See https://github.com/golang/go/issues/22037.

105
DashboardBuilders.md

@ -1,105 +1,4 @@
# Table of contents The Go wiki on GitHub has moved to go.dev (#61940).
1. [Coordinator Builders](#coordinator-builders)
1. [How to set up a builder](#how-to-set-up-a-builder)
1. [Builder Requirements](#builder-requirements)
1. [Security notes](#security-notes)
2. [LUCI Builders](#luci-builders)
1. [How to set up a builder](#how-to-set-up-a-builder-1)
1. [Builder Requirements](#builder-requirements-1)
# Coordinator Builders
Build configs (at the top) and host configs (bottom) are listed here:
https://farmer.golang.org/builders
A builder runs on a certain host type. (e.g. `linux-386-387` is a build type. It runs on `host-linux-kubestd`, a Kubernetes-based linux/amd64 host)
They come from the file https://github.com/golang/build/blob/master/dashboard/builders.go
For design details about the coordinator, see https://go.dev/s/builderplan
Information about builder machines, how many are running and their status can be found at https://farmer.golang.org/
## How to set up a builder
1. Talk to golang-dev@ to get a builder host type & hash (they can get one from using the `golang.org/x/build/cmd/genbuilderkey` tool), and put that in ` ~/.gobuildkey` or `~/.gobuildkey-host-foo-bar` or the file pointed to by env var `$GO_BUILD_KEY_PATH`.
1. Define your new builder in https://github.com/golang/build/blob/master/dashboard/builders.go with a new HostConfig and BuildConfig.
1. Have golang-dev deploy the build coordinator rebuilt with the dashboard/builders.go change
1. Have golang-dev modify golang.org/x/build/cmd/buildlet/Makefile to add your port and to uploads its buildlet binary to Google Cloud Storage (you can do this step out of order if your compiler changes aren't yet upstream)
1. Verify you can see the new host & build configs at https://farmer.golang.org/builders
1. (Interm/testing step) Test that your builder key works and you can register:
1. `go get -u golang.org/x/build/cmd/buildlet`
1. `buildlet -coordinator=farmer.golang.org -reverse-type=host-foo-bar -reboot=false`
1. verify it shows up at https://farmer.golang.org/#pools in "Reverse pool summary" and "Reverse pool machine detail"
1. Modify the golang.org/x/build/cmd/buildlet/stage0 binary if/as needed to pass the right flags to the buildlet binary.
1. Put your stage0 binary on your builder, run in a loop under your operating system's process supervisor (systemd, etc). The stage0 binary is responsible for conditionally re-downloading the buildlet binary from Google Cloud Storage for each build. (This lets us evolve the build system without involving each machine owner)
For WIP ports, the steps above can be done out of order as needed. But as a port matures, be sure each step above is done. In particular, make sure that you're not just running a fixed copy of the buildlet binary in a loop forever. We need to be able to update it over time without your involvement. You should be running the stage0 binary (or equivalent shell script or similar for your platform) in a loop instead.
## Builder Requirements
* Internet connection (at least be able to access Google and https://farmer.golang.org)
* Preferably two or more (V)CPUs
* At least 512MiB of memory (1GB or more highly recommended. 512MB might need a small `GOGC` setting to avoid thrashing.)
## Security notes
Generally, community-run builders only run code that's already been reviewed & submitted. We only enable pre-submit testing for builders run by the Go team that have a lot of hardware available. However, the [Gomote tool](https://go.dev/wiki/Gomote) is available for a number of people on the Go team and in the Go community that lets them have arbitrary access to the builders for development & debugging.
For paranoia reasons, you might want to run your builder in an isolated network that can't access any of your internal resources.
# LUCI Builders
The Go team is migrating the testing pipeline from a custom solution, the coordinator, to [LUCI](https://chromium.googlesource.com/chromium/src/+/master/docs/tour_of_luci_ui.md). [LUCI](https://chromium.googlesource.com/chromium/src/+/master/docs/tour_of_luci_ui.md) is an open source continuous integration system created by the Chrome open source team at Google. The Go team has adopted the use of LUCI in order to leverage a continuous integration solution which is used and supported by a larger group of developers. This should enable the team to provide a more featureful solution to the community.
The LUCI system requires builders to run two applications which authenticate to LUCI and receive and process builds. LUCI token daemon generates a token needed to authenticate. The swarming bot uses the token to connect to LUCI and process builds.
## Builder Requirements
* An internet connection with the ability to connect to:
- https://proxy.golang.org (or an alternative proxy via GOPROXY).
- https://luci-token-server.appspot.com
- https://chromium-swarm.appspot.com
- https://cr-buildbucket.appspot.com
- https://7419-34ac013-dot-chromium-swarm.appspot.com (possible changed in the future?)
- https://remotebuildexecution.googleapis.com
* Resources
- At least 512MB of memory. 1GB or more is highly recommended.
- 20GB disk space is ideal.
- Preferably with 2 or more (V)CPUs.
* Python3 installed and in the `PATH`.
* Permissions
- The bot should be run as the `swarming` user (without root rights).
- The bot automatically updates itself. It should have permissions to do so.
- The bot periodically restarts the machine. It should have permissions to do so (via sudo).
- Under Docker, you can replace the shutdown command with a [shell script that restarts the container](https://chromium.googlesource.com/infra/infra/+/main/docker/swarm_docker/README.md#shutting-container-down-from-within) ([example](https://cs.opensource.google/go/x/build/+/master:cmd/buildlet/stage0/run-worker.sh)).
- If the machine can't be restarted for some reason, set the environment variable `SWARMING_NEVER_REBOOT`.
## How to set up a builder
1. [Create an issue](https://github.com/golang/go/issues/new?labels=new-builder&title=x%2Fbuild%3A+add+LUCI+%3Cos-arch%3E+builder) on the Go Issue tracker requesting the addition of a new builder and assign it yourself.
1. The title of the issue should be in the format: `x/build: add LUCI <os-arch> builder`.
1. Choose a hostname.
1. Add the label "new-builder". (You can post a comment on the issue stating `@gopherbot, please add label new-builder.` in the issue to have [gopherbot](https://go.dev/wiki/gopherbot) add it for you.)
1. Use `golang.org/x/build/cmd/genbotcert` to generate both a certificate signing request (_hostname_.csr) and a TLS private key (_hostname_.key) using the hostname (chosen beforehand) as input. Add a .txt file extension to the certificate signing request (_hostname_.csr.txt) and attach it to the GitHub issue. A team member will attach the resulting certificate (_hostname_.cert) to the GitHub issue.
1. `genbotcert -bot-hostname <hostname>`
1. A Go team member will define your new builder in [LUCI](https://chromium.googlesource.com/chromium/src/+/master/docs/tour_of_luci_ui.md). A comment will be added to the issue when this is completed.
1. The Machine Token Daemon communicates with the Token Server to generate and renew a LUCI machine token. Install `go.chromium.org/luci/tokenserver/cmd/luci_machine_tokend` and configure it to run every 10 minutes via cron. The private key shouldn't be readable by the `swarming` user, so the cron job should run as a separate user.
1. `luci_machine_tokend -backend luci-token-server.appspot.com -cert-pem <path-to-the-certificate> -pkey-pem <path-to-the-private-key> -token-file=/var/lib/luci_machine_tokend/token.json`
1. If /var/lib isn't a suitable place for the token, change it as you see fit and pass `-token-file-path` to `bootstrapswarm` below to match.
1. Install `golang.org/x/build/cmd/bootstrapswarm` and configure it to run in a loop under your operating system's process supervisor (systemd, etc) as the `swarming` user. `Bootstrapswarm` downloads the initial version of the swarming bot and ensures that it is always running.
1. `bootstrapswarm -hostname <hostname>`
1. Verify the bot starts up without any errors in the logs.
Try <https://go.dev/wiki/DashboardBuilders> or <https://go.dev/wiki/>.

55
Deprecated.md

@ -1,55 +1,4 @@
Sometimes an API feature such as a struct field, function, type, or even a whole package becomes The Go wiki on GitHub has moved to go.dev (#61940).
redundant or unnecessary.
When we want to discourage new programs from using it,
we mark that feature "deprecated".
In contrast to some other systems, an API feature being deprecated Try <https://go.dev/wiki/Deprecated> or <https://go.dev/wiki/>.
_does not_ mean it is going to be removed in the future.
On the contrary, [Go 1 compatibility](https://go.dev/doc/go1compat)
means the feature will be preserved in its deprecated form
to keep existing programs running.
To signal that an identifier should not be used, add a paragraph to its doc
comment that begins with `Deprecated:` followed by some information about the
deprecation, and a recommendation on what to use instead, if applicable.
The paragraph does not have to be the last paragraph in the doc comment.
[Some tools will warn on use of deprecated identifiers](https://staticcheck.io/docs/checks#SA1019)
and their docs [are hidden on pkg.go.dev](https://go.dev/issue/40850).
If function `F1` is being replaced by function `F2`
and the first release in which `F2` is available is Go 1.N,
then an official deprecation notice for `F1` should not be
added until Go 1.N+1.
This ensures that Go developers only see `F1` as deprecated
when all supported Go versions include `F2` and they can easily switch.
Marking an API feature deprecated can create work and
decisions for millions of Go developers using the feature.
Deprecating an API feature is an API change that must
be discussed using [the proposal process](https://go.dev/s/proposal).
## Examples
```Go
type ResponseRecorder struct {
// HeaderMap contains the headers explicitly set by the Handler.
// It is an internal detail.
//
// Deprecated: HeaderMap exists for historical compatibility
// and should not be used. To access the headers returned by a handler,
// use the Response.Header map as returned by the Result method.
HeaderMap http.Header
```
```Go
// Package rc4 implements the RC4 stream cipher.
//
// Deprecated: RC4 is cryptographically broken and should not be used
// except for compatibility with legacy systems.
//
// This package is frozen and no new functionality will be added.
package rc4
```
There are a few other examples [in the standard library](https://cs.opensource.google/search?q=Deprecated:%20language:go&ss=go%2Fgo).

62
DesignDocuments.md

@ -1,62 +1,4 @@
# Go 1.1 The Go wiki on GitHub has moved to go.dev (#61940).
* [Scalable Scheduler](https://docs.google.com/document/d/1TTj4T2JO42uD5ID9e89oa0sLKhJYD0Y_kqxDv3I3XMw)
* [net/http/cookiejar](https://groups.google.com/d/msg/golang-dev/ygDB3nbir00/rouknDcuyakJ)
* [Function Calls](https://docs.google.com/document/d/1bMwCey-gmqZVTpRax-ESeVuZGmjwbocYs1iHplK-cjo/pub)
# Go 1.2 Try <https://go.dev/wiki/DesignDocuments> or <https://go.dev/wiki/>.
* [xml.Marshaler and Unmarshaler](https://go.dev/s/go12xml)
* [encoding.TextMarshaler and Unmarshaler](https://go.dev/s/go12encoding)
* [Runtime Symbol Table Format](https://go.dev/s/go12symtab)
* [Field Selectors and Nil Checks](https://go.dev/s/go12nil)
* [```x[i:j:k]``` Slice Syntax](https://go.dev/s/go12slice)
* [Preemptive Scheduler](https://docs.google.com/document/d/1ETuA2IOmnaQ4j81AtTGT40Y4_Jr6_IDASEKg0t0dBR8/edit?usp=sharing)
# Go 1.3
* [Contiguous Stacks](https://docs.google.com/document/d/1wAaf1rYoM4S4gtnPh0zOlGzWtrZFQ5suE8qr2sD8uWQ/pub)
* [Go 1.3 Linker Overhaul](https://go.dev/s/go13linker)
* [Go 1.3 Native Client Support](https://docs.google.com/document/d/1oA4rs0pfk5NzUyA0YX6QsUEErNIMXawoscw9t0NHafo/pub)
# Go 1.4
* [Go channels on steroids](https://go.dev/s/go13chan)
* [Go 1.4 “Internal” Packages](https://go.dev/s/go14internal)
* [Go 1.4 src/pkg → src](https://go.dev/s/go14nopkg)
* [Go 1.4 Custom Import Path Checking](https://go.dev/s/go14customimport)
* [Go generate: A Proposal](https://go.dev/s/go1.4-generate)
* [The syscall package](https://docs.google.com/a/golang.org/document/d/1QXzI9I1pOfZPujQzxhyRy6EeHYTQitKKjHfpq0zpxZs)
* [Go 1.4 Subrepo Renaming](https://go.dev/s/go14subrepo)
* [Go 1.4 Native Client Support for ARM](https://go.dev/s/go14naclarm)
* [dev.cc branch plan](https://go.dev/s/dev.cc)
# Go 1.5
* [Go 1.5 Bootstrap Plan](https://go.dev/s/go15bootstrap)
* [Go Compiler Overhaul](https://go.dev/s/go13compiler)
* [Go Execution Tracer](http://goo.gl/eXjfeS)
# Future Proposals
* [New SSA Backend for the Go Compiler](https://docs.google.com/document/d/1szwabPJJc4J-igUZU4ZKprOrNRNJug2JPD8OYi3i1K0/edit?usp=sharing_eid)
* [Go 1.4+ Garbage Collection (GC) Plan and Roadmap](https://go.dev/s/go14gc)
* [Better GC and Memory Allocator for Go](https://docs.google.com/document/d/1HCPu3WKyCX3ZRYxmIMKTk0Ik1dePxKW1p02k3uhcft4/view)
* [Groups Discussion](https://groups.google.com/d/topic/golang-dev/pwUh0BVFpY0/discussion)
* [Precise GC Stack Roots](https://docs.google.com/document/d/13v_u3UrN2pgUtPnH4y-qfmlXwEEryikFu0SQiwk35SA/pub)
* [Go 1.3 cmd/go and os/fsnotify](https://go.dev/s/go13fsnotify)
* [Go 1.5 os/fsnotify API](http://goo.gl/MrYxyA)
* [Simple Multi-Dimensional Slices (Tables)](https://docs.google.com/document/d/1eHm7KqfKP9_s4vR1zToxq-FBazdUQ9ZYi-YhcEtdfR0/edit)
* [Go execution modes](https://docs.google.com/a/golang.org/document/d/1nr-TQHw_er6GOQRsF6T43GGhFDelrAP0NqSS_00RgZQ/edit)
* [Building and distributing Go packages as shared libraries](https://docs.google.com/a/canonical.com/document/d/1PxhXNhsdqwBjteW7poqv4Vf3PhtTmYuQKkOk_JNWeh0/edit#heading=h.9hyi51rp3owq)
* [NUMA-aware scheduler for Go](https://docs.google.com/document/d/1d3iI2QWURgDIsSR6G2275vMeQ_X7w-qxM2Vp7iGwwuM/pub)
* [Go 1.5+ "External" Packages](https://docs.google.com/document/d/1CJnU6ZKvsp21B0lQwbJlKFt8Zz4EWscaCRy_EwK8ja8)
# Other Tools
* [Go Oracle](https://docs.google.com/document/d/1WmMHBUjQiuy15JfEnT8YBROQmEv-7K6bV-Y_K53oi5Y)
* [Binding Go and Java](https://go.dev/s/gobind)
* [Go Builder Plan](https://go.dev/s/builderplan)
* [gomobile — a tool for building apps](https://docs.google.com/document/d/1cePOQ35PNEb_QqxnPAmBv0cEnAm7AQSGuz9wVeJ-lBs/edit)
# Rejected Proposals
* [Read-only Slices](https://docs.google.com/a/golang.org/document/d/1UKu_do3FRvfeN5Bb1RxLohV-zBOJWTzX0E8ZU1bkqX0/edit#heading=h.2wzvdd6vdi83), [Evaluation of read-only slices](https://docs.google.com/document/d/1-NzIYu0qnnsshMBpMPmuO21qd8unlimHgKjRD9qwp2A/edit) ([rejected](https://groups.google.com/d/msg/golang-dev/Y7j4B2r_eDw/Rkq-OtEsEBAJ))
* [Go 1.4: unsafe.Pointer arithmetic](https://docs.google.com/a/dempsky.org/document/d/1yyCMzE4YPfsXvnZNjhszaYNqavxHhvbY-OWPqdzZK30/pub)

5
Diagnostics.md

@ -1 +1,4 @@
Moved to [golang.org](https://tip.golang.org/doc/diagnostics.html). The Go wiki on GitHub has moved to go.dev (#61940).
Try <https://go.dev/wiki/Diagnostics> or <https://go.dev/wiki/>.

15
Download-build-farm-failed-logs-and-debugging.md

@ -1,15 +1,4 @@
The Go project has all build failed logs storage at GCE, which you can access by the [dashboard](https://build.golang.org/). The Go wiki on GitHub has moved to go.dev (#61940).
You can download all the failed logs by `fetchlogs`. Try <https://go.dev/wiki/Download-build-farm-failed-logs-and-debugging> or <https://go.dev/wiki/>.
Download `fetchlogs` by `go get golang.org/x/build/cmd/fetchlogs`
`fetchlogs` only download 300 lastest failed logs by default, which is not enough for "mystery"/"flaky" bugs.
`fetchlogs -n <the number you want>`
You may also want to take a look at
`github.com/aclements/go-misc/greplogs`. It's a useful tool by Austin
to run grep over logs fetched by fetchlogs.
Also `github.com/aclements/findflakes` can make some guesses as to when a
flaky test started failing.

19
DragonFly-BSD.md

@ -1,19 +1,4 @@
# Go on DragonFly BSD The Go wiki on GitHub has moved to go.dev (#61940).
From https://github.com/golang/go/issues/34958#issuecomment-543852995 : Try <https://go.dev/wiki/DragonFly-BSD> or <https://go.dev/wiki/>.
> Go's DragonFly support policy is that we support the latest stable
> release primarily, but also try to keep DragonFly master passing, in
> prep for it to become the latest stable release.
>
> But that does mean we need one more builder at the moment.
| **Kernel version** | **Architectures** | **Initial support version** | **Final support version** |
|:------------------------|:------------------|:----------------------------|:--------------------------|
| 4.6 or above | amd64 | Go 1.8 | |
| 4.4.4 (EOL) | amd64 | Go 1.8 | |
| 4.4 through 4.4.3 (EOL) | amd64 | Go 1.3 _*_ | Go 1.7.6 |
| 3.8 through 4.2 (EOL) | amd64 | Go 1.3 _*_ | Go 1.7.6 |
| 3.6 (EOL) | amd64, 386 | Go 1.3 | Go 1.4.3 |
_*_ Go 1.5 or above is recommended.

145
ErrorValueFAQ.md

@ -1,145 +1,4 @@
# Error Values: Frequently Asked Questions The Go wiki on GitHub has moved to go.dev (#61940).
The Go 2 [error values proposal](https://go.googlesource.com/proposal/+/master/design/29934-error-values.md) adds functionality to the [`errors`](https://tip.golang.org/pkg/errors) and [`fmt`](https://tip.golang.org/pkg/fmt) packages of the standard library for Go 1.13. There is also a compatibility package, [`golang.org/x/xerrors`](https://pkg.go.dev/golang.org/x/xerrors), for earlier Go versions. Try <https://go.dev/wiki/ErrorValueFAQ> or <https://go.dev/wiki/>.
We suggest using the `xerrors` package for backwards compatibility. When you no longer wish to support Go versions before 1.13, use the corresponding standard library functions. This FAQ uses the `errors` and `fmt` packages from Go 1.13.
## How should I change my error-handling code to work with the new features?
You need to be prepared that errors you get may be wrapped.
- If you currently compare errors using `==`, use `errors.Is` instead. Example:
```
if err == io.ErrUnexpectedEOF
```
becomes
```
if errors.Is(err, io.ErrUnexpectedEOF)
```
- Checks of the form `if err != nil` need not be changed.
- Comparisons to `io.EOF` need not be changed, because `io.EOF` should never be wrapped.
- If you check for an error type using a type assertion or type switch, use `errors.As` instead. Example:
```
if e, ok := err.(*os.PathError); ok
```
becomes
```
var e *os.PathError
if errors.As(err, &e)
```
- Also use this pattern to check whether an error implements an interface. (This is one of those rare cases when a pointer to an interface is appropriate.)
- Rewrite a type switch as a sequence of if-elses.
## I am already using `fmt.Errorf` with `%v` or `%s` to provide context for an error. When should I switch to `%w`?
It's common to see code like
```
if err := frob(thing); err != nil {
return fmt.Errorf("while frobbing: %v", err)
}
```
With the new error features, that code continues to work exactly as before, constructing a string that includes the text of `err`. Changing from `%v` to `%w` doesn't change that string, but it does wrap `err`, allowing the caller to access it using `errors.Unwrap`, `errors.Is` or `errors.As`.
So use `%w` if you want to expose the underlying error to your callers. Keep in mind that doing so may be exposing implementation detail that can constrain the evolution of your code. Callers can depend on the type and value of the error you're wrapping, so changing that error can now break them. For example, if the `AccessDatabase` function of your package `pkg` uses Go's `database/sql` package, then it may encounter a `sql.ErrTxDone` error. If you return that error with `fmt.Errorf("accessing DB: %v", err)` then callers won't see that `sql.ErrTxtDone` is part of the error you return. But if you instead return `fmt.Errorf("accessing DB: %w", err)`, then a caller could reasonably write
```
err := pkg.AccessDatabase(...)
if errors.Is(err, sql.ErrTxDone) ...
```
At that point, you must always return `sql.ErrTxDone` if you don't want to break your clients, even if you switch to a different database package.
## How can I add context to an error I'm already returning without breaking clients?
Say your code now looks like
```
return err
```
and you decide that you want to add more information to `err` before you return it. If you write
```
return fmt.Errorf("more info: %v", err)
```
then you might break your clients, because the identity of `err` is lost; only its message remains.
You could instead wrap the error by using `%w`, writing
```
return fmt.Errorf("more info: %w", err)
```
This will still break clients who use `==` or type assertion to test errors. But as we discussed in the first question of this FAQ, consumers of errors should migrate to the `errors.Is` and `errors.As` functions. If you can be sure that your clients have done so, then it is not a breaking change to switch from
```
return err
```
to
```
return fmt.Errorf("more info: %w", err)
```
## I'm writing new code, with no clients. Should I wrap returned errors or not?
Since you have no clients, you aren't constrained by backwards compatibility. But you still need to balance two opposing considerations:
- Giving client code access to underlying errors can help it make decisions, which can lead to better software.
- Every error you expose becomes part of your API: your clients may come to rely on it, so you can't change it.
For each error you return, you have to weigh the choice between helping your clients and locking yourself in. Of course, this choice is not unique to errors; as a package author, you make many decisions about whether a feature of your code is important for clients to know or an implementation detail.
With errors, though, there is an intermediate choice: you can expose error details to people reading your code's error messages without exposing the errors themselves to client code. One way to do that is to put the details in a string using `fmt.Errorf` with `%s` or `%v`. Another is to write a custom error type, add the details to the string returned by its `Error` method, and avoid defining an `Unwrap` method.
## I maintain a package that exports an error-checking predicate function. How should I adapt to the new features?
Your package has a function or method `IsX(error) bool` that reports whether an error has some property.
A natural thought would be to modify `IsX` to unwrap the error it is passed, checking the property for each error in the chain of wrapped errors. We advise against doing this: the change in behavior could break your users.
Your situation is like that of the standard `os` package, which has several such functions. We recommend the approach we took there. The `os` package has several predicates, but we treated most of them the same. For concreteness, we'll look at `os.IsExist`.
Instead of changing `os.IsExist`, we made `errors.Is(err, os.ErrExist)` behave like it, except that `Is` unwraps. (We did this by having `syscall.Errno` implement an `Is` method, as described in the documentation for [`errors.Is`](https://pkg.go.dev/errors/#Is).) Using `errors.Is` will always work correctly, because it will exist only in Go versions 1.13 and higher. For older versions of Go, you should recursively unwrap the error yourself, calling `os.IsExist` on each underlying error.
This technique only works if you have control of the errors being wrapped, so you can add `Is` methods to them.
In that case, we recommend:
- Don't change your `IsX(error) bool` function; do change its documentation to clarify that it does not unwrap.
- If you don't already have one, add a global variable whose type implements `error` that represents the
condition that your function tests:
```
var ErrX = errors.New("has property X")
```
- Add an `Is` method to the types for which `IsX` returns true. The `Is` method should return true if its argument
equals `ErrX`.
If you don't have control of all the errors that can have property X, you should instead consider adding another function that tests for the property while unwrapping, perhaps
```
func IsXUnwrap(err error) bool {
for e := err; e != nil; e = errors.Unwrap(e) {
if IsX(e) {
return true
}
}
return false
}
```
Or you could leave things as they are, and let your users do the unwrapping themselves. Either way, you should still change the documentation of `IsX` to clarify that it does not unwrap.
## I have a type that implements `error` and holds a nested error. How should I adapt it to the new features?
If your type already exposes the error, write an `Unwrap` method.
For example, perhaps your type looks like
```
type MyError struct {
Err error
// other fields
}
func (e *MyError) Error() string { return ... }
```
Then you should add
```
func (e *MyError) Unwrap() error { return e.Err }
```
Your type will then work correctly with the `Is` and `As` functions of `errors` and `xerrors`.
We've done that for [`os.PathError`](https://tip.golang.org/pkg/os/#PathError.Unwrap) and other, similar types in the standard library.
It's clear that writing an `Unwrap` method is the right choice if the nested error is exported, or otherwise visible to code outside your package, such as via a method like `Unwrap`. But if the nested error is not exposed to outside code, you probably should keep it that way. Making the error visible by returning it from `Unwrap` will enable your clients to depend on the type of the nested error, which can expose implementation details and constrain the evolution of your package. See the discussion of `%w` above for more.

102
Errors.md

@ -1,102 +1,4 @@
# Errors The Go wiki on GitHub has moved to go.dev (#61940).
Errors are indicated by returning an `error` as an additional return value from a function. A `nil` value means that there was no error. Try <https://go.dev/wiki/Errors> or <https://go.dev/wiki/>.
` error `s can be turned into strings by calling `Error`, their only method. You can create an error from a string by calling `errors.New`:
```go
if failure {
return errors.New("inverse tachyon pulse failed")
}
```
or by using `fmt.Errorf`:
```go
if failure {
return fmt.Errorf("inverse tachyon pulse failed")
}
```
Error strings should not start with a capital letter because they'll often be prefixed before printing:
```go
err := TryInverseTachyonPulse()
if err != nil {
fmt.Printf("failed to solve problem: %s\n", err)
}
```
If you expect calling code to be able to handle an error, you can distinguish classes of errors either by returning special values, or new types. You only need to distinguish differences that the calling code could be expected to handle in this way as the string allows one to communicate the details of the error.
`io.EOF` is a special value that signals the end of a stream. You can compare error values directly against io.EOF.
If you want to carry extra data with the error, you can use a new type:
```go
type ParseError struct {
Line, Col int
}
func (p ParseError) Error() string {
return fmt.Sprintf("parse error on line %d, column %d", p.Line, p.Col)
}
```
If you want to create a constant string error, you can use a named type string:
```go
type errorConst string
const ErrTooManyErrors errorConst = "too many errors found."
func (e errorConst) Error() string {
return string(e)
}
```
Calling code would test for a special type of `error` by using a type switch:
```go
switch err := err.(type) {
case ParseError:
PrintParseError(err)
}
```
## Naming
Error types end in `"Error"` and error variables start with `"Err"` or `"err"`:
```go
package somepkg
// ParseError is type of error returned when there's a parsing problem.
type ParseError struct {
Line, Col int
}
var ErrBadAction = errors.New("somepkg: a bad action was performed")
// -----
package foo
func foo() {
res, err := somepkgAction()
if err != nil {
if err == somepkg.ErrBadAction {
}
if pe, ok := err.(*somepkg.ParseError); ok {
line, col := pe.Line, pe.Col
// ....
}
}
}
```
## References
* Errors (specification): https://go.dev/ref/spec#Errors
* Package `errors`: https://pkg.go.dev/errors/
* Type switches: https://go.dev/ref/spec#TypeSwitchStmt

259
ExperienceReports.md

@ -1,259 +1,4 @@
This page collects experience reports about problems with Go that might inform our design of solutions to those problems. These reports should focus on the _problems_: they should not focus on and need not propose solutions. To propose solutions, see the [proposal process](https://go.dev/s/proposal). The Go wiki on GitHub has moved to go.dev (#61940).
We hope to use these experience reports to understand where people are having trouble writing Go, to help us prioritize future changes to the Go ecosystem. (We do not promise to reply to these. If you need immediate help answering questions about Go, see [https://go.dev/help/](https://go.dev/help/) for resources.) Try <https://go.dev/wiki/ExperienceReports> or <https://go.dev/wiki/>.
__The best experience reports tell: (1) what you wanted to do, (2) what you actually did, and (3) why that wasn’t great, illustrating those by real concrete examples, ideally from production use.__ Please write these reports about the problems most significant to you, post them on your own blog, or on Medium, or as a [Github Gist](https://gist.github.com/) (use a `.md` extension for Markdown), or as a publicly-readable Google doc, and then link them here. (Talk videos or slides are also welcome, although they are not as convenient for us to digest.)
If you do not have permission to edit the wiki to add an article to this list, [please file an issue](https://go.dev/issue/new).
Please keep the overall page sorted alphabetically by section (Error Handling before Logging, and so on).
Within a section, please keep articles sorted chronologically.
It's helpful to include a one-phrase summary of the point of each article.
Add new sections as appropriate.
**Table of Contents**
- [App and Game Development](#app-and-game-development)
- [Concurrency](#concurrency)
- [Casting](#casting)
- [Context](#context)
- [Declarations](#declarations)
- [Dependencies](#dependencies)
- [Documentation](#documentation)
- [Diagnostics and Debugging](#diagnostics-and-debugging)
- [Education and Teaching](#education-and-teaching)
- [Error Handling](#error-handling)
- [Error Values](#error-values)
- [File System](#file-system)
- [Generics](#generics)
- [GoMobile](#gomobile)
- [Immutability](#immutability)
- [Inter Process Communication](#inter-process-communication)
- [Large-Scale Software Development](#large-scale-software-development)
- [Literals](#literals)
- [Logging](#logging)
- [Misc/Multiple](#misc--multiple)
- [Modules](#modules)
- [Performance](#performance)
- [Porting](#porting)
- [Slices](#slices)
- [Syntax](#syntax)
- [Time](#time)
- [Tooling](#tooling)
- [Type System](#type-system)
- [Typed nils](#typed-nils)
- [Vendoring](#vendoring)
## App and Game Development
- Paul Ruest, "[Go Library Support for Apps and Games](https://gazed.github.io/goApps.html)", November 2017
- Tad Vizbaras, "[Building Optical Character Recognition (OCR) in Go](http://recoink.com/goreport)", December 2017
## Casting
- Richard Warburton, "[Should Go Casting be permitted when underlying data structures are the same?](https://gist.github.com/krolaw/f010ab0966fd379725ecc48e8bbcac1c)", December 2017
## Concurrency
- Sergey Kamardin, “[A Million WebSockets and Go](https://medium.freecodecamp.org/million-websockets-and-go-cc58418460bb),” August 2017, about the memory overhead of blocked read/write goroutines.
- Nathaniel J. Smith, “[Notes on structured concurrency, or: Go statement considered harmful](https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/)”, April 2018.
## Context
- Sam Vilain, “[Using Go's context library for making your logs make sense](https://blog.gopheracademy.com/advent-2016/context-logging/),” December 2016, about extracting structured log values from context.
- Jon Calhoun, “[Pitfalls of context values and how to avoid or mitigate them in Go](https://www.calhoun.io/pitfalls-of-context-values-and-how-to-avoid-or-mitigate-them/),” February 2017.
- Michal Štrba, "[Context should go away for Go 2](https://faiface.github.io/post/context-should-go-away-go2/)," August 2017
- Axel Wagner, "[Why context.Value matters and how to improve it](https://blog.merovius.de/2017/08/14/why-context-value-matters-and-how-to-improve-it.html)," August 2017.
- Dave Cheney, "[Context isn't for cancellation](https://dave.cheney.net/2017/08/20/context-isnt-for-cancellation)," August 2017.
- Ross Light, "[Canceling I/O in Go Cap'n Proto](https://medium.com/@zombiezen/canceling-i-o-in-go-capn-proto-5ae8c09c5b29)," January 2018.
- Iman Tumorang, "[Avoiding Memory Leak in Golang API](https://hackernoon.com/avoiding-memory-leak-in-golang-api-1843ef45fca8)," January 2018.
## Declarations
- Christophe Meessen, "[Problems with Go's shorthand declaration :=](https://gist.github.com/chmike/ac0113afefbc04e67323b4a3688d6b54#file-godeclareproblem-md)", July 2017, about the shadowing var trap and apparent inconsistency of `:=`.
- Brian Will, "[Go's := syntax is error-prone with multiple target variables](https://gist.github.com/BrianWill/671ce51e6ef6a9f0caa27272a9a0637f)", August 2017.
## Dependencies
- Patrick Bohan, "[Docker => Moby: Go Dependencies](http://engineering.rallyhealth.com/go/golang/dependencies/package-managers/2017/06/28/go-and-dependencies.html)," Jun 28, 2017. A new Go team's struggles with dependency management and an approach to deal with them.
- Judson Lester, "[untitled gist] (https://gist.github.com/nyarly/edb6b7a5e3a762da6a5e2da8f59acf07)", August 2017.
- David Collier-Brown, "[Avoiding an NP-Complete Problem by Recycling Multics’ Answer](https://leaflessca.wordpress.com/2018/09/03/avoiding-an-np-complete-problem-by-recycling-multics-answer/)", September 2018.
- Adrian Hesketh "[Security vulnerability tracking](https://gist.github.com/a-h/f0fd0fad5e8a2e0c9b7afcf84f51f286)", January 2018. Proving to a security auditor that code doesn't contain known vulnerabilities.
## Diagnostics and Debugging
- Kevin Burke, "[How I'm running benchmarks and printing their results](https://github.com/kevinburke/go-html-boilerplate/blob/master/Makefile#L38)", it would be nice if I didn't need so much Unix glue to run and print these. July 2017.
- John Clarke, Tracking down an intermittent fault (not a race) by running a very slow {hit test failure, increase logging} cycle by running "do { go test -race } while ( $LASTEXITCODE -eq 0 )" overnight. Over many nights. Execution trace functionality like https://rr-project.org/ would be transformative. November 2018.
- `guanw`, [`cmd/trace` and PySnooper](https://github.com/guanw/go-proposal/blob/master/proposal.md). Comparison of `cmd/trace` with a (more succinct) Python tracing API. May 2019.
## Documentation
- Kevin Burke, "[Need to add documentation for a binary in three different places](https://github.com/golang/go/issues/20212)", May 2017.
## Education and Teaching
- Carl Kingsford and Phillip Compeau, "[Go 2.0 for Teaching](http://www.monogrammedchalk.com/go-2-for-teaching/)". Experience using Go in an introductory programming course.
## Error Handling
(This section is about writing `if err != nil`.)
- Andrew Gerrand, “[Error Handling and Go](https://go.dev/blog/error-handling-and-go),” July 2011,
showing Go error handling patterns.
- Martin Sústrik, “[Why should I have written ZeroMQ in C, not C++ (part I)](http://www.250bpm.com/blog:4),” May 2012,
discussing production problems with C++ exception handling due to error-handling code being far from code that causes the error.
- Thomi Richards, “[The Problems with Errors](http://www.tech-foo.net/the-problems-with-errors.html),” March 2014,
arguing that it's essential for code to document exactly which errors it returns / exceptions it might throw.
- Roger Peppe, “[Lovin' your errors](https://rogpeppe.neocities.org/error-loving-talk/index.html),” March 2015, discussing idioms for error handling.
- Bleve, “[Deferred Cleanup, Checking Errors, and Potential Problems](http://www.blevesearch.com/news/Deferred-Cleanup,-Checking-Errors,-and-Potential-Problems/),” September 2015,
showing a bug related to error handling and defer in Bleve search.
- Andrew Morgan, “[What I Don't Like About Error Handling in Go, and How to Work Around It](https://opencredo.com/why-i-dont-like-error-handling-in-go/),” January 2017,
about it being difficult to force good error handling, errors not having stack traces, and error handling being too verbose.
- André Hänsel, "[If Ⅰ were to make my own Go…](https://blog.creations.de/?p=223)", August 2017
- Peter Goetz, "[Thinking About New Ways of Error Handling in Go 2](https://medium.com/@peter.gtz/thinking-about-new-ways-of-error-handling-in-go-2-e56d116952f1)," September 2017, shows how error-prone error handling in Go is and lays out requirements to improve the experience.
## Error Values
(This section is about additional error semantics beyond the `Error() string` method.)
- Andrew Morgan, “[What I Don't Like About Error Handling in Go, and How to Work Around It](https://opencredo.com/why-i-dont-like-error-handling-in-go/),” January 2017,
about it being difficult to force good error handling, errors not having stack traces, and error handling being too verbose.
- Chris Siebenmann, “[Go's net package doesn't have opaque errors, just undocumented ones](https://utcc.utoronto.ca/~cks/space/blog/programming/GoNetErrorsUndocumented),” August 2018
- Bryan C. Mills, “[Error Wrapping and Redundancy in Go](https://github.com/bcmills/go-experience-reports/blob/master/errors.md),” September 2019
## File System
- Chris Lewis, “[Non-Local File Systems Should Be Supported](https://gist.github.com/cflewis/87843028576459b0f6ebf55f1b200891),” July 2017. Proposes replacing file system read calls to something more abstracted like the `sql` package does.
## Generics
- “[Summary of Go Generics Discussions (living document)](https://docs.google.com/document/d/1vrAy9gMpMoS3uaVphB32uVXX4pi-HnNjkMEgyAHX4N4/edit).”
- Bouke van der Bijl, “[Idiomatic Generics in Go](https://web.archive.org/web/20141001043016/http://bouk.co/blog/idiomatic-generics-in-go/),” September 2014.
- Craig Weber, “[Living without generics in Go](https://web.archive.org/web/20141227092139/http://www.weberc2.com/posts/2014/12/12/living-without-generics.txt),” December 2014.
- Shashank Sharma, “[Poor man's generics in Golang (Go)](https://codeblog.shank.in/poor-mans-generics-in-golang/),” May 2016.
- Niek Sanders, “[Overhead of Go's generic sort](https://github.com/nieksand/sortgenerics),” September 2016,
documenting the overhead of sorting using sort.Interface instead of specialized code.
- Jon Calhoun, “[Using code generation to survive without generics in Go](https://www.calhoun.io/using-code-generation-to-survive-without-generics-in-go/),” May 2017.
- Jon Bodner, “[Closures are the Generics for Go](https://medium.com/capital-one-developers/closures-are-the-generics-for-go-cb32021fb5b5),” June 2017.
- Andrew Stock, "[Why I miss generics in Go](https://medium.com/@watchforstock/why-i-miss-generics-in-go-9aef810a1bef)," June 2017
- Kevin Burke, "[Code example with lots of interface casts](https://gist.github.com/kevinburke/a10aed6d8d07ecd5efe658b21cd168c1)," requires a lot of boilerplate/casts.
- Ian Lance Taylor, "[The append function](https://www.airs.com/blog/archives/559)," July 2017.
- DeedleFake, "[The Problem with Interfaces](https://deedlefake.com/2017/07/the-problem-with-interfaces/)", July 2017.
- Kurtis Nusbaum "[Why I'm So Frustrated With Go](https://hackernoon.com/why-im-so-frustrated-with-go-97c0c4ae214e)," June 2017
- Juan Álvarez, "[Generics on Go's stdlib](https://medium.com/@shixzie/generics-on-gos-stdlib-10de52fe824d)", July 2017.
- David Chase, "[A use case for Go Generics in a Go Compiler](https://dr2chase.wordpress.com/2017/08/09/a-use-case-for-go-generics-in-a-go-compiler/)", August 2017
- Varun Kumar, "[Generics - I Wish You Were Here...](https://varunksaini.com/blog/use-case-for-generics/)", August 2017
- Sameer Ajmani, "[Go Experience Report for Generics: Google metrics API](https://medium.com/@sameer_74231/go-experience-report-for-generics-google-metrics-api-b019d597aaa4)", August 2017
- Chewxy, "[Tensor Refactor: A Go Experience Report](https://blog.chewxy.com/2017/09/11/tensor-refactor/)", September 2017, discusses the lack of generics and how it affects building high performance multidimensional arrays for different data types (having to resort to a lot of pointer ugliness, and manually keeping track of type and runtime type checking)
- qwerty2501,"[A problem runtime error due to lack of Generics](https://gist.github.com/qwerty2501/8839af87946571943a6c4f623c6124e2)", October 2017
- posener, "[Why I recommend to avoid using the go-kit library](https://gist.github.com/posener/330c2b08aaefdea6f900ff0543773b2e)", clear separation of concern need lots of boilerplate code. gokit try
code generation to avoid this [#70](https://github.com/go-kit/kit/issues/70) [#308](https://github.com/go-kit/kit/pull/308) [protoc-gen-gokit](https://github.com/AmandaCameron/protoc-gen-gokit) , but it looks like
a complex solution for the problem.
- Xavier Leroy, "[A modular module system](http://gallium.inria.fr/%7Exleroy/publi/modular-modules-jfp.pdf)", paper about module description for generics.
- Tobias Gustafsson, "[Experiences implementing PEDS](https://github.com/tobgu/peds/blob/master/experience_report.md)", PEDS is a set of statically type safe, immutable/persistent, collections. November 2017
- A Googler "[govisor/generics.go](https://github.com/google/gvisor/blob/master/tools/go_generics/generics.go)". April 27, 2018
## GoMobile
- Vijay, "[Nested structs and slices not supported in gomobile]"
## Immutability
- Kurtis Nusbaum "[Why I'm So Frustrated With Go](https://hackernoon.com/why-im-so-frustrated-with-go-97c0c4ae214e)," June 2017
- Sindre Myren "[Go 2.0: Retain simplicity by trading features](https://medium.com/@smyrman/go-2-0-retain-simplicity-by-trading-features-b310b60862ea)" July 2017
- Tobias Gustafsson, "[Experiences implementing PEDS](https://github.com/tobgu/peds/blob/master/experience_report.md)", PEDS is a set of statically type safe, immutable/persistent, collections. November 2017
## Inter Process Communication
- Pablo R. Larraondo "[A Go interprocess communication model](https://gist.github.com/prl900/a7aaa41707e2236592da5e78d8a10dc9)," August 2017
## Large-Scale Software Development
- Russ Cox, “[Codebase Refactoring (with help from Go)](https://talks.golang.org/2016/refactor.article),” November 2016, laying out the gradual code repair problem addressed in part by type aliases ([#18130](https://go.dev/issue/18130)).
- Travis Jeffery, "[I'll take pkg over internal](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/)," November 2019; talking about Go project layouts, problems with internal, and why people use pkg.
## Literals
- Mike Schinkel, "[Managing string literals is a PITA, not just in GoLang but in (all?) other languages](https://gist.github.com/mikeschinkel/be502cb73fb1ef535749816ba1817dc3)," June 2022, proposing "Literal String" and "Literal Template" types.
## Logging
- Evan Miller, “[Logging can be tricky](http://corner.squareup.com/2014/09/logging-can-be-tricky.html),” September 2014,
showing how logging can add to application tail latency.
- Dave Cheney, “[Let's talk about logging](https://dave.cheney.net/2015/11/05/lets-talk-about-logging),” November 2015,
arguing that there are only two log levels.
- TJ Holowaychuk, “[Apex log](https://medium.com/@tjholowaychuk/apex-log-e8d9627f4a9a),” January 2016, describing a structured log package and how it would be used in production.
- Paddy Foran, “[Logging in Go](https://dramafeveronline.com/),” February 2016, showing how sends Go program logs to Sentry.
- Martin Angers, “[About Go logging for reusable packages](https://www.0value.com/about-go-logging),” March 2016, making suggestions for how to write code that doesn't assume a particular log package.
- BugReplay.com, “[How to use Google Cloud's Free Structured Logging Service With Golang](http://blog.bugreplay.com/post/150086459149/how-to-use-google-clouds-free-structured-logging),” September 2016.
- Sam Vilain, “[Using Go's context library for making your logs make sense](https://blog.gopheracademy.com/advent-2016/context-logging/),” December 2016, about extracting structured log values from context.
- Logmatic, “[Our Guide to a Golang Logs World](https://logmatic.io/blog/our-guide-to-a-golang-logs-world/),” March 2017.
- Chris Hines, Peter Bourgon, “[Proposal: standard Logger interface](https://docs.google.com/document/d/1shW9DZJXOeGbG9Mr9Us9MiaPqmlcVatD_D8lrOXRNMU/edit?usp=drive_web),“ February 2017, problems related to stdlib logger, especially in the context of libraries, and one proposed solution.
- Sindre Myren, "[There is nothing Goish about log.Fatal](https://medium.com/@smyrman/there-is-nothing-goish-about-log-fatal-4ab24ae5ba7)" August 2017, how poorly log.Fatal plays with defer, and a simple pattern for delaing with it in Go 1.x and Go 2.x.
- Joonas Loppi, "[An idea to fix Go´s logging mess](https://joonas.fi/2018/12/04/an-idea-to-fix-gos-logging-mess/)" December 2017, just use *log.Logger as an interface everywhere and compose solutions around it.
## Misc / Multiple
- Iman Tumorang, "[Trying Clean Architecture on Golang](https://hackernoon.com/golang-clean-archithecture-efd6d7c43047)" July 2017
- Laurent Demailly, "[My Go lang experience, part 1](https://laurentsv.com/blog/2017/12/28/about-golang.html)" December 2017, a laundry list of pros and cons with current Go from an experienced C/C++/Java/Scripting languages developer perspective.
- Gokcehan Kara, "[Installation with Go Language can be Simpler](https://gokcehan.github.io/posts/installation-with-go-language-can-be-simpler.html)" May 2018, some complications about the installation and distribution of static stripped binaries with version information.
- Bob Nystrom, "[The Language I Wish Go Was](https://journal.stuffwithstuff.com/2010/10/21/the-language-i-wish-go-was/)" October 2010, I wish Go had tuples, unions, constructors, no Nil, exceptions, generics, some syntax sugar, and ponies that shoot Cheez Whiz out of their noses.
## Modules
- Paul Jolly - "[Creating a submodule within an existing module](https://gist.github.com/myitcv/79c3f12372e13b0cbbdf0411c8c46fd5)" - covers multi-module repos, cyclic module dependencies and the steps required to move between various "states"
- Chi authors - [Github comment](https://github.com/go-chi/chi/pull/378#issuecomment-453274681) - comment on why the Chi authors held out on implementing Go Modules support (which has been added in the meantime). TL;DR ­— due to the import compatibility rule.
- Sam Whited -"[Supporting Go Modules](https://blog.samwhited.com/2019/01/supporting-go-modules/)" - Things learned from upgrading 20 so modules. TL;DR — upgrading large modules past v1 is a huge pain and needs tooling, failure modes for modules are very complex and it's easy to screw up adding modules support to existing projects.
- Stripe Github thread (linked comment down) - [reverting support for Go Modules](https://github.com/stripe/stripe-go/pull/712#issuecomment-454594534). TL;DR — Stripe is reverting Go Modules support because there is no clear upgrade path from dep for modules above v1.
- [Referencing bash scripts in `GOPATH`](https://gist.github.com/ineiti/4a4a1798876225f7a553a13120d705ae)
- [Go Modules on Badger and Dgraph](https://discuss.dgraph.io/t/go-modules-on-badger-and-dgraph/4662). TL;DR - Dgraph is dropping support for v2 because it forces non-Go modules users to change their code.
- [A survey on Golang's dependency management modes (GOPATH and Go Modules): status quo, problems and challenges](https://github.com/KateGo520/Hero/issues/1). - The purpose of this report is to help developers better understand the issues in the transition from GOPATH to Go Modules.
## Performance
- Kevin Burke, "[Real Life Go Benchmarking](https://kev.inburke.com/kevin/real-life-go-benchmarking/)," trying to explain to the average developer how to use tools like pprof, maybe this could be easier. July 2016.
- Nathan Kerr, "[Concurrency Slower?](https://pocketgophers.com/concurrency-slower/)", shows how to use Go's testing, benchmarking, and profiling tools to improve the performance of a concurrent implementation of a function. April 2017.
## Porting
- Shannon Pekary, "[Why GOPP](https://github.com/spekary/gopp/blob/master/Why.md)," an attempt to create
a 'class' keyword that simply makes a struct to also be an interface to make porting code from object-oriented languages much easier.
## Slices
- Richard Warburton, "[Should Go 2.0 support slice comparison?](https://gist.github.com/krolaw/3205a3139d423b0c39e24b98c923b1a1)," an argument to treat slices as structs for equality comparison, ignoring backing arrays.
- "[Deduplicating a slice is too cumbersome](https://gist.github.com/kevinburke/ad20587e6694acb9251f7d7e25c77078)," a 10-line function in your source code vs. e.g. Ruby's `uniq` function.
- "[Counter-intuitive behaviour of Go variadic functions](https://gist.github.com/dpinela/f7fdeb0ce3e1f0b4f495917ad9210a85),", January 2018, stumbling blocks encountered when expanding slices into argument lists.
## Syntax
- André Hänsel, "[If Ⅰ were to make my own Go…](https://blog.creations.de/?p=223)", August 2017
- Bojan Zivanovic, "[Optional function parameters](https://bojanz.github.io/optional-parameters-go/)", May 2020
- Raanan Hadar, "[A data scientist's take on Go](https://medium.com/@rhadar/a-data-scientists-take-on-go-ed408c00ac45)", September 2020
## Time
- John Graham-Cumming, “[How and Why the Leap Second Affected Cloudflare DNS](https://blog.cloudflare.com/how-and-why-the-leap-second-affected-cloudflare-dns/),” January 2017, about timing across leap seconds ([#12914](https://go.dev/issue/12914)).
## Tooling
- Jonathan Ingram, “[gofmt is not opinionated enough](https://gist.github.com/jonathaningram/2b62022844348f3407518dd3a180ef42)”, August 2017, about ongoing debates between developers regarding code style because `gofmt` is not opinionated enough.
- Jean-Laurent de Morlhon, "[Pourquoi Maurice ne doit surtout pas coder en GO](https://www.youtube.com/watch?v=LIFZPzupwgs), talk about Go from a java developper perspective ("go dep" is not enough,...), slides are in english.
## Type System
- Sam Whited, “[Faking Enumeration Types with Consts and Unexported Types](https://gist.github.com/SamWhited/6cdbc49b4562e1a1b0526af523f5c5d7)”, July 2017, about attempting to ensure compile time correctness of values provided to an API using the type system.
- Andreas Matuschek, "[Operator Methods](https://gist.github.com/maj-o/9cab355e3e5e4f6f66dbf0a8f24cd13a)", July 2017, just to remember that there are problems with types without corresponding operators ([#19770](https://github.com/golang/go/issues/19770)).
- Leigh McCulloch, "[Go: Experience Report: Pointers](https://leighmcculloch.com/posts/go-experience-report-pointers/)", July 2017, about pointers being used for both transferring ownership and indicating a lack of value.
- Jack Lindamood, "[Interface wrapping method erasure](https://medium.com/@cep21/interface-wrapping-method-erasure-c523b3549912)", July 2017, about the loss of information due to type wrappers
- Sam Whited, “[The Case for interface{}](https://blog.samwhited.com/2017/08/the-case-for-interface/)”, Aug 2017, two examples of using interface and why one is bad (but necessary) and one is good.
- James Frasché, "[Sum types experience report](https://gist.github.com/jimmyfrasche/ba2b709cdc390585ba8c43c989797325)", Aug 2017, issues caused by inability to restrict to a closed set of types
- Robin Eklind, "[Specific use cases. In response to James Frasché's 'Sum types experience report'](https://gist.github.com/jimmyfrasche/ba2b709cdc390585ba8c43c989797325#gistcomment-2181410)", Aug 2017, issues caused by inability to restrict to a closed set of types
- Rick Branson, "[Implicit Pointers = Explicitly Bad](https://docs.google.com/document/d/1va7f4YvExK4mNBmMt2RMg1SNSHyljc8ARVp2ATKtBwU/edit?usp=sharing)", Sep 2017, issues encountered with parameters/variables with interface types as implicit references
- Chewxy, "[Tensor Refactor: A Go Experience Report](https://blog.chewxy.com/2017/09/11/tensor-refactor/)", September 2017, issues regarding discussion of a type system in Go
- Walter Schulze, "[Generic functions cannot be passed as values](https://gist.github.com/awalterschulze/e3999f8cfa29b246c35a651a2be4d121)", September 2017
- Walter, Schulze, "[For Sum Types: Multiple return parameters are overrated](https://awalterschulze.github.io/blog/post/sum-types-over-multiple-returns/)", September 2017
- Nicolas, Boulay "[Sum type not always the best choice (Typed tagless-final interpretations)](https://gist.github.com/nicolasboulay/a8ee4a65e8c2cc110c20e6d24e838e86), October 2017
- Eduard Urbach, "[Type-casting interface{} to chan interface{}](https://github.com/blitzprog/go-channel-type-casting)", October 2017
- David Vennik, "[Unjumbling Golang OOP primitives](https://gist.github.com/l0k1verloren/344956daedb434094e9af2c21ff9376c)", April 20, 2018 - The problem of the lack of structuring in OOP primitives - dummy functions and redundant boilerplate type bindings.
- Jelte Fennema, "[Fixing the billion dollar mistake in Go by borrowing from Rust](https://getstream.io/blog/fixing-the-billion-dollar-mistake-in-go-by-borrowing-from-rust/)", June 14, 2018 - Nil pointer dereferences cause panics in production - it would be great if the type system would catch some of those.
## Typed nils
- David Cheney, "[Typed nils in Go 2](https://dave.cheney.net/2017/08/09/typed-nils-in-go-2)", August 2017.
## Vendoring
- Jeremy Loy, "[Go Modules and Vendoring](https://github.com/golang/go/issues/27227#issuecomment-420428896)", September 2018.
- Ian Davis, "[Vendoring for self-contained builds](https://github.com/golang/go/issues/27227#issuecomment-459171581)", January 2019

85
FileTreeDocumentation.md

@ -1,85 +1,4 @@
This page documents the file tree for a source installation of go1.13.1. The Go wiki on GitHub has moved to go.dev (#61940).
``` Try <https://go.dev/wiki/FileTreeDocumentation> or <https://go.dev/wiki/>.
$ tree -d -L 2 /usr/lib/go1.13.1 | head
/usr/lib/go1.13.1
`-- go
|-- api
|-- bin
|-- doc
|-- lib
|-- misc
|-- pkg
|-- src
`-- test
$
```
api contains data for Go's API checker
```
$ ls $GOROOT/api
README go1.10.txt go1.13.txt go1.4.txt go1.7.txt go1.txt
except.txt go1.11.txt go1.2.txt go1.5.txt go1.8.txt next.txt
go1.1.txt go1.12.txt go1.3.txt go1.6.txt go1.9.txt
$
```
bin contains the go and gofmt executables
```
$ ls -l $GOROOT/bin
total 11576
-rwxr-xr-x 1 root root 9652760 Oct 2 03:02 go
-rwxr-xr-x 1 root root 2197756 Oct 2 03:02 gofmt
$
```
doc contains .css, .go, .html, .js, and .png files
lib contains the compressed time zone database
```
$ tree $GOROOT/lib | head -n 5
/usr/lib/go1.13.1/go/lib
`-- time
|-- README
|-- update.bash
`-- zoneinfo.zip
$
```
misc contains files pertaining to specific build modes and platforms
```
$ tree -d -L 1 $GOROOT/misc | head -n 12
/usr/lib/go1.13.1/go/misc
|-- android
|-- arm
|-- cgo
|-- chrome
|-- ios
|-- linkcheck
|-- nacl
|-- reboot
|-- swig
|-- trace
`-- wasm
$
```
pkg contains libs, header files, compiled object files, and executables
```
$ tree -d -L 1 $GOROOT/pkg | head -n 6
/usr/lib/go1.13.1/go/pkg
|-- include
|-- linux_386
|-- linux_386_dynlink
|-- obj
`-- tool
$
```
src contains the go1.13.1 source code
test contains tests of the Go toolchain and runtime

18
FreeBSD.md

@ -1,18 +1,4 @@
# Go on FreeBSD The Go wiki on GitHub has moved to go.dev (#61940).
| **Kernel version** | **Architectures** | **Initial support version** | **Final support version** | Try <https://go.dev/wiki/FreeBSD> or <https://go.dev/wiki/>.
|:-------------------|:--------------------------------|:----------------------------|:--------------------------|
| 14-CURRENT | amd64, 386, arm, arm64, riscv64 | _**_ _***_ | |
| 13-STABLE | amd64, 386, arm, arm64, riscv64 | _**_ _***_ | |
| 12-STABLE | amd64, 386, arm, arm64 | Go 1.12 _**_ | |
| 11-STABLE (EOL) | amd64, 386, arm, 386 | Go 1.7 | Go 1.19.x |
| 10-STABLE (EOL) | amd64, 386, arm, 386 | Go 1.3 _*_ | Go 1.12.4 |
| 9-STABLE (EOL) | amd64, 386 | Go 1 _*_ | Go 1.9.7 |
| 8-STABLE (EOL) | amd64, 386 | Go 1 _*_ | Go 1.9.7 |
| 7-STABLE (EOL) | amd64, 386 | Go 1 | Go 1.1.2 |
_*_ Go 1.5 or above is recommended.
_**_ Go versions prior to 1.20 require a kernel with `options COMPAT_FREEBSD11` config (this is the default). 64-bit inode aware system calls are available since https://go.dev/cl/143637. See https://go.dev/issues/22447.
_***_ Go 1.20 is the first version to support freebsd/riscv64.

77
FromXToGo.md

@ -1,77 +1,4 @@
This page links to blog posts, videos, and slide decks discussing moving a code base to Go from some other language. The Go wiki on GitHub has moved to go.dev (#61940).
# Python Try <https://go.dev/wiki/FromXToGo> or <https://go.dev/wiki/>.
* [Disqus: Trying out this Go thing](https://blog.disqus.com/trying-out-this-go-thing)
* [Rackspace: Making OpenStack-Powered Rackspace Cloud Files Buzz With Hummingbird](https://blog.rackspace.com/making-openstack-powered-rackspace-cloud-files-buzz-with-hummingbird/)
* [Repustate: From Python to Go: migrating our entire API](https://www.repustate.com/blog/migrating-entire-api-go-python/)
* [Spacemonkey: Python to Go](https://www.spacemonkey.com/blog/posts/go-space-monkey)
* [Why I went from Python to Go (and not node.js)](http://jordanorelli.com/post/31533769172/why-i-went-from-python-to-go-and-not-nodejs)
* [How to Convince Your Company to Go With Golang](https://sendgrid.com/blog/convince-company-go-golang/)
* [5 Reasons Why We switched from Python To Go](https://medium.com/@tigranbs/5-reasons-why-we-switched-from-python-to-go-4414d5f42690)
* [Stream: Why we switched from Python to Go](https://getstream.io/blog/switched-python-go)
* [Code Migration in Production: Rewriting the Sharding Layer of Uber’s Schemaless Datastore](https://eng.uber.com/schemaless-rewrite/)
* [Learning Go by porting a medium-sized web backend from Python](https://benhoyt.com/writings/learning-go/)
# Node
* [Digg](https://medium.com/@theflapjack103/the-way-of-the-gopher-6693db15ae1f#.yw5lk8t25)
* [Uber](https://www.infoq.com/articles/podcast-matt-ranney) (audio)
* [Apex/TJ Holowaychuk](https://medium.com/@tjholowaychuk/farewell-node-js-4ba9e7f3e52b#.3hjxf6pbp)
* [ScaleDrone migrated all websocket servers from Node.js to Go](http://blog.scaledrone.com/posts/nodejs-to-go)
* [From Node.js To Go, Why One Startup Made The Switch](http://thenewstack.io/from-node-js-to-go-why-one-startup-made-the-switch/)
* [Why did Koding switch from Node.js to Go?](https://www.quora.com/Why-did-Koding-switch-from-Node-js-to-Go)
* [Letting Go of Node.js](http://blog.davebalmer.com/letting-go-of-node-js/)
* [Our Experience with Golang](https://www.upguard.com/blog/our-experience-with-golang)
* [Interview with Steve Kaliski, CTO of Bowery - The tech stack that powers Bowery, Moving from Node.js to Go lang and more](https://hashnode.com/post/interview-with-steve-kaliski-cto-of-bowery-the-tech-stack-that-powers-bowery-moving-from-nodejs-to-go-lang-and-more-ciibz8dmn001lj3xt468g5k78)
# C++
* [dl.google.com](https://talks.golang.org/2013/oscon-dl.slide#1) by Brad Fitzpatrick
* [Flywheel: Google's mobile image compression proxy](http://matt-welsh.blogspot.nl/2013/08/rewriting-large-production-system-in-go.html)
* [Fulfilling a Pikedream: the ups of downs of porting 50k lines of C++ to Go](https://togototo.wordpress.com/2015/03/07/fulfilling-a-pikedream-the-ups-of-downs-of-porting-50k-lines-of-c-to-go/)
# Ruby
* [Book: From Ruby to Golang](https://leanpub.com/rb2go)
* [Toggl: Moving to Go](https://blog.toggl.com/2012/09/moving-to-go/)
* [Iron.io: How We Went from 30 Servers to 2: Go](https://www.iron.io/how-we-went-from-30-servers-to-2-go/)
* [Parse: How We Moved Our API From Ruby to Go and Saved Our Sanity](http://blog.parse.com/learn/how-we-moved-our-api-from-ruby-to-go-and-saved-our-sanity/)
* [Timehop: Why Timehop Chose Go to Replace Our Rails App](https://medium.com/building-timehop/why-timehop-chose-go-to-replace-our-rails-app-2855ea1912d)
* [Scout App: FROM RUBY TO GO: A REWRITE FOR THE FUTURE](http://blog.scoutapp.com/articles/2014/09/25/from-ruby-to-go-a-rewrite-for-the-future)
* [Steven Yue: From Ruby's Grape to Martini in Go for Building Web API Server](http://stevenyue.com/blogs/from-rubys-grape-to-martini-in-go-for-building-web-api-server/)
* [Soundcloud: Go at Soundcloud](https://developers.soundcloud.com/blog/go-at-soundcloud)
* [My impressions of Go](http://blog.bensigelman.org/post/56158760736/golang-impressions)
* [Our Experience with Golang](https://www.upguard.com/blog/our-experience-with-golang)
* [Rewriting our web analytics tracking infrastructure in Go](https://engineering.skroutz.gr/blog/rewriting-web-analytics-tracking-in-go/)
# Java
* [From Java to Go](https://gquintana.github.io/2017/01/15/From-Java-to-Go.html)
* [Why one developer switched from Java to Google Go](http://www.javaworld.com/article/2459212/scripting-jvm-languages/why-one-developer-switched-from-java-to-google-go.html)
# Common Lisp
* [A comparison of three programming languages for a full-fledged next-generation sequencing tool](https://bmcbioinformatics.biomedcentral.com/articles/10.1186/s12859-019-2903-5)
* [Comparing Ease of Programming in C++, Go, and Java for Implementing a Next-Generation Sequencing Tool](https://doi.org/10.1177%2F1176934319869015)
# .NET
* [Why I Left the .NET Framework](http://blog.jonathanoliver.com/why-i-left-dot-net/)
# Scala
* [CrowdStrike: Moving a Team from Scala to Go](http://jimplush.com/talk/2015/12/19/moving-a-team-from-scala-to-golang/)
* [Making the move from Scala to Go, and why we’re not going back](https://movio.co/blog/migrate-Scala-to-Go/)
# PHP
* [Switching from PHP to Go (read comments section)](https://www.reddit.com/r/golang/comments/3wfnru/switching_from_php_to_go/)
* [A Journey into Microservices](https://sudo.hailoapp.com/services/2015/03/09/journey-into-a-microservice-world-part-1/)
* [ARDUINO WEB ARCHITECTURE, BACK TO THE FUTURE](https://blog.arduino.cc/2015/04/16/arduino-web-architecture-back-to-the-future/)
* [Marco switched to GoLang from PHP and Saved Money, why not you ?!](http://phpmagazine.net/2015/02/marco-switched-to-golang-from-php-and-saved-money-why-not-you.html)
* [Moving from PHP (Laravel) to Go](https://dannyvankooten.com/laravel-to-golang/)
* [When All You Have is an ElePHPant (Slides from ConFoo 2016)](https://www.ramblinations.com/when-all-you-have-is-an-elephpant)
# Perl
* [How We Migrate From Perl to Golang](https://medium.com/@alvintz.v/how-we-migrate-from-perl-to-golang-1520a4951392)
# Haskell
* [Golang’s Real-time GC in Theory and Practice](https://blog.pusher.com/golangs-real-time-gc-in-theory-and-practice/)
# Clojure
* [Rewriting an API Gateway Service from Clojure to Golang: AppsFlyer Experience Report](https://www.infoq.com/articles/api-gateway-clojure-golang)

33
Frozen.md

@ -1,33 +1,4 @@
Sometimes a package reaches the end of its development cycle and is considered complete. It continues to be maintained, meaning regressions or breakages are fixed, but the scope becomes frozen and no new features are meant to be accepted. The Go wiki on GitHub has moved to go.dev (#61940).
Freezing a package is a message primarily for developers and contributors to the package, not users. It does not imply that the package should not be used. For that, see the ["Deprecated" convention](Deprecated). Try <https://go.dev/wiki/Frozen> or <https://go.dev/wiki/>.
To signal that a package is frozen and is not accepting new features, add a paragraph to its doc comment stating that, and a recommendation on where to look for and where to contribute new features, if applicable.
## Examples
```
// The syslog package is frozen and is not accepting new features.
// Some external packages provide more functionality. See:
//
// https://pkg.go.dev/search?q=syslog
```
```
// The smtp package is frozen and is not accepting new features.
// Some external packages provide more functionality. See:
//
// https://pkg.go.dev/search?q=smtp
```
```
// The net/rpc package is frozen and is not accepting new features.
```
```
// The testing/quick package is frozen and is not accepting new features.
```
```
// The text/tabwriter package is frozen and is not accepting new features.
```

32
Fuzzing-trophy-case.md

@ -1,32 +1,4 @@
# Fuzzing trophy case The Go wiki on GitHub has moved to go.dev (#61940).
This page collects issues that have been discovered using [Go's native fuzzing](https://github.com/golang/go/issues/44551).
## Contributing
If native fuzzing uncovered a bug in your project, please consider adding it to this list by editing this Wiki page directly, or by reaching out to katie@golang.org with the bug you'd like to share.
_Note: If you think the bug is a security issue, please report it responsibly to the respective team, and do not include it in this list until public disclosure._
## Trophies
<!-- If editing this list, please maintain alphabetical order -->
### Standard Library
* [go/scanner: inconsistent handling of NUL bytes in 1.17](https://github.com/golang/go/issues/46855)
* [time: ParseDuration can panic on invalid input](https://github.com/golang/go/issues/46883)
### Other projects
* [go-yaml/yaml/v3: yaml.Unmarshal() crashes on "#\n - - QI\xd7"](https://github.com/go-yaml/yaml/issues/744)
* [josephburnett/jd: crashes when validating JSON Patch test/replace operation](https://github.com/josephburnett/jd/commit/7064efc5df7c899ffc53b45be8915e3f4edc1684)
* [josephburnett/jd: JSON Patch to void failing round-trip](https://github.com/josephburnett/jd/commit/bd2fc2657f56c7c1f70a5971c18be32365afd1c7)
* [kokes/smda: nil pointer error](https://github.com/kokes/smda/commit/b41ac00b5f5acba60d93076347fc73fe2fbca340)
* [kokes/smda: out of bounds error](https://github.com/kokes/smda/commit/2c2548f211a1ed2c3547407e0b420e4340612278)
* [mvdan.cc/sh: syntax.Quote failed to quote the empty string](https://github.com/mvdan/sh/commit/92eab20da20af9c4005294abf937e387d87c8407)
* [mvdan.cc/sh: syntax.Quote misused `\x` escape sequences in mksh](https://github.com/mvdan/sh/commit/8bd780f971469bece51617a53da0e1c700c4a5b8)
* [mvdan.cc/sh: syntax.Quote can't quote the `0xFFFE` and `0xFFFF` runes in mksh](https://github.com/mvdan/sh/commit/6ff55fb976f3c39d1a382ff5af616c3665c7e501)
* [pelletier/go-toml: index out of range error in expect function](https://github.com/pelletier/go-toml/issues/561)
* [swaggest/form: panic on invalid keys in request](https://github.com/swaggest/form/issues/4)
* [yuin/goldmark: corner case errors](https://github.com/yuin/goldmark/issues/245)
* [DataDog/datadog-agent: fix edge case in tags normalization](https://github.com/DataDog/datadog-agent/pull/13235)
Try <https://go.dev/wiki/Fuzzing-trophy-case> or <https://go.dev/wiki/>.

78
GOPATH.md

@ -1,78 +1,4 @@
## GOPATH variable The Go wiki on GitHub has moved to go.dev (#61940).
Go development using dependencies beyond the standard library is done [using Go modules](https://go.dev/blog/using-go-modules). When using Go modules, the GOPATH variable (which defaults to `$HOME/go` on Unix and `%USERPROFILE%\go` on Windows) is used for the following purposes: Try <https://go.dev/wiki/GOPATH> or <https://go.dev/wiki/>.
- The `go install` command installs binaries to `$GOBIN`, which defaults to `$GOPATH/bin`.
- The `go get` command caches downloaded modules in `$GOMODCACHE`, which defaults to `$GOPATH/pkg/mod`.
- The `go get` command caches downloaded checksum database state in `$GOPATH/pkg/sumdb`.
See the [go command documentation](https://pkg.go.dev/cmd/go#hdr-GOPATH_environment_variable) for full details about the GOPATH variable. The rest of this page concerns the GOPATH development mode, which is now deprecated.
## GOPATH development mode
Before Go modules, Go development using dependencies used “GOPATH development mode,” or “GOPATH mode” for short. In GOPATH mode, the `go` command used the GOPATH variable for the following purposes:
- The `go install` command installed binaries to `$GOBIN`, which defaults to `$GOPATH/bin`.
- The `go install` command installed the compiled package file for `import "example.com/y/z"` to `$GOPATH/pkg/example.com/y/z.a`.
- The `go get` command downloaded source code satisfying `import "example.com/y/z"` to `$GOPATH/src/example.com/y/z`.
## Deprecating and removing GOPATH development mode
Go modules are the replacement for GOPATH development mode to add the concept of a package version throughout the Go ecosystem.
The transition from GOPATH development mode to Go modules has been gradual, spread across many Go releases:
- **Go 1.11 (August 2018)** introduced the `GO111MODULE` variable, which defaulted to `auto`.
With `GO111MODULE=off`, the `go` command used GOPATH mode always.
With `GO111MODULE=on`, the `go` command used module mode always.
With `GO111MODULE=auto` (or leaving `GO111MODULE` unset), the `go` command decided the mode based on the current directory. If the current directory was _outside_ `$GOPATH/src` and was within a source tree with a `go.mod` file in its root, then the `go` command used Go module mode. Otherwise the `go` command used GOPATH mode. This rule ensured that all commands run in `$GOPATH/src` were unaffected in `auto` mode but let users experiment with modules in other directories.
- **Go 1.13 (August 2019)** adjusted `GO111MODULE=auto` mode to remove the `$GOPATH/src` restriction: if a directory inside `$GOPATH/src` has a `go.mod` file, commands run in or below that directory now use module mode. This allows users to continue to organize their checked-out code in an import-based hierarchy but use modules for individual checkouts.
- **Go 1.16 (February 2021)** will change the default to `GO111MODULE=on`, using module mode always. That is, GOPATH mode will be disabled entirely by default. Users who need one to use GOPATH mode for one more release can set `GO111MODULE=auto` or `GO111MODULE=off` explicitly.
- **Go 1.NN (???)** will remove the `GO111MODULE` setting and GOPATH mode entirely, using module mode always.
Note that removing GOPATH development mode does _not_ mean removing the GOPATH variable. It will still be used for the purposes listed at the top of this page.
## FAQ
### Is the GOPATH variable being removed?
No. The GOPATH variable (set in the environment or by `go env -w`) is **not** being removed. It will still be used to determine the default binary install location, module cache location, and checksum database cache location, as mentioned at the top of this page.
### Can I still write code in GOPATH/src/import/path?
Yes. Many Go developers appreciate the structure that this convention provides and check out their module repositories into it. All your code needs to get started with modules is a `go.mod` file. See [`go mod init`](https://pkg.go.dev/cmd/go#hdr-Initialize_new_module_in_current_directory).
### How can I compile one repo in GOPATH/src against changes made in another?
If you want to use unpublished changes in one module when building another, you can add a `replace` line to the other module’s `go.mod`.
For example, if you have checked out `golang.org/x/website` and `golang.org/x/tools` to `$GOPATH/src/golang.org/x/website` and `$GOPATH/src/golang.org/x/tools`, then to make your local builds of `website` automatically use changes in `tools`, you would add this to `$GOPATH/src/golang.org/x/website/go.mod`:
replace golang.org/x/tools => ../tools
Of course, `replace` directives know nothing about `$GOPATH`. The same line would work fine if you had checked the two out into `$HOME/mycode/website` and `$HOME/mycode/tools`.
### Why is GOPATH development mode being removed?
At its core, GOPATH development mode essentially supplies all those kinds of `replace` lines automatically, so that the code you build for dependencies is the code you happen to have checked out on your computer. That means your build is affected by old checkouts you happen to have lying around that you might have forgotten about. It means that the build you get on one machine can be different from another, even starting with the same version of the same top-level repo. And it means that the builds you get can be different from the ones another developer in the same project gets. Go modules address all these reproducibility concerns. The root cause of all these problems is that GOPATH mode does not have any concept of a package _version_.
In addition to reproducibility, Go modules provide a clear way to handle proxying and secure downloads. When you `git clone` a project and then grab its dependencies, those dependencies are being cryptographically checked (using the `go.sum` file) to make sure they're the same bits the original developer used. The only trusted part is the top-level `git clone`. Here again, this is only possible because Go modules, in contrast to GOPATH mode, have a concept of a package version.
And for future evolution of Go itself, modules clearly mark which version of the Go language a particular tree of files is written in. This makes it possible to disable problematic features—for example, `string(1)`, which many people think produces `"1"` but actually produces `"\x01"` (Ctrl-A)—in later versions of Go while keeping older programs building (because they are explicitly marked as having been written for the older version of Go).
There are more examples like these.
None of this is possible with GOPATH development mode as it exists today. We can't move the ecosystem forward and start really depending on these important properties of Go modules without retiring GOPATH mode.
(You might also ask: why not just add those things to GOPATH mode? The answer is: we did, and the result is Go modules.)
### When was it decided to deprecate GOPATH development mode?
The [original plan](https://go.dev/blog/modules2019) was to deprecate GOPATH mode in Go 1.13, but we wanted to take extra time to make modules even more robust for as many Go users as possible, so the deprecation was pushed back from that release. Discussion on [issue #41330](https://go.dev/issue/41330) and in the golang-tools group did not identify any remaining blockers for deprecating GOPATH, so it is now scheduled for Go 1.16, with removal in a future release, as stated in the timeline above.
### What if I have more questions about moving from GOPATH development mode to Go modules?
See [golang.org/help](https://go.dev/help) for a list of resources. If none of those are appropriate, feel free to [file an issue](https://go.dev/issue) here. We want everyone to be successful adopting Go modules.

61
Gardening.md

@ -1,61 +1,4 @@
# Gardening The Go wiki on GitHub has moved to go.dev (#61940).
## What is gardening? Try <https://go.dev/wiki/Gardening> or <https://go.dev/wiki/>.
"Gardening" in open source projects refers to the background maintenance tasks done to keep the project healthy & growing & nice looking.
This page lists common Go gardening tasks.
## Access
If you've been regularly active in the Go community for some time, feel free to ask for Gerrit and/or Github access to modify things.
See https://go.dev/wiki/GerritAccess and https://go.dev/wiki/GithubAccess
## Gardening Tasks
Before doing any gardening work, especially on the issue tracker, remember to familiarize yourself with the issues life-cycle, described here: [Handling Issues - Issue States](https://github.com/golang/go/wiki/HandlingIssues#issue-states).
### Fix red
Look at https://build.golang.org/ --- is anything red? Fix or file bugs or nag people. The build dashboard should never be red, even occasionally. If the tree is red, people can't work effectively because TryBots and such will just report failures, masking other problems.
### Triage new bugs
Look at the [untriaged issues](https://github.com/golang/go/issues?q=is%3Aopen+is%3Aissue+-label%3ANeedsInvestigation+-label%3ANeedsFix+-label%3ANeedsDecision+-label%3AWaitingForInfo+-label%3AGo2+-label%3AProposal+-label%3ACherryPickCandidate+-label%3ACherryPickApproved+no%3Aassignee+created%3A%3E2019-01-01+-label%3Agopls+-label%3Apkgsite). For Go, we use the presence of certain labels (`Needs*` or `WaitingForInfo`) to indicate that an issue has been triaged. Issues labeled `Go2`, `Proposal`, `CherryPickCandidate`, `gopls`, `pkgsite` have their own, separate triage queues and can be skipped.
While triaging the bug:
* is it a duplicate? Close it, referencing the dup.
* is it a Question rather than a bug? Reply with something like "For questions about Go, see https://go.dev/wiki/Questions".
* is the subject the correct format? It should start with the package path and a colon: "net/http: fix crash in Server during foo operation".
* is it in a subrepo? Leave the milestone as `Unreleased` unless it's a subrepo that goes into a release, like `http2`.
* if it is a regression and you can reproduce it, use `git bisect` to find the bad commit (optional but very helpful).
* does the relevant package [have a primary owner](https://dev.golang.org/owners)? Mention them in a comment. If not, add the `help wanted` label.
* if the relevant package has no owner, but appears to be complex and deeply technical in nature, add the `ExpertNeeded` label.
When the issue has been triaged, add an appropriate label (per https://go.dev/wiki/HandlingIssues) to mark it as such.
### WaitingForInfo
Find bugs that are in state WaitingForInfo (https://github.com/golang/go/labels/WaitingForInfo) and ping them, remove the label when replies arrive, or close the bugs if a reply never arrived.
### "Unplanned" bugs
["Unplanned" issues](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20milestone%3AUnplanned%20sort%3Aupdated-asc%20-label%3AGo2%20-label%3ALanguageChange) have a habit of being neglected. Check out old ones and see if they're easily fixable (and can be moved to a Go1.n or Go 1.nMaybe milestone), or should be closed.
### Pending CLs
[Review the format of commit messages](https://go.dev/doc/contribute#commit_messages) and presence of tests and formatting of code and typos/grammar in incoming pending CLs. All of that can be done without determining the correctness of the change itself. See https://dev.golang.org/release for the list of pending CLs.
Once it has a +1, the owner of that area can give it a +2.
Read a +1 as meaning "triaged", or "not obviously wrong". If it has tests, is formatted properly (references a bug number, probably), and is ready for more review, give it a +1.
### Pending CLs: ask about tests
If a new CL arrives without a test, but could/should have a test, ask if they could add a test. Or suggest how.
### Pending CLs: run TryBots
If you have access (see https://go.dev/wiki/GerritAccess) to run the TryBots and you see a CL with plausible (and non-malicious) code, kick off the TryBots. (We've never seen malicious code trying to escape our TryBot sandboxes, but that's why it's not automatic yet. Please alert us if you see something.)

108
GcToolchainTricks.md

@ -1,108 +1,4 @@
This page documents some less well-known (perhaps advanced) tricks for the ` gc ` toolchain (and the Go tool). The Go wiki on GitHub has moved to go.dev (#61940).
# C code without ` cgo ` Try <https://go.dev/wiki/GcToolchainTricks> or <https://go.dev/wiki/>.
### Use ` syso ` file to embed arbitrary self-contained C code
Basically, you write your assembly language in GNU as(1) format, but make sure
all the interface functions are using Go's ABI (everything on stack, etc., please read [Go 1.2 Assembler Introduction](https://go.dev/doc/asm) for more details).
The most important step is compiling that file to file.syso (` gcc -c -O3 -o file.syso file.S `),
and put the resulting syso in the package source directory.
And then, suppose your assembly function is named Func, you need one stub
[cmd/asm](https://pkg.go.dev/cmd/asm) assembly file to call it:
```as
TEXT ·Func(SB),$0-8 // please set the correct parameter size (8) here
JMP Func(SB)
```
then you just declare Func in your package and use it, go build will be able to
pick up the syso and link it into the package.
Notes:
* The binary produced won't use cgo, and the overhead is just an unconditional JMP that could be perfectly branch predicted. But, please be aware that because it doesn't use cgo, your assembly function is running on Go stack, and it **shouldn't use too much stack** (a safe value is less than ~100 bytes) or terrible things will happen. For compute kernels, this requirement isn't too restricting.
* Please make sure you‘ve included all library dependencies in your C code. ` libc ` is not available, and most notably, ` libgcc ` is also not available (esp. when you're using gcc ` __builtin_funcs `, please use ` nm(1) ` to double-check that your file doesn't contain any undefined symbols).
* It's also possible to call back Go functions from C code, but this is left as an exercise for the reader.
* this trick is supported on all Go 1.x releases.
* the Go linker is pretty capable in that you just need to prepare .syso file for each architecture, not for each OS/Arch combination (assuming you don't use OS-specific constructs, obviously), and the Go linker is perfectly capable to link, for example, Mach-O object files into ELF binaries. So be sure to name your syso file with names like ` file_amd64.syso `, ` file_386.syso `.
# Bundle data into Go binary
There are a lot of ways to bundle data in Go binary, for example:
* ` zip ` the data files, and append the zip file to end of Go binary, then use ` zip -A prog ` to adjust the bundled zip header. You can use ` archive/zip ` to open the program as a zip file, and access its contents easily. There are existing packages that helps with this, for example, https://pkg.go.dev/bitbucket.org/tebeka/nrsc; This requires post-processing the program binary, which is not suitable for non-main packages that require static data. Also, you must collect all data files into one zip file, which means that it's impossible to use multiple packages that utilize this method.
* Embed the binary file as a ` string ` or ` []byte ` in Go program. This method is not recommended, not only because the generated Go source file is much larger than the binary files themselves, also because static large ` []byte ` slows down the compilation of the package and the ` gc ` compiler uses a lot of memory to compile it (this is a known bug of ` gc `). For example, see the [tools/godoc/static](https://pkg.go.dev/golang.org/x/tools/godoc/static) package.
* use similar ` syso ` technique to bundle the data. Precompile the data file as syso file using GNU ` as(1) `'s ` .incbin ` pseudo-instruction.
The key trick for the 3rd alternative is that the linker for the ` gc ` toolchain has the ability to link COFF object files of a different architecture into the binary without problem, so you don't need to provide syso files for all supported architectures. As long as the syso file doesn't contain instructions, you can just use one to embed the data.
The assembly template to generate the COFF .syso file:
```as
/* data.S, as -o data.syso */
.section .rdata,"dr" /* put in COFF section .rdata */
.globl _bindataA /* no longer need to prepend package name here */
.globl _ebindataA
_bindataA:
.incbin "dataA"
_ebindataA:
.globl _bindataB /* no longer need to prepend package name here */
.globl _ebindataB
_bindataB:
.incbin "dataB"
_ebindataB:
```
And two other files, first a Plan 9 C source file that assembles the slice for Go:
```c
/* slice.c */
#include "runtime.h"
extern byte _bindataA[], _bindataB[], _ebindataA, _ebindataB;
void ·getDataSlices(Slice a, Slice b) {
a.array = _bindataA;
a.len = a.cap = &_ebindataA - _bindataA;
b.array = _bindataB;
b.len = b.cap = &_ebindataB - _bindataB;
FLUSH(&a);
FLUSH(&b);
}
```
And finally, the Go file that uses the embedded slide:
```go
/* data.go */
package bindata
func getDataSlices() ([]byte, []byte) // defined in slice.c
var A, B = getDataSlices()
```
Note: you will need an ` as(1) ` capable of generating the COFF syso file, you
can build one easily on Unix:
```
wget http://ftp.gnu.org/gnu/binutils/binutils-2.22.tar.bz2 # any newer version also works
tar xf binutils-2.22.tar.bz2
cd binutils-2.22
mkdir build; cd build
../configure --target=i386-foo-pe --enable-ld=no --enable-gold=no
make
# use gas/as-new to assemble your data.S
# all the other file could be discarded.
```
**Drawback** of this issue is that it seems incompatible to cgo, so only use it when you don't
use cgo, at least for now. I (minux) is working on figuring out why they're incompatible.
# Including build information in the executable
The gc toolchain linker, [cmd/link](https://pkg.go.dev/cmd/link), provides a `-X` option that may be used to record arbitrary information in a Go string variable at link time. The format is `-X importpath.name=val`. Here `importpath` is the name used in an import statement for the package (or `main` for the main package), `name` is the name of the string variable defined in the package, and `val` is the string you want to set that variable to. When using the go tool, use its `-ldflags` option to pass the `-X` option to the linker.
Let's suppose this file is part of the package `company/buildinfo`:
```go
package buildinfo
var BuildTime string
```
You can build the program using this package using `go build -ldflags="-X 'company/buildinfo.BuildTime=$(date)'"` to record the build time in the string. (The use of `$(date)` assumes you are using a Unix-style shell.)
The string variable must exist, it must be a variable, not a constant, and its value must not be initialized by a function call. There is no warning for using the wrong name in the `-X` option. You can often find the name to use by running `go tool nm` on the program, but that will fail if the package name has any non-ASCII characters, or a `"` or `%` character.

110
GccgoCrossCompilation.md

@ -1,110 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
If you want to run your Go programs on a platform that is not supported by the standard Go compiler _gc_ you can build a version of the GCC compiler that targets your desired target platform, since GCC supports many more platforms. This is possible because there is a Go frontend to GCC named [gccgo](https://github.com/golang/gofrontend). Try <https://go.dev/wiki/GccgoCrossCompilation> or <https://go.dev/wiki/>.
# Details
## Definitions
* **Build** This is the computer where you are building the cross-compiler.
* **Host** The computer that will run the cross-compiler once it's built. This is usually the same as Build.
* **Target** This is the destination system, where you want the cross-compiled program to run.
More definitions and complex cross situations can be found at the [Wikipedia article](http://en.wikipedia.org/wiki/Cross_compiler).
## Go tools and gccgo
You will later need to source code to the Go tool, so you might as well uninstall the version you have installed from your package manager to avoid confusion (fully optional tho). Also build & install gccgo targeting host(!, that's right, you need a gcco compiling for not only target but one for host).
* [Installing Go from source](https://go.dev/doc/install/source)
* [Official Go documentation](https://go.dev/doc/install/gccgo)
## Build the cross-compiler
### Build
First you have to build your cross-compiling version of GCC. This is complex process as it requires several stages with bootstrapping since there are mutual dependency relations between GCC and libc implementations. A very fine tutorial on how to build a GCC cross-toolchain with eglic (works with glibc too) was written by Jim Blandy and posted at eglibc's mailinglist [patches Cross-building instructions](http://www.eglibc.org/archives/patches/msg00078.html). In the final stage where the full GCC is built, simply configure script with _--enable-languages=c,c++,go_ (see [official Go documentation](https://go.dev/doc/install/gccgo)).
You can use the [ewxb\_gcc\_cross-compiler\_builder](https://github.com/erikw/ewxb_gcc_cross-compiler_builder) script as a starting point. Don't expect that script to work out of the box, but rather as a hint to which steps you're likely to take when building your x-toolchain.
If you're lucky enough and want a version of GCC that is not bleeding edge (which you might want to have the latest Go features) you can use a cross-compiler builder to ease the configuration e.g. [crosstool-NG](http://crosstool-ng.org/) that lets you configure GCC with a simple TUI menu.
Newer versions of crosstool-NG can build the go language by enabling ```CT_EXPERIMENTAL``` and ```CT_CC_SUPPORT_GOLANG```. This will automatically add ```go``` to ```--enable-languages```.
### Symlink
You should now have a bin directory with files with names like "` <target `>-gcc", "` <target `>-gnu-gccgo" etc. Because the go build tool does not allow you to specify file-names of the compilers to use (only statically supports the strings 'gc' and 'gccgo') it will look in your $PATH envvar for the first file named 'gccgo' and 'gcc'. You will therefore have to add this directory as an overlay by setting it to be the first one in $PATH when you want to use the cross-compiler and not your normal gcc binary on your system. Since the go tool looks for a binary named _gccgo_ you'll have to make some symlinks for the tools you want it to find.
```
$ cd path/to/cross-comp-gcc/bin
$ ln -s <arch>-<os>-gnu-gcc gcc
$ ln -s <arch>-<os>-gnu-gccgo gccgo
$ ln -s <arch>-<os>-gnu-ar ar
$ export PATH="path/to/crosscomp-gcc/bin:$PATH" # Do this whenever you want to use the cross-compilers targeting your target instead of the system default targeting host.
```
etc.
With $TARGET set to the target architecture and $PREFIX set to the destination path of the built files, you can make the symlinks with:
```
#!/usr/bin/env bash
cd $PREFIX/bin
for file in $(find . -type f); do
tool_name=$(echo $file | sed -e "s/${TARGET}-\(.*\)$/\1/")
ln -sf "$file" "$tool_name"
done
```
### Test
When the cross-compiler is build you should test that it works, both for a simple C program and a simple Go program.
```
$ gccgo -Wall -o helloworld helloworld.go
$ file helloworld # verify that the architecture of the binary is the desired target and not a binary that can run on your host machine.
$ <upload-command-to-target> helloworld
$ <ssh/telnet etc. to target and test run>
```
### Gotchas
If you haven't compiled a shared object of the go library, _libgo_, for your target you might want to compile your Go programs statically, just like _gc_ does, to include all what is needed to run your program. Do this by adding the _-static_ switch to gccgo. If you're unsure how your produced ELF file is linked, inspect it with _readelf -d `<elf>`_ or _objdump -T `<elf>`_.
## Build a cross-gccgo aware version of the Go tool
### Assumptions
* Assuming that you've followed the instructions on [Installing Go from source](https://go.dev/doc/install/source) you should have a checked out version of the go source at _$GOROOT_.
* Envvar _$GOROOT_ is set.
* The envvars _$GOARCH_ and _$GOOS_ represent the **target** architecture and operating system. Figure these out and set them to these values when you want to cross-compile.
### Build
You can specify the compiler to use when building with the go tool with _go build -compiler gccgo ` <go-package,files> `_. This is however not enough. If you have set _$GOARCH_ and _$GOOS_ to something that is not supported by _gc_ but with _gccgo_ you have to build a special version of the go tool that understands these extra architectures. If you compile another version of the go tool with the go tool but specify to use gccgo targeting your host, the resulting go tool will be able to compile programs with all the architectures supported by gccgo.
```
$ cd ~/tmp
$ hg clone ~/src/go # [0]
$ cd go/src/cmd/go
$ go build -o xgo -compiler gccgo . # [1] [2] [3]
$ cp xgo ~/bin/ # Or any directory that is in your $PATH
```
* ` [0 `] Clone Go source to directory outside $GOROOT. Needed since the cmd/go we're about to compile is handles specially.
* ` [1 `] Here the _gccgo_ that targets **host** must be used, and not the cross-compiling gccgo. Make sure to have you _$PATH_ set correctly for this.
* ` [2 `] Will produce binary named xgo to distinguish from the existing go-binary. Name it to something suitable, e.g. mgo if your target is MIPS.
* ` [3 `] The compilation step (go build) can fail with some compilation errors since gccgo is lagging behind the go project (at least at go mercurial tip 7f2863716967). Fix those errors by commenting out or something more clever and re-compile.
## Cross-compile Go programs.
With your _$PATH_ set to find _xgo\_and the cross-compiling version of_gccgo and _$GOARCH_ set properly you can now cross-compile using the go tool (named xgo).
```
$ export PATH="path/to/xgo/:path/to/crosscomp-gccgo/:$PATH"
$ export GOARCH="<you-target's-arch>"
$ export GOOS="<you-target's-OS>"
$ xgo build -compiler gccgo <go-package/files>
```
## TODO
Go-programs importing "C" does not seems to work using xgo. Currently blocked by [Go issue#7398](https://github.com/golang/go/issues/7398)
This Wiki page was inspired by the lessons learned from "[golang-nuts] Simplification of MIPS cross-compilation?" @ https://groups.google.com/forum/#!topic/golang-nuts/PgyS2yoO2jM

64
GerritAccess.md

@ -1,64 +1,4 @@
# Gerrit Access The Go wiki on GitHub has moved to go.dev (#61940).
There are two types of Gerrit access described here, with different powers & responsibilities. Only ask for access if you're an active member of the community. New contributors should participate in the Gerrit code review process for some time before requesting access. Try <https://go.dev/wiki/GerritAccess> or <https://go.dev/wiki/>.
(For Github access, see https://go.dev/wiki/GithubAccess)
## Running TryBots ("may-start-trybots")
TryBot access lets you kick off a test run of a CL in Gerrit prior to submission (pre-submit testing).
TryBots run in a somewhat-secure and somewhat-isolated environment,
but they're not perfectly security hardened.
You must skim the CL for anything malicious before starting TryBots.
See [LUCI](https://go.dev/wiki/LUCI#TryBots) for details on triggering TryBots.
All approvers (see next section) have TryBot access automatically. Others can request TryBot access. See [Requesting Access](#requesting-access) below.
## Approving CLs ("approvers")
Approvers can review and submit code changes (CLs), subject to the review rules described below. Being an approver comes with an expectation of responsibility: approvers are people who care about Go and want to help it succeed. An approver is not just someone who can make changes, but someone who has demonstrated their ability to collaborate with the team, get the most knowledgeable people to review code, contribute high-quality code, and follow through to fix issues (in code or tests).
### Code Review Requirements
Every CL requires _both_ a code review (Code-Review+2) from an approver and the involvement of two Google employees using Google-secured computers, either as code uploader or as a reviewer voting at least Code-Review+1. Requiring multiple people ensures that code cannot be submitted unilaterally from a single compromised account. The Google employee and hardware requirements further raise the bar: since CLs in many repos are essentially published by Google for download by users at commit time, the Google involvement is to approve this publication. Once a review has a Code-Review+2 and the necessary Google involvement, it can be submitted, by any approver. All these rules are enforced by the Gerrit server.
A Code-Review+2 vote means that you have read the change and are confident that it is correct and appropriate to submit. Typically, you should only Code-Review+2 code in directories or packages that you "own"; the exception is trivial and obviously correct changes. Note that all user-visible new features or changes—new API, new command-line flags, and so on—need to go through the [proposal process](https://go.dev/s/proposal-process). The CLs should reference the specific accepted proposal [in the commit message](https://github.com/golang/go/wiki/CommitMessage) (“For #NNN.”).
When adding a Code-Review+2 vote, it is encouraged to also add Run-TryBots+1 and Auto-Submit+1: see the [auto-submit](#auto-submit) section below for details.
A Code-Review+1 vote means that you have read the change and believe it seems reasonable but aren’t making the definitive judgement that Code-Review+2 indicates. It also means you are confident the change does not introduce any sort of security vulnerability or other clearly inappropriate code change.
When a change has the appropriate reviews to be submitted, a Submit button appears in Gerrit (for approvers). You should only submit changes with a Code-Review+2 from the owner of that area (maybe you!).
Approvers can also vote Hold+1 on a CL to mark it as unsubmittable (until that vote is removed). A typical reason might be that we need to wait on the CL for a proposal review, or because the CL needs to be submitted at a certain time: voting Hold+1 ensures that it can still be reviewed, but it won't accidentally be submitted early.
To request approver access, see [Requesting Access](#requesting-access) below.
### Auto-Submit
If you are reviewing a CL and believe it can be approved and submitted as is,
with no further changes, you can use the auto-submit functionality
to run tests and submit the CL if the tests pass.
To do this, vote Code-Review+2 as well as Auto-Submit+1 and Run-TryBot+1. When the tests pass, Gopherbot will submit it.
More precisely, Gopherbot watches for and automatically submits CLs that
- have Auto-Submit+1 and TryBot-Result+1 votes,
- have the necessary code reviews,
- have no unresolved comments,
- aren't marked #wait-release,
- and merge cleanly into the current branch head.
All approvers can add Auto-Submit+1 votes.
An Auto-Submit+1 vote is not carried forward when a patch is reuploaded.
# Requesting Access
To get request either of the access types above, file a bug (https://github.com/golang/go/issues/new?title=access:+&body=See+https://go.dev/wiki/GerritAccess) and list and state which access you want, and state the Google account you use to log in to Gerrit.
Decisions about granting access are made by the Go release team at Google. If your request is declined, it is almost always because you haven't been active enough for them to get a clear enough signal about your work, understanding of project conventions, and so on. Don't lose heart: it can take time to reach that level of familiarity.
## Once you have access
Go help garden! See https://go.dev/wiki/Gardening.

78
GerritBot.md

@ -1,78 +1,4 @@
GerritBot is a tool used for importing GitHub Pull Requests (PRs) into [Gerrit](https://go-review.googlesource.com) for code review. It was created because the Go team does all its reviews in Gerrit, but we'd like to allow a more common workflow for contributing code via GitHub PRs. The Go wiki on GitHub has moved to go.dev (#61940).
Table of Contents Try <https://go.dev/wiki/GerritBot> or <https://go.dev/wiki/>.
=================
+ [Workflow](#workflow)
+ [Frequently Asked Questions](#frequently-asked-questions)
+ [Feedback and Bug Reports](#feedback-and-bug-reports)
+ [I'd like to add a feature/fix a bug](#id-like-to-add-a-featurefix-a-bug)
## Workflow
+ A user can upload a GitHub PR against any of our GitHub repos just as they would with any other GitHub project that accepts PRs
+ The PR changes will then be imported by GerritBot and a message will be posted to the GitHub PR containing a link to the Gerrit review
+ All comments are handled within Gerrit. Any comments on the GitHub PR will be ignored
+ The PR author can continue to upload commits to the branch used by the PR in order to address feedback from Gerrit
+ Any changes to the commit message must be done by editing the title and description of the GitHub PR, and not via Gerrit or git. (See FAQ below for details).
+ [Draft PRs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) are imported as [WIP](https://gerrit-review.googlesource.com/Documentation/intro-user.html)
+ Once the code is ready to be merged, a maintainer will submit the change on Gerrit and GerritBot will close the issue
+ Similarly, if a change is closed or abandoned on Gerrit, the corresponding PR will be closed
## Frequently Asked Questions
### I need a Google account to sign up for Gerrit? Why can't I sign in using my GitHub account?
You need a Gmail or other Google account to [register for Gerrit](https://go-review.googlesource.com/login/).
This is a limitation of the infrastructure that runs our Gerrit instances and is out of our control, plus you already need a Google account to [sign our CLA](https://cla.developers.google.com/clas), a requirement for us to accept your contribution in the first place.
### I left a reply to a comment in Gerrit but no one but me can see it
Replies to comments on code in Gerrit are first saved as drafts and need to be published via the “Reply” button. This is to prevent multiple emails per review “session” and is similar to the [pending review workflow](https://help.github.com/articles/reviewing-proposed-changes-in-a-pull-request/) in GitHub. If you see a number next to the “Reply” text in the button, this means you have pending drafts to publish.
### How does GerritBot determine the final commit message?
It uses the title and description of the GitHub PR to construct the commit message for the Gerrit change. You can edit this using the GitHub web interface (not Gerrit or git). The PR description is in the first text area in the "Conversation" tab of the GitHub PR. It is editable via "Edit" option on the "..." menu.
**Note:** Gerrit imports the **plain** text that is viewable as you edit the message in Github, and it does not import the **rendered** text you see in GitHub prior to editing.
One common area of related confusion is around **issue references**. For example, GerritBot or a human reviewer might ask you to [avoid URLs for issue references](https://go.dev/doc/contribute#ref_issues). In Gerrit, you might see the full URL for an issue, but in the GitHub web interface, you might only see an issue reference like `#12345` and it might be unclear where the URL is coming from. This can be due to confusion between the rendered view in GitHub vs. the underlying raw/plain text. If the GitHub web interface shows something like `Fixes https://github.com/golang/go/issues/12345` while you are **editing the text in GitHub**, change it to something like `Fixes #12345` or `Fixes golang/go#12345` instead. See the [Contribution Guide](https://go.dev/doc/contribute#ref_issues) for more on issue references.
Once the PR is edited in GitHub, it can take 10 minutes or so before the Gerrit change is updated.
### What is a CL? What is a Gerrit change?
CL is short for "change list", which is essentially a patch proposed to be introduced into a repository. The Go project uses Gerrit to carefully review each CL. An example CL is https://go.dev/cl/508475.
Gerrit change is another term for CL.
### Can I help review other people's CLs?
Yes, this is highly encouraged, and a great way to familiarize yourself with Gerrit, the Go project's [code review process](https://go.dev/doc/contribute#review), and the internals of the Go standard library, runtime, compiler, and so on.
You can browse the currently open CLs [here](https://go-review.googlesource.com/q/status:open+-is:wip) and subscribe for updates to interesting CLs by clicking the star icon.
You don't need to be an expert in the code to help with initial review triage. See the section on [helping to review CLs](https://github.com/golang/go/wiki/Gardening/#pending-cls) in the [Gardening](https://github.com/golang/go/wiki/Gardening) wiki page for more details.
### I heard Gerrit requires one commit per change. Can I upload multiple commits to my PR?
You can upload as many commits as you like. GerritBot will handle squashing your commits into one change that Gerrit can handle.
### Why is GerritBot the owner of my change?
This is due to an [open bug](https://bugs.chromium.org/p/gerrit/issues/detail?id=8296) with the way Gerrit handles acting as another user. Once that is fixed, the original author will also be the owner of the change.
### Can I ask GerritBot to stop posting comments on my PR?
You can toggle comments from GerritBot by using the `comments` slash command (e.g., `/comments off`).
## Feedback and Bug Reports
Please [file an issue](https://github.com/golang/go/issues/new?title=x%2Fbuild%2Fcmd%2Fgerritbot%3A%20%3Cfill%20this%20in%3E) and use the `x/build/cmd/gerritbot:` prefix in the title.
## I'd like to add a feature/fix a bug
+ If the feature/bug is non-trivial, please [file an issue](https://github.com/golang/go/issues/new?title=x%2Fbuild%2Fcmd%2Fgerritbot%3A%20%3Cfill%20this%20in%3E) first
+ The code is located at x/build/cmd/gerritbot
([GitHub](https://github.com/golang/build/tree/master/cmd/gerritbot),
[Gerrit](https://go.googlesource.com/build/+/master/cmd/gerritbot/))

27
GithubAccess.md

@ -1,27 +1,4 @@
# Github Access The Go wiki on GitHub has moved to go.dev (#61940).
There are two types of Github access described here, with different powers & responsibilities. Only ask for access if you're an active member of the community. New contributors should participate in the Github & Gerrit review process for some time before requesting access. Try <https://go.dev/wiki/GithubAccess> or <https://go.dev/wiki/>.
(For Gerrit access, see https://go.dev/wiki/GerritAccess)
## Assignees
The "go-assignees" group is a read-only group granting no special access, other than it allows the users in the group to be assigned issues.
In general, Go doesn't use the "Assigned to" field of bugs much. Instead, we just leave a comment saying we'll work on it. But if you want this access, reference https://github.com/orgs/golang/teams/go-assignees and your Github username in your issue requesting access.
## Editors
The "go-editors" group is the set of people who can edit metadata on issues.
To request this type of access, reference https://github.com/orgs/golang/teams/go-editors and your Github username in your issue requesting access.
Please do not edit any field you're not confident about. Feel free to ask for second opinions.
## Requesting Access
To get request either of the access types above, file a bug (https://github.com/golang/go/issues/new?title=access:+&body=See+https://go.dev/wiki/GithubAccess) and list and state which access you want (its name and group URL).
## Once you have access
Go help garden! See https://go.dev/wiki/Gardening.

101
Go-1.10-Release-Party.md

@ -1,101 +1,4 @@
### What's happening? The Go wiki on GitHub has moved to go.dev (#61940).
To celebrate the release of Go 1.10 we're to organising a world wide release party during the month of February 2018 🎉
#### So what is the release date? Try <https://go.dev/wiki/Go-1.10-Release-Party> or <https://go.dev/wiki/>.
Go 1.10 was released on February 16.
### Sounds awesome, how can you get involved?
- If you host a Go user group or meetup, schedule a meetup during February, and celebrate with Gophers around the world.
- If you're a member of a Go user group or meetup, pester your organiser and let them know you'd like to participate.
After the event post a photo, make a video, write a blog post, scribble on your Facebook wall, or tweet something pithy. Let's see how big we can make the celebration.
Spread the word using hashtag [#GoReleaseParty](https://twitter.com/hashtag/goreleaseparty)
Don't forget to add your meetup's details :point_down: right here.
#### Who's involved?
Here is a list of the groups who are participating.
- Madrid, Spain: Feb 8 7:30 pm at [source{d}](https://sourced.tech). [View the event](https://www.meetup.com/go-mad/events/247296417/)
- Copenhagen, Denmark: Feb 15 7:00 pm at Maersk. [View the meetup](https://www.meetup.com/Go-Cph/events/242615767/)
- Minsk, Belarus: Feb 15 7:00 pm at SPACE. [View the event](https://www.facebook.com/events/202545833823265/)
- London, UK: Feb 15 6:30 pm at Shazam. [View the meetup](https://www.meetup.com/Go-London-User-Group/events/247343552/)
- Paris, France: Feb 15 7:15 pm at Mobiskill. [View the meetup](https://www.meetup.com/Golang-Paris/events/247526552)
- Orlando, FL, United States: Feb 19 7:00 PM at Familab. [View the meetup](https://www.meetup.com/OrlanGo/)
- Shizuoka, Japan: Feb 20 6:30 pm at Ageya Take. [View the event](https://shizuoka-go.connpass.com/event/79570/)
- Jakarta, Indonesia: Feb 20 7:00pm at Hacktiv8. [View the event](https://www.meetup.com/GoJakarta/events/247559760/)
- Tokyo, Japan: Feb 20 7:00 pm at Google Tokyo. [View the event](https://gocon.connpass.com/event/78128/)
- Okayama, Japan: Feb 20 7:00 pm at Kurashiki Coffee Okayama Aoe. [View the event](https://connpass.com/event/79528/)
- Reston, VA, USA: Feb 21 6:45 pm at Comcast. [View the meetup](https://www.meetup.com/Golang-Reston/events/246828702/)
- San Francisco, CA: Feb 21 6:00 pm at Cloudflare [View the event](https://www.meetup.com/golangsf/events/245472050/)
- Phoenix, AZ, United States: Feb 22 6:30 PM at Galvanize. [View the meetup](https://www.meetup.com/Golang-Phoenix/events/247751393/)
- Warsaw, Poland: Feb 22 7:00 pm at Kawiarnia Crux [View the meetup](https://www.meetup.com/pl-PL/Golang-Warsaw/events/247732050/)
- Santiago, Chile: Feb 22 7:00 pm at Mercado Libre Chile. [View the meetup](https://www.meetup.com/golang-chile/events/247511315/)
- Aachen, Germany: Feb 22 7:00pm at hosting.de. [View the meetup](https://www.meetup.com/Gophers-Aachen/events/247739398/)
- Waterloo, Canada: Feb 22 7:00pm at the Lion Brewery in the Heuther Hotel. [View the meetup](https://www.meetup.com/Golang-KW/events/247770215/)
- Lodz, Poland: Feb 22 6:00 pm at Co/Walk HUB [View the meetup](https://www.meetup.com/Golang-Lodz/events/247802682/)
- İzmir, Turkey: Feb 23 7:30 pm at Drunken Duck [View the event](https://www.facebook.com/events/144640862880347/)
- Milan, Italy: Feb 23 8:00 pm at Venini42 [View the event](https://www.meetup.com/it-IT/Golang-Milano/events/247741405/)
- Bengaluru, India: Feb 24 10:00 am at OpenEBS Office Space. [View the meetup](https://www.meetup.com/Golang-Bangalore/events/247344493/)
- Moscow, Russia: Feb 24 11:30 am at Badoo. [View the meetup](https://golang-moscow.timepad.ru/event/663880/)
- Yoshkar-Ola, Russia: Feb 24 2:00 pm at iSpring. [View the meetup](https://golang-yoshar-ola.timepad.ru/event/667643/)
- Zagreb, Croatia: Feb 26 6:00 pm at MaMa. [View the meetup](https://www.meetup.com/Golang-ZG/events/247644001/)
- Edmonton, Canada: Feb 26 6:30 pm at Startup Edmonton [View the meetup](https://www.meetup.com/startupedmonton/events/247825453/)
- Berlin, Germany: Feb 26 7:00 pm at n26. [View the meetup](https://www.meetup.com/golang-users-berlin/events/247289781/)
- Stockholm, Sweden: Feb 27 17:30 at Betalo. [View the meetup](https://www.meetup.com/Go-Stockholm/events/247955211/)
- Baltimore, MD: Feb 27 06:30pm at ZeroFOX. [View the meetup](https://www.meetup.com/BaltimoreGolang/events/247958575/)
- Joinville, Brazil: Feb 27 7:00 pm at ContaAzul. [View the meetup](https://www.meetup.com/Joinville-Go-Meetup/events/247548485/)
- Brisbane, Australia: Feb 28 6:00 pm at Jumbo Interactive. [View the meetup](https://www.meetup.com/Brisbane-Golang-Meetup/events/247337741/)
- Frankfurt, Germany: Feb 28 6:30 pm at SANID GmbH, [View the meetup](https://www.meetup.com/gophers-frm/events/247776234/)
- Chicago, IL: Feb 28 6:00pm at Enova. [View the meetup](https://www.meetup.com/Women-Who-Go-Chicago/events/247802512/) & [View the meetup](https://www.meetup.com/Chicago-Gophers/events/247805023/)
- Fort Lauderdale, FL: Mar 1 6:30 pm at Microsoft, [View the meetup](https://www.meetup.com/Go-Miami/events/247987413/)
- Zurich, Switzerland: Mar 1 7:00 pm at Job Cloud. [View the meetup](https://www.meetup.com/Zurich-Gophers/events/246188927/)
- Florianópolis, Brazil: Mar 17 3:00 pm at Involves. [View the meetup](https://www.meetup.com/pt-BR/Floripa-Gophers/events/kzmchpyxfbwb/)
- Portland, Oregon: April 24th 6:00 pm at New Relic. [View the meetup](https://www.meetup.com/PDX-Go/events/248938586/)
_If your group is not listed here yet, edit the page and add yourself in a chronological order._
_Organisers, once you've added your group, consider tweeting out a link to the page to raise awareness._
### Stay in touch
Trying to co-ordinate dozens of meetup groups around the globe will be challenging. Here are some ways you can plan your event, and keep up to date.
As always, if you get stuck, or need help, please [contact the organisers directly](https://github.com/golang/go/wiki/Go-1.10-release-party#no-seriously-whos-organising-this), we're here to help.
.
##### Slack Channel
We have a channel for the [release party](https://gophers.slack.com/messages/go-release-party/) on the [Gophers Slack](https://gophers.slack.com/messages/go-release-party/). If you need an invite to Slack, [you can request an automatic invite with this link](https://invite.slack.golangbridge.org/).
##### Mailing list
We have set up a [mailing list for meetup organisers](https://groups.google.com/forum/#!forum/go-meetup-organisers) to ask questions.
### What happens in a release party?
As with the previous [Go 1.6](https://github.com/golang/go/wiki/Go-1.6-release-party) and [Go 1.8](https://github.com/golang/go/wiki/Go-1.8-release-party) release parties, this is a great opportunity to spread the word about the improvements landing 1.10, and the plans for what is coming next!
#### Resources
You can use the slide deck that the Go London User Group in London will use. It's [available here](https://talks.godoc.org/github.com/dlsniper/talks/2018/go-1.10-release-party/presentation.slide#1) ([source](https://github.com/dlsniper/talks/tree/master/2018/go-1.10-release-party))
_Please send PR's with corrections/additions_
[Here's a link to the _draft_ Go 1.10 release notes](https://tip.golang.org/doc/go1.10).
[Here's a link](https://speakerdeck.com/campoy/the-state-of-go-1-dot-10) to the talk by Francesc Campoy: The State of Go (February 2018).
### What'll happen if Go 1.10 isn't out during February?
If all else fails... at least we'll have each other.
### Who's organising this?
Well, if you run a Go meetup, you are. It can't be a worldwide release party without meetups around the globe.
#### No, seriously, who's organising this?
Here are the organisers so far:
- [Natalie Pistunovich](mailto://natalie.pistunovich@gmail.com) - [@NataliePis](https://twitter.com/nataliepis)
- [Dave Cheney](mailto://dave@cheney.net) - [@davecheney](https://twitter.com/davecheney)
- [João Henrique Machado Silva](mailto://joaoh82@gmail.com) - [@joaoh82](https://twitter.com/joaoh82)
- [Florin Pățan](mailto://florinpatan@gmail.com) - [@dlsniper](https://twitter.com/dlsniper)
_Want to help? Edit this page and add yourself_
If you have questions, please reach out to one of the organisers.

170
Go-1.6-release-party.md

@ -1,170 +1,4 @@
### Party recap on tweets The Go wiki on GitHub has moved to go.dev (#61940).
Missed or missing the party? Here is a flashback for you: https://storify.com/gobridge/go-16v-world-release-party Try <https://go.dev/wiki/Go-1.6-release-party> or <https://go.dev/wiki/>.
----
### What's happening?
To celebrate the release of Go 1.6 we're organising a world wide release party on February the 17th, 2016.
#### Hang on, did you say Go 1.6 ships on the 17th of February?
Nope! Go 1.6 ships when it's ready. With that said, things are looking pretty good for a mid Feb release. Using the power of software estimation, a date was plucked from the aether that happened to coincide with several meetups that were already in the works.
### Sounds awesome, how can you get involved?
- If you host a Go user group or meetup, schedule a meetup on the 17th of Feb and celebrate with Gophers around the world.
- If you're a member of a Go user group or meetup, pester your organiser and let them know you'd like to participate.
After the event post a photo, make a video, write a blog post, scribble on your Facebook wall, or tweet something pithy. Let's see how big we can make the celebration.
Don't forget to add your details :point_down: right here.
#### Who's involved?
Here is a list of the groups who are participating.
- [Sydney Go users' group](http://www.meetup.com/golang-syd/events/228276309/)
- [Go-Miami](http://www.meetup.com/Go-Miami/events/228280324/)
- [San Diego Gophers](http://www.meetup.com/sdgophers/events/228129827/)
- [PDX Go](http://www.meetup.com/PDX-Go/events/228220792/)
- [GopherConIndia](http://www.gophercon.in/)
- [Belarus Golang User Group](https://events.dev.by/belarus-golang-user-group-meetup-2)
- [Ukrainian Golang User Groups](http://www.meetup.com/uagolang/events/228343484/)
- [Lviv Golang Group](http://www.meetup.com/Lviv-Golang-Group/events/228344940/)
- [Edmonton Go](https://edmontongo.org/) (Feb 22)
- [Software Craftsmanship Toulouse](http://www.meetup.com/fr-FR/Software-Craftsmanship-Toulouse/events/228285655/)
- [Golang Paris](http://www.meetup.com/fr-FR/Golang-Paris/events/228563347/)
- [Polish GLUG Meetup](http://www.meetup.com/GoLang-User-Group-Wroclaw/events/228369658/)
- [Google Developer Group Gigcity](http://www.meetup.com/GDG-Gigcity/events/228373161/)
- [Golang Montréal](https://golangmontreal.org) (Feb 22nd)
- [Golang Vietnam](https://www.facebook.com/events/1651152271814093/) (Feb 23)
- [Gophers Katowice](http://www.meetup.com/Gophers-Katowice/events/228375778/)
- [GoSF](http://www.meetup.com/golangsf/events/226090306/)
- [Boston Golang](http://www.meetup.com/Boston-Go-lang-User-Group/events/228398963/)
- [Go-Tampa](http://www.meetup.com/Go-Tampa/events/227365472/)
- [Atlanta](http://www.meetup.com/Go-Users-Group-Atlanta/events/228336134/)
- [GoAKL](http://www.meetup.com/Go-AKL/events/228436705/)
- [Golang Barcelona](http://www.meetup.com/es-ES/Golang-Barcelona/events/228438675/)
- [Golang Singapore](http://www.meetup.com/golangsg/events/228148961/) (February 18)
- [Go Maryland](http://www.meetup.com/Go-Maryland/events/228445301/) (February 18)
- [Orange County Gophers](http://www.meetup.com/Orange-County-Gophers/events/228458630/)
- [Central Jersey Tech Meetup](http://www.meetup.com/Central-Jersey-Tech-Meetup/events/228461491/)
- [Kansas City Golang Meetup](http://www.meetup.com/Kansas-City-Go-lang-Meetup/events/228467750/)
- [Mexico City Gophers](http://www.meetup.com/GophersMX/events/228478343/)
- [Women Who Go London](http://www.meetup.com/Women-Who-Go-London/events/228254901/)
- [Go Israel](http://www.meetup.com/Go-Israel/events/228520409/)
- [Go User Group Hamburg](http://www.meetup.com/Go-User-Group-Hamburg/events/228370048/)
- [Golang Brasil - São Paulo](http://www.meetup.com/golangbr/events/228525183/) (Saturday, February 20)
- [Zürich Gophers - Switzerland](http://www.meetup.com/Zurich-Gophers/events/228578365/)
- [Golang Reston](http://www.meetup.com/Golang-Reston/events/228252844/)
- [GoMAD](http://www.meetup.com/go-mad/events/228591957/)
- [GoCon](http://gocon.connpass.com/event/26572/)
- [GDG Golang Berlin](http://www.meetup.com/golang-users-berlin/events/228632499/) (Feb 17)
- [ATX Golang](http://www.meetup.com/atxgolang/events/226396146/) (Austin)
- [GoCon Tokyo](http://gocon.connpass.com/event/26572/)
- [Golang Italian Hackers, at Develer](https://www.eventbrite.it/e/biglietti-go-16-release-party-21450150979)
- [Go London User Group](http://www.meetup.com/Go-London-User-Group/events/228371135/)
- [Seattle Go Programmers](http://www.meetup.com/golang/events/228465356/)
- [Vilnius Golang](http://www.meetup.com/Vilnius-Golang/events/228751719/)
- [Go DC](http://www.meetup.com/Golang-DC/events/228378173/)
- [GDG Korea Golang](https://plus.google.com/u/0/events/cku5socs07a6o3oihqu3dfvhf70) (Feb 22)
- [Golang ZG, Zagreb Croatia] (http://www.meetup.com/Golang-ZG/events/228863217/)
- [Gophers-ir Iran/Tehran] (https://evand.ir/events/gophers-16) (February 18)
- [Golang Brazil - Porto Alegre](https://www.facebook.com/events/980566935370382/) (February 17)
- [Seattle Go Programmers] (http://www.meetup.com/golang/events/228465356/) (Wed February 17)
- [Go Cape Town] (http://www.meetup.com/gocapetown/events/228874257/)
- [Golang Hong Kong] (http://www.meetup.com/GolangHK/events/228551636/)
- [Golang Lima] (http://www.meetup.com/es-ES/Golang-Peru/events/228643682/)
- [Gophers Barranquilla] (http://www.meetup.com/es-ES/Gophers-Barranquilla/events/228899893/)
_If your group is not listed here yet, edit the page and add yourself._
_Organisers, once you've added your group, consider tweeting out a link to the page to raise awareness._
### Stay in touch
Trying to co-ordinate dozens of meetup groups around the globe will be challenging. Here are some ways you can plan your event, discuss it online, and keep up to date.
As always, if you get stuck, or need help, please [contact the organisers directly](https://github.com/golang/go/wiki/Go-1.6-release-party#no-seriously-whos-organising-this), we're here to help.
##### Slack Channel
We have a channel for the [release party](https://gophers.slack.com/messages/go-release-party/) on the [Gophers Slack](https://gophers.slack.com/messages/go-release-party/). If you need an invite to Slack, [you can request an automatic invite with this link](https://gophersinvite.herokuapp.com/).
##### Mailing list
We have set up a [google groups mailing list](https://groups.google.com/forum/#!forum/go-meetup-organisers) for meetup organisers to ask questions. At the moment the list is focused on the event on the 17th, hopefully if that goes well the mailing list will become a useful resource in the future.
### What happens in a release party?
Go 1.6 is the 7th release of the language which has been open source since November 10th, 2009 -- that's 6.5 years since the project was open sourced and nearly 4 years since the 1.0 release.
A lot has changed in the language since 1.0, so this is a great opportunity to discuss the improvements landing 1.6.
#### Resources
Francesc Campoy presented his _State of Go_ talk at FOSDEM, which includes details of the upcoming Go 1.6 release. [His slide are available online](https://talks.golang.org/2016/state-of-go.slide#1).
Here a Go 1.6 presentation slide deck from the Go Sydney users' group. Feel free to use this for your meetup.
[talks.godoc.org/github.com/davecheney/gosyd/go1.6.slide](http://talks.godoc.org/github.com/davecheney/gosyd/go1.6.slide)
_Source_: https://github.com/davecheney/gosyd/blob/master/go1.6.slide
_Please send PR's with corrections/additions_
#### Go 1.6 new and noteworthy
_Please help by expanding this section so meetup organisers can share these details with their groups._
- [Go 1.6 release notes (draft)](http://tip.golang.org/doc/go1.6)
- HTTP/2.
Go 1.6's `net/http` package supports [HTTP/2](https://http2.golang.org/) for both the client and server out of the box.
[Here is a video of @bradfitz giving an overview of Go 1.6's HTTP/2 support](https://www.youtube.com/watch?v=gukAZO1fqZQ).
- Garbage Collector improvements.
Go 1.6 focused heavily on improvements to the low latency collector shipped in Go 1.5.
Rick Hudson gave a [presentation at GopherCon 2015](https://www.youtube.com/watch?v=aiv1JOfMjm0) describing the low latency collector delivered in Go 1.5, and gave hints to the improvements being worked on for 1.6.
Rick recently [recorded an interview with InfoQ](http://www.infoq.com/interviews/hudson-go-gc) which focused on 1.6 in more detail.
- GOVENDOREXPERIMENT becomes the default.
Go 1.5 added experimental support for a mechanism of including the source of your package's dependencies in the package itself, colloquially known as _vendoring_. This feature was opt-in during Go 1.5.
Go 1.6 makes the vendor support the default, and it's likely that packages will start to use it soon.
- `text/template` changes.
A long requested ability to [trim whitespace in templates](http://tip.golang.org/pkg/text/template/#hdr-Text_and_spaces) has arrived. This template
`"{{23 -}} < {{- 45}}"`
will produce this output
`"23<45"`
- cgo changes
cgo continues to get stricter about sharing data between Go and C. http://tip.golang.org/cmd/cgo/#hdr-Passing_pointers
Ian Lance Taylor has put a lot of work into making signal handling more sane.
- More supported platforms.
Go 1.6 adds experimental ports to Linux on 64-bit MIPS (linux/mips64 and linux/mips64le). Note that this is 64 bit MIPS, not the older 32 bit MIPS commonly found in routers.
64-bit PowerPC (linux/ppc64le), Go 1.6 now supports cgo with external linking and is roughly feature complete.
Go 1.6 also adds an experimental port to Android on 32-bit x86 (android/386).
_Did you contribute to Go 1.6 and your contribution is not listed here? Edit this page and add some details about what you did._
### What'll happen if Go 1.6 comes out early?
It'll ruin the surprise, but only a little. Being realistic, even without the difficulty of timezones it's impossible to run every meetup at exactly the same time. As mentioned above, Feb 17 is an arbitrary date.
If you're a meetup organiser, Feb 17th would be great, but your participation is more important than being able to organise your group for exactly the 17th.
### What'll happen if Go 1.6 isn't out by the 17th?
Well ... at least we'll have each other.
The feature set of Go 1.6 isn't going to change in the next few weeks. If Go 1.6 ships after the 17th, it will be a little anticlimactic that we jumped the gun, but it's not a big deal.
### Who's organising this?
Well, if you run a Go meetup, you are. It can't be a worldwide release party without meetups around the globe.
#### No, seriously, who's organising this?
Here are the organisers so far:
- [Dave Cheney](mailto://dave@cheney.net) - @davecheney
- [Carlisia Campos](mailto://carlisia@golangbridge.org) - @carlisia
_Want to help? Edit this page and add yourself_
If you have questions, please reach out to one of the organisers.

147
Go-1.8-Release-Party.md

@ -1,147 +1,4 @@
### What's happening? The Go wiki on GitHub has moved to go.dev (#61940).
To celebrate the release of Go 1.8 we're to organising a world wide release party on February the 16th, 2017.
#### Hang on, did you say Go 1.8 ships on the 16th of February? Try <https://go.dev/wiki/Go-1.8-Release-Party> or <https://go.dev/wiki/>.
Nope! Go 1.8 is in good shape to ship in early February, but no firm release date has been published; it might be as early as the 1st of Feb, or it might not.
### Sounds awesome, how can you get involved?
- If you host a Go user group or meetup, schedule a meetup on the 16th of Feb, or as close to it as convenient, and celebrate with Gophers around the world.
- If you're a member of a Go user group or meetup, pester your organiser and let them know you'd like to participate.
After the event post a photo, make a video, write a blog post, scribble on your Facebook wall, or tweet something pithy. Let's see how big we can make the celebration.
Spread the word using hashtag [#GoReleaseParty](https://twitter.com/hashtag/goreleaseparty)
Don't forget to add your meetup's details :point_down: right here.
#### Who's involved?
Here is a list of the groups who are participating.
- Buenos Aires, Argentina: Feb 16 7:00 pm. Location: Mercado Libre's Headquarters. (https://www.meetup.com/es-ES/Golang-Argentina/)
- Orlando, FL: Feb 16 7:00PM, Location TBD, [Orlando Gophers](https://www.meetup.com/OrlandoGophers/)
- Mexico City, Mexico: Feb 16 7:00pm at Palo-IT, view the [meetup](https://www.meetup.com/GophersMX/events/237559318/) for details.
- Helsinki, Finland: Feb 16 5:30pm, [view the meetup](https://www.meetup.com/Helsinki-Gophers/events/237504573/)
- Tehran, Iran: Feb 16 5pm , at [Clickyab] (https://clickyab.com) office. Visit [event page](https://goo.gl/XgQ02E) for more info or contact [@fzerorubigd](https://twitter.com/fzerorubigd).
- Florence area, Italy: Feb 16 6pm CET, at Develer SRL. Visit [event page](https://www.eventbrite.it/e/biglietti-go-18-release-party-31564433069?utm-medium=discovery&utm-campaign=social&utm-content=attendeeshare&aff=escb&utm-source=cp&utm-term=listing) for more detail or contact [@golab_conf](https://twitter.com/golab_conf).
- Aachen, Germany: Feb 16 7pm, [view the meetup](https://www.meetup.com/Gophers-Aachen/events/237423932/)
- Bengaluru, India - Feb 16th 7.00pm at [Gojek] (https://twitter.com/GojekTech) office. Contact [@rbharshetty] (https://twitter.com/rBharshetty) or view the [meetup] (https://www.meetup.com/Golang-Bangalore/events/237156123/) for details
- Munich, Germany: Feb 15 7pm at Stylight. Contact [@lc0d3r](https://twitter.com/lc0d3r), [@munich_gophers](https://twitter.com/munich_gophers) or view the [meetup](https://www.meetup.com/Munich-Gophers-Go-User-Group/events/236962991/) for details.
- Washington DC: Feb 16 7pm at MakeOffices Dupont. View the [Golang meetup](https://www.meetup.com/Golang-DC/events/236696696/) and [GDG-DC] (https://www.meetup.com/gdg-dc) [Meetup] (https://www.meetup.com/gdg-dc/events/237677174/) for details.
- Columbia, MD: Feb 16 5:30pm at Tier 1 Consulting Group. See [event page](https://www.meetup.com/Go-Maryland/events/237121509/)
- Halifax, Nova Scotia, Canada **Postponed due to weather, will be rescheduled** Contact [@danp](https://twitter.com/danp128) for more info.
- Belo Horizonte, MG, Brazil: Feb 16 7pm at The Plant. Contact [@joaoh82](https://twitter.com/joaoh82) for more info or go to [Go Belo Horizonte](https://www.meetup.com/go-belo-horizonte/)
- Florianólis, SC, Brazil: Feb 16 7pm at Neoway Business Solutions. Contact [@ricardolonga](https://twitter.com/ricardolonga) for more info or go to [Floripa Gophers](https://www.meetup.com/Floripa-Gophers/events/236729070/)
- São Paulo, Brazil: Feb 16 7pm at TBD. Contact [@vdemario](https://twitter.com/vdemario) for more info or check the [meetup page](https://www.meetup.com/golangbr/)
- [@GolangParis](https://twitter.com/golangparis), France, Feb 16 7pm at [Deezer](www.deezer.com/features), see [meetup page](https://www.meetup.com/fr-FR/Golang-Paris/events/236696058). Ping: gaufres [at] golangparis.org.
- Sydney, Australia: Feb 16 6pm at TBD. Contact [@chewxy](https://twitter.com/chewxy) for more info. The [event page](https://www.meetup.com/golang-syd/events/236680493/)
- Moscow, Russia: Feb 16 7pm. [Meetup group](https://www.meetup.com/Golang-Moscow/events/237132934/).
- Novosibirsk, Russia: Feb 19 11am NOVT. Contact [@lkalneus](https://twitter.com/lkalneus) for more info. [Live stream](https://www.youtube.com/watch?v=r1KBpBpEinA)
- [@DenverGophers](https://twitter.com/DenverGophers) Feb 16 6:00pm at Comcast Viper. View the [meetup](http://bit.ly/denver-1-8-release-party) or contact [@apriendeau](https://twitter.com/apriendeau) for more info.
- [@MinneapolisGo](https://twitter.com/MinneapolisGo) Feb 16 6:00pm at Agosto. View the [meetup](https://www.meetup.com/Minneapolis-Ultimate-Golang/events/236698705/) or contact [@corylanou](https://twitter.com/corylanou) for more info.
- Amsterdam, the Netherlands: Feb 16 6pm at [Wercker](http://www.wercker.com). View the [meetup](https://www.meetup.com/golang-amsterdam/events/236723017/) for more details and RSVP.
- Wroclaw, Poland: Feb 16 7pm at Kuznicza 10. View the [meetup](https://www.meetup.com/GoLang-User-Group-Wroclaw/events/236727341/) or contact [@viru](https://github.com/viru/) for more details.
- Stockholm, Sweden: Feb 21 6pm at TV4. View the [meetup](https://www.meetup.com/Go-Stockholm/events/236748141/) or contact [@marcusolsson](https://twitter.com/marcusolsson/) for more details.
- New York, NY: Feb 16 at 6:30PM at Stack Overflow. RSVP for [meetup](https://www.meetup.com/golanguagenewyork/events/236871667/) Contact [@wikiwalk](https://twitter.com/wikiwalk) for more details.
- Madrid, Spain: Feb 16 at 7:30PM at source{d}, The event will be announced on [meetup](https://www.meetup.com/go-mad/). Contact [@mcuadros_](https://twitter.com/mcuadros_) for more details.
- Murcia, Spain: Feb 16 at 7:00PM at CEEIM. Will announce the event on [meetup](https://www.meetup.com/Gophers-Murcia/). Contact [@ANPez](https://twitter.com/ANPez) for more details.
- Taipei, Taiwan: Feb 16 at 7:30PM at [Dcard](https://www.dcard.tw). RSVP on the [kktix page](http://golang.kktix.cc/events/gtg21). Contact [@kkdai](https://twitter.com/Evan_Lin) for more details.
- Budapest, Hungary: Feb 16 at 7:00PM at [Prezi House of Ideas](https://www.google.com/maps?f=q&hl=en&q=1065+Hajós+street+35.,+Budapest,+hu). RSVP on the [meetup page](https://www.meetup.com/go-budapest/events/236811843/). For details please contact the organizer: [@gulyasm](https://twitter.com/gulyasm)
- Reston, VA: Feb 16 at 6:45PM at Comcast. See more details and RSVP on the [meetup page](https://www.meetup.com/Golang-Reston/events/236807731/).
- Lille, France: Feb 16 at 6:45PM at [Epitech Lille](https://goo.gl/maps/C6H7CjZWrFv). [Meetup page](https://www.meetup.com/GDG-Lille/events/236825262).
- Hamburg, Germany: Feb 16 at 7PM place at [loodse](https://loodse.com/en/). [Meetup page](https://www.meetup.com/Go-User-Group-Hamburg/events/236813440/).
- Okayama, Japan: Feb 16 7pm at Kurashiki Coffee Shop. See an [event page](https://connpass.com/event/48433/) or contact [@qt_luigi](https://twitter.com/qt_luigi) for more info.
- Phoenix, AZ: Feb 16 at 6:30PM, at [Brightcove](https://www.brightcove.com), Scottsdale. See [event page](https://www.meetup.com/Golang-Phoenix/events/236891853/) or contact [@golangPhoenix](https://twitter.com/golangPhoenix)
- Toronto, Canada: Firkin on King, See [event page](https://www.meetup.com/go-toronto/events/236855730/)
- Seattle, WA: Feb 16 at 6PM at Uber, See [event page](https://www.meetup.com/golang/events/236803478/)
- Vancouver, BC, Canada: Feb 16 at 6PM at [Hootsuite](http://hootsuite.com), See [event page](https://www.meetup.com/golangvan/events/236807698/)
- San Francisco, CA: Feb 16 at 6:30PM, venue TBD. See [event page](https://www.meetup.com/golangsf/events/236673793/)
- Copenhagen, Denmark: Feb 16th at 6PM, at Vivino. See [event page](https://www.meetup.com/Go-Cph/events/233646078/) or contact [@phr0e](https://twitter.com/phr0e) or [@CphGophers](https://twitter.com/CphGophers)
- Leeds, England, UK: Feb 16th at 6PM, at White Cloth Gallery in Leeds (LS1 4HT). See [event page](https://www.eventbrite.co.uk/e/go-18-release-party-tickets-31217190457)
- Zurich, CH, Feb 23rd at 6:30PM at Unic AG offices in Altstetten. See [event page](https://www.meetup.com/Zurich-Gophers/events/236745236/)
- Framingham, Ma - Feb 16th 7pm - See [event page](https://www.meetup.com/Framingham-Golang-Meetup/events/236999473/)
- Cambridge, Ma - Feb 16th 6:30pm, at the Google Office in Cambridge - See [event page](https://www.meetup.com/Boston-Go-lang-User-Group/events/237190202/), contact [@bostongolang](https://twitter.com/bostongolang)
- Tokyo, Japan - Feb 16th 7pm - See https://gocon.connpass.com/event/48281/
- San Diego, CA @ ScouRED - Feb 16th 6pm - See [event page](https://www.meetup.com/sdgophers/events/236202461/), contact [@carlisia](https://twitter.com/carlisia)
- Philadelphia, PA - Feb 16th 6PM, at Sidecar. See [Meetup page](https://www.meetup.com/GoLangPhilly/events/236965685/) or contact [@golangphilly](https://twitter.com/golangphilly)
- Milan, Italy - Feb 16th 6.30pm, at Ibuildings' offices. For info tweet to [@kmox83](https://twitter.com/kmox83) or [@mavimo](https://twitter.com/mavimo) - See the [event page](https://www.meetup.com/Golang-Milano/)
- Singapore - Feb 16th 7.30pm, at Singapore Power office. See the [Meetup page](https://www.meetup.com/golangsg/events/236725569/) or tweet to [@golangSG](https://twitter.com/golangSG)
- Cardiff (Wales UK) - Feb 15th 18:00 at Tramshed Cardiff. See the [Meetup page](https://www.meetup.com/Cardiff-Go-Meetup/events/237158460/) or tweet to [@cdfgolang](https://twitter.com/cdfgolang)
- Minsk, Belarus - Feb 16th 7.00pm at Juno. [Meetup Page ->] (https://www.meetup.com/JunoCrew-meetups/events/237671824/) [Registration here ->](https://goo.gl/forms/Fw07rIouWDyMiT5e2)
- Bangor (Wales UK) - Feb 16th 7:00 PM hosted by [NorthWalesTech](http://northwales.technology/). See the [Meetup page](https://www.meetup.com/NorthWalesTech/events/236961582/) or tweet to [@northwalestech](https://twitter.com/northwalestech)
- Odessa, Ukraine - Feb 25th 10:00am at VertaMedia. See the [meetup page](http://vmes.vertamedia.com/).
- Valencia, Spain - Feb 18th 17:00pm at Oh my Game Bar. Visit the [Telegram group](https://telegram.me/golangvalencia) or visit our [twitter](https://twitter.com/golangvalencia).
- Austin, TX (USA) - Feb 16th 6:30 PM (GMT-6) visit the [Austin Go Language User Group](https://www.meetup.com/atxgolang/events/237329768/) Meetup page for details
- Hyderabad, India - Feb 16th 6:30 PM visit the [Hyderabad Gophers](https://www.meetup.com/Hyderabad-Gophers/events/237360939/) Meetup page for details or contact [@itsbalamurali](https://twitter.com/itsbalamurali), [@gouthamve](https://twitter.com/putadent) for more details.
- Edmonton, AB (Canada) - Feb 27th 6:30 PM visit [Edmonton Go](https://edmontongo.org/) and RSVP via the [meetup page](https://www.meetup.com/startupedmonton/events/jptkwlywdbkc/).
- Dallas, TX - Feb 16th 7:00 PM visit [GoDFW](https://www.meetup.com/GolangDFW/) and RSVP via the [meetup page](https://www.meetup.com/GolangDFW/events/237369419/)
- Trójmiasto (Gdańsk-Sopot-Gdynia), Poland - Feb 13th 6:00 PM visit [GUGT](https://www.meetup.com/Golang-User-Group-Trojmiasto/) and RSVP via the [meetup page](https://www.meetup.com/Golang-User-Group-Trojmiasto/events/237271455/)
- Istanbul, Turkey - Feb 16th 7:00 PM at [Insider](http://useinsider.com/?utm_source=Github&utm_campaign=Go%201.8%20Release%20Party). RSVP via the [eventbrite page](https://www.eventbrite.com/e/insider-go-18-release-party-tickets-31826925190).
- Strasbourg, France - Feb 16th 6:30 PM at [La Plage Digitale](http://www.alsacedigitale.org/). RSVP via the [meetup page](https://goo.gl/R1A8Mg).
- Waterloo, Canada - Feb 16 7:00 PM at the Lion's Brewery at the [Heuther Hotel](http://www.huetherhotel.com/). RSVP via the [meetup page](https://www.meetup.com/Golang-KW/events/237554495/).
- Republic of Korea - Feb 16 8:00 Pm at GangNam 2nd TOZ. See the [meetup page]
(https://www.facebook.com/groups/golangko/).
- Dublin, Ireland - Feb 16 6:30 PM at Arista Networks. [Meetup](https://www.meetup.com/Dublin-Go-Meetup/events/237589126/) details.
- Berlin, Germany - Feb 28 7:00 PM at Amazon. RSVP at [Meetup](https://www.meetup.com/golang-users-berlin/events/237611330/).
- Portland, OR (pdxgo) - Feb 16 6:30 PM at Esri R&D Center. RSVP at [Meetup](https://www.meetup.com/PDX-Go/events/236702058/).
- Lyon, France - Fev 16 7 PM at OVH. RSVP at [Meetup](https://www.meetup.com/Golang-Lyon/events/237073142/)
- New York - Fev 16 7:00 PM at [Nulab](http://nulab-inc.com/). RSVP at [Meetup](https://www.meetup.com/Bowery-Go/events/237620656/)
- Dresden, Germany - Feb 16th 6:30PM at [LOVOO](https://www.lovoo.com). RVSP at http://doodle.com/poll/s2bw6eu4ywhqg9ut
- London, UK - Feb 15th 6:30PM at Skills Matter Code Node RSVP at [Meetup](https://www.meetup.com/Go-London-User-Group/events/236963108/)
- Auckland, NZ - Feb 15th 6:00PM at Vend, RSVP at [Meetup](https://www.meetup.com/Go-AKL/events/237547913/)
- 🇻🇳 Saigon, Vietnam - Feb 21 7:00 PM, RSVP at our [Facebook Event page](https://www.facebook.com/events/386900578337910/)
- Brno, CZ - Feb 28th 7:00PM. RSVP via the [meetup event page](https://www.meetup.com/Golang-Brno/events/237697083/).
- Atlanta, GA (USA) - Feb 16th at 6:30PM EST. RSVP at the [Meetup Page](https://www.meetup.com/Go-Users-Group-Atlanta/events/237150679/) or contact [@rlmcpherson](https://twitter.com/rlmcpherson)
- Edinburgh, Scotland - Feb 16th 6:30 PM GMT. RSVP at [Meetup](https://www.meetup.com/Edinburgh-Golang-meetup/events/237706628/) or contact [@macqueenism](https://twitter.com/macqueenism) or [@hackebrot](https://twitter.com/hackebrot).
- Boise, ID (USA) - Feb 16th 6:00PM (MST). RSVP via the [meetup event page](https://www.meetup.com/Boise-Go-lang-Meetup/events/237412184/).
- Cape Town, South Africa - Feb 16th 6:30PM (SAST). RSVP via the [meetup event page](https://www.meetup.com/gocapetown/events/237398240/) or get in touch with [@clvnb](https://twitter.com/clvnb)
- Lviv, Ukraine - Feb 24th 6:30PM (EET). RSVP via the [meetup event page](https://www.meetup.com/Lviv-Golang-Group/events/237729679/)
- Brest, France - Feb 21th 6:30PM. See the [Meetup page](https://www.meetup.com/fr-FR/FinistJUG/events/237468708/)
_If your group is not listed here yet, edit the page and add yourself._
_Organisers, once you've added your group, consider tweeting out a link to the page to raise awareness._
### Stay in touch
Trying to co-ordinate dozens of meetup groups around the globe will be challenging. Here are some ways you can plan your event, and keep up to date.
As always, if you get stuck, or need help, please [contact the organisers directly](https://github.com/golang/go/wiki/Go-1.8-release-party#no-seriously-whos-organising-this), we're here to help.
.
##### Slack Channel
We have a channel for the [release party](https://gophers.slack.com/messages/go-release-party/) on the [Gophers Slack](https://gophers.slack.com/messages/go-release-party/). If you need an invite to Slack, [you can request an automatic invite with this link](https://invite.slack.golangbridge.org/).
##### Mailing list
We have set up a [mailing list for meetup organisers](https://groups.google.com/forum/#!forum/go-meetup-organisers) to ask questions.
### What happens in a release party?
As with the previous [Go 1.6](https://github.com/golang/go/wiki/Go-1.6-release-party) and Go 1.7 release parties, this is a great opportunity to spread the word about the improvements landing 1.8, and the plans for the 1.9 development cycle.
#### Resources
A sample slide deck that you can use is [available here](https://talks.godoc.org/github.com/davecheney/go-1.8-release-party/presentation.slide#1) ([source](https://github.com/davecheney/go-1.8-release-party))
_Please send PR's with corrections/additions_
[Here's a link to the _draft_ Go 1.8 release notes](http://beta.golang.org/doc/go1.8).
[Here's a link](https://talks.golang.org/2017/state-of-go.slide/) to the talk by Francesc Campoy: The State of Go (February 2017).
### What'll happen if Go 1.8 comes out before the 16th?
This is likely to happen, but many meetups have a January date scheduled and don't want to hold two meetups so close together. The 16th is an arbitrary date that a quorum of meetups could find that didn't conflict with their existing schedules.
If you're a meetup organiser and can hit the Feb 16th, awesome, but your participation is more important than being able to organise your group for an exact date.
### What'll happen if Go 1.8 isn't out by the 16th?
Well ... at least we'll have each other.
The feature set of Go 1.8 isn't going to change in over the next month. If Go 1.8 ships after the 16th, it will be a little anticlimactic that we jumped the gun, but it's not a big deal.
### Who's organising this?
Well, if you run a Go meetup, you are. It can't be a worldwide release party without meetups around the globe.
#### No, seriously, who's organising this?
Here are the organisers so far:
- [Dave Cheney](mailto://dave@cheney.net) - @davecheney
- [João Henrique Machado Silva](mailto://joaoh82@gmail.com) - [@joaoh82](https://twitter.com/joaoh82)
_Want to help? Edit this page and add yourself_
If you have questions, please reach out to one of the organisers.

27
Go-Community-Slides.md

@ -1,27 +1,4 @@
Did you speak at a conference or meetup lately? Please share links to your slide decks here for better distribution to our global community. The Go wiki on GitHub has moved to go.dev (#61940).
Try <https://go.dev/wiki/Go-Community-Slides> or <https://go.dev/wiki/>.
# Peer To Peer Groups
## Kitchener-Waterloo, Canada
### Concurrent Optimization Methods Using Go
Brodie Roberts, June 12, 2018 [[repo](https://github.com/indexexchange/GoOptimizationMethods)]
Concurrency is a powerful tool for doing huge amounts of computation on today's multi-core computers. But that power is limited by the design of paralleling the problem and its implementation using threads and locks. We'll start with a sub-optimal concurrent Go program and walk through improving it - iterating on finding the program's bottleneck, improving it, and seeing the program get faster. We'll also cover general tips and tricks of concurrent optimization to apply to your own computationally intensive programs.
# Conferences
## [GopherCon 2018](http://gophercon.com/), Denver, Colorado
### The Importance of Beginners
Natalie Pistunovich, August 29
* [Session details](https://www.gophercon.com/agenda/session/16875)
* [Slides](https://github.com/Pisush/Public-Speaking/blob/master/Slides/gopherconUS.pdf)
### Rethinking Classical Concurrency Patterns
Bryan C. Mills, August 28
* [Slides with speaker notes](https://drive.google.com/file/d/1nPdvhB0PutEJzdCq5ms6UI58dp50fcAN/view?usp=sharing)

174
Go-Release-Cycle.md

@ -1,174 +1,4 @@
This wiki page is maintained by the Go team. Please The Go wiki on GitHub has moved to go.dev (#61940).
[send comments to golang-dev](https://groups.google.com/group/golang-dev) or
[file issues](https://go.dev/issue) instead of making changes directly.
Short link: https://go.dev/s/release. Try <https://go.dev/wiki/Go-Release-Cycle> or <https://go.dev/wiki/>.
## Overview
Go is released every six months. Each release cycle is broken down into a
development phase lasting about 4 months, followed by a 3-month period of
testing and polishing called the release freeze. If everything goes well, work
on the next release begins before the previous release has shipped, resulting in
an overlap of about a month.
After the initial release of a version, it is supported with minor releases that
fix severe bugs and security issues.
## Timeline
The current release cycle is aligned to start in mid-January and mid-July of
each year. The target milestones for a release cycle are as described below. We
try to hit the targets as closely as possible, while still delivering a quality
release.
To give the team time to prepare, and to address unexpected problems, we prefer
to do release work early or mid-week. That means that exact dates will vary year
to year, so milestones are specified as weeks in a particular month. Week 1 is
the week starting on the first Monday of the month. All dates are subject to
change based on the year's holiday timings.
![release](https://user-images.githubusercontent.com/24611692/228010841-fb299331-e7e3-4e64-85dc-66261ce22ea3.svg)
#### January / July week 1: Planning for release begins.
Planning of major work for upcoming release cycle is announced on
[golang-dev](https://groups.google.com/group/golang-dev).
Example: [Go 1.20](https://groups.google.com/g/golang-dev/c/V8ez4YunkeE)
#### January / July week 3: Release work begins.
Once the prior release has entered its final stabilization period, the tree
opens for general development. All kinds of development are welcome during this
period. It's preferable for large or particularly risky changes to land well
before the end of the development window, so that there's time to fix any
problems that arise with them.
#### May / November week 4: Release freeze begins.
This milestone begins the second part of the release cycle, the release freeze.
The release freeze applies to the entire main repository as well as to the code
in subrepositories that is needed to build the binaries included in the release,
particularly vet and all its dependencies in the tools subrepository.
During the freeze, only bug fixes and doc updates are accepted. On occasion new
work may be done during the freeze, but only in exceptional circumstances and
typically only if the work was proposed and approved before the cutoff. Such
changes must be low risk. See [freeze exceptions](#freeze-exceptions) below.
This part of the release cycle is focused on improving the quality of the
release, by testing it and fixing bugs that are found. However, every fix must
be evaluated to balance the benefit of a possible fix against the cost of now
having not as well tested code (the fix) in the release. Early in the release
cycle, the balance tends toward accepting a fix. Late in the release cycle, the
balance tends toward rejecting a fix, unless a case can be made that the fix is
both low risk and high reward.
Examples of low risk changes appropriate late in the cycle include changes to
documentation and fixes to new features being introduced in the current release
(since there is no chance of introducing a regression compared to an earlier
release).
Shortly after the freeze begins, nearly all known bugs should have been fixed or
explicitly postponed (either to the next release or indefinitely). The remainder
should usually be tracked as release blockers and worked on urgently.
#### June / December week 2: Release candidate 1 issued.
A release candidate is meant to be as close as possible to the actual release
bits. Issuing a release candidate is an indication that the Go team has high
confidence that the tree is free of critical bugs. In particular, because Google
continuously tracks the development version of Go, by the time a release
candidate is issued, a close approximation of it will have been running in
production at Google for at least a week or two.
Once a release candidate is issued, only documentation changes and changes to
address critical bugs should be made. In general the bar for bug fixes at this
point is even slightly higher than the bar for bug fixes in a minor release. We
may prefer to issue a release with a known but very rare crash than to issue a
release with a new but not production-tested fix.
If critical bugs are reported and fixed, additional release candidates may be
issued, but typically not more than one every two weeks.
Again, a release candidate is meant to be bug-free, as much as possible.
Organizations are encouraged to deploy it in production settings after
appropriate organization-specific testing.
The calm period between a release candidate and the final release is a good time
for additional testing or for discussing the next release (see the planning
milestone above).
#### July / January week 3: Work on the next release begins
While the current release is being stabilized, the tree reopens for work on the
next. During this period, fixes intended for the current release need to be
[cherry-picked onto the release branch](https://go.dev/wiki/MinorReleases#making-cherry-pick-cls).
Unlike cherry-picks for minor releases, these changes don't need a backport
issue and don't need to be approved by the release team. As long as they're
permitted by the [freeze policy](#may--november-week-4-release-freeze-begins),
they can be reviewed and submitted like any other CL.
#### August / February week 2: Release issued.
Finally, the release itself!
A release should not contain significant changes since the last release
candidate: it is important that all code in the release has been well tested.
Issuing a release is an indication that release testing has confirmed the
release candidate's high confidence that the tree is free of critical bugs.
Even if a release goes smoothly and there's spare time, we prefer to stay on
schedule. Extra testing can only improve the stability of a release, and it also
gives developers working on the Go release more time to think about and plan the
next release before code changes start pouring in again.
By the time of the final release, Google will have been using this version of Go
for nearly two months. While Google's successful use does not guarantee the
absence of problems, our experience has been that it certainly helps improve the
quality of the release. We strongly encourage other organizations to test
release candidates as aggressively as they are able and to report problems that
they find.
Once a release is stabilized, work on the next release, including code reviews
and submission of new code, can begin, and the cycle repeats. Note that if a
release is delayed, work on the next release may be delayed as well.
## Release Maintenance
A minor release is issued to address one or more critical problems for which
there is no workaround (typically related to stability or security). The only
code changes included in the release are the fixes for the specific critical
problems. Important documentation-only changes and safe test updates (such as
disabling tests), may also be included as well, but nothing more. Minor releases
preserve backwards compatibility as much as possible, and don't introduce new
APIs.
Minor releases to address problems (including security issues) for Go 1.x stop
once Go 1.x+2 is released. For more about security updates, see the
[security policy](https://go.dev/security).
See also the [MinorReleases](https://go.dev/wiki/MinorReleases) wiki page.
## Freeze Exceptions
Fix CLs that are
[permitted by the freeze policy](#may--november-week-4-release-freeze-begins) do
not need a freeze exception.
Any exceptions to the freeze must be communicated to and explicitly approved by
the Go Release Team before the freeze. If you’d like to request an exception,
please file an issue in the issue tracker with "[freeze exception]" as a suffix
and include "CC @golang/release" ([example](https://go.dev/issue/42747)). We
will address any requests on a case-by-case basis with a strong preference for
not permitting changes after the freeze.
## Historical note
A version of this schedule, with a shorter development window, was originally
adopted for the Go 1.7 release in 2016. After years of difficult releases,
testing and process improvements in 2022 and 2023 led to a timely 1.19 release.
For 1.20, the development window was expanded with a late freeze and early thaw.
These changes were formalized for the 1.21 release. We anticipate continuing to
ship on time.

49
Go2.md

@ -1,49 +1,4 @@
# Go2 status The Go wiki on GitHub has moved to go.dev (#61940).
This page tracks the status of "Go 2". Try <https://go.dev/wiki/Go2> or <https://go.dev/wiki/>.
We are currently seeking feedback on potential designs for improved error handling, error values, and generics:
* [Announcement of Go2 Draft Designs](https://go.dev/blog/go2draft)
* [Go2 Error Handling, Generics, and Error Values](https://go.googlesource.com/proposal/+/master/design/go2draft.md)
## Bugs
* [Open Go2 bugs](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3AGo2)
## Talks
* [GopherCon 2017: Russ Cox - The Future of Go](https://www.youtube.com/watch?v=0Zbh_vmAKvk)
* [GopherCon Russia 2018: Brad Fitzpatrick - Go: Looking back and looking forward](https://www.youtube.com/watch?v=ZCB-g2B4Y5A) (Go2 stuff is at about 20 minutes in)
* [Sydney Golang Meetup - Rob Pike - Go 2 Draft Specifications](https://www.youtube.com/watch?v=RIvL2ONhFBI)
## Scope
From talk above:
* "maybe three major changes"
* plus minor housekeep tasks
* TBD
Examples of major changes:
* [versioning](https://github.com/golang/go/issues/24301)
* [generics](https://github.com/golang/go/issues/15292)?
* [simplified, improved error handling](https://github.com/golang/go/issues/21161)?
* ...
Examples of housekeeping:
* [Open Go2Cleanup bugs](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3AGo2Cleanup) (please don't add this label to things without discussion)
## Compatibility
We do not want to break the ecosystem. Go 1 and Go 2 code must be able to interoperate in programs with ease.
## Standard library
The standard library would probably be versioned and permit out-of-cycle updates, but be included with Go releases. Maybe "encoding/foo" become shorthand for "golang.org/x/std/encoding/foo". TBD. Some package would probably get v2 major versions, but the v1 versions would be minimally maintained, at least for security.
## Roadmap
TBD

277
Go2ErrorHandlingFeedback.md

@ -1,277 +1,4 @@
# Feedback re Go 2 Error Handling Draft Design The Go wiki on GitHub has moved to go.dev (#61940).
This page is meant to collect and organize feedback and discussion Try <https://go.dev/wiki/Go2ErrorHandlingFeedback> or <https://go.dev/wiki/>.
started with the Go 2 [error handling draft design](https://go.googlesource.com/proposal/+/master/design/go2draft-error-handling-overview.md).
Please post feedback on your blog, Medium, GitHub Gists, mailing lists, Google Docs, etc. And then please link it here.
Please help categorize the rest of the uncategorized proposals at the bottom.
**Update, June 19, 2019** – Based on this feedback we have posted a [proposal for a try builtin](https://go.dev/design/32437-try-builtin), which produced significant feedback on #32437 ([threaded view here](https://swtch.com/try.html)).
We've disabled comments on that issue until July 1 to give people time to experiment in their own code. We would very much like to see experience reports about using the general try approach in your own code, including trial conversions with [tryhard](https://github.com/griesemer/tryhard). Thanks!
# Experience with the [“try proposal”](https://go.dev/design/32437-try-builtin)
Add to this list:
- TEMPLATE: Your Name, “[Title](URL)”, Month YYYY
* * *
# Requirements
Discussions of the requirements for a new error handling method.
- Warren Stephens, "[Go 2 `handle` should provide line number, source filename, version](https://github.com/warrenstephens/Go2ErrorHandlingFeedback)", December 2018
- Liam Breck, “[Requirements to Consider for Go 2 Error Handling](https://gist.github.com/networkimprov/961c9caa2631ad3b95413f7d44a2c98a)”, September 2018
- jimmyfrasche, "[Don't special case error or nil](https://gist.github.com/jimmyfrasche/f2cd6aff16db5e46c577da44ec0cfa72)", September 2018
- Matt Dee "[Error Handling Should Support Custom Error Types](https://gist.github.com/mattdee123/a04f95ef5639489668cafd9c3b675a8c)", August 2018
- Ian Lance Taylor, “[Incomplete list of criteria](https://github.com/golang/go/issues/21161#issuecomment-389380686)” from GitHub proposal discussion, May 2018
- Rob Pike (posted by @matjam) “[Simplicity is Complicated](https://www.youtube.com/watch?v=rFejpH_tAHM)”, December 2015
# In support
This includes supporting the existing chaining/stacking of handlers without changes.
- Tokyo Gophers, "[In support comments from Go 2 feedback event](https://docs.google.com/document/d/1yTDMP0E9hlJyLnKyr-6XL84RogiiwDnk0fMg9HDOKkc/edit#heading=h.f7ryl4573bu9)", October 2018
- Adam Bouhenguel "[In support of more declarative error handling](https://gist.github.com/ajbouh/716f8daba40199fe4d4d702704f3dfcc)", August 2018
- Daniel Theophanes, "[Go 2 Design: Error Handling Net Win](https://docs.google.com/document/d/e/2PACX-1vSq487dLylRHjgtKV42EbTKHW1aHZaaso3MZ4HOG1OS-s8suOnR9WZz6ahzH4Kufs2vwKKDMhoj1_I6/pub)", August 2018
- Alexandru-Paul Copil, "[In Support, with slight modifications and considerations](https://gist.github.com/cpl/54ed073e20f03fb6f95257037d311420)", September 2021
## Example code
Code changed to use the existing proposal.
- Daniel Milde, "[Use check-handle draft syntax in gdu](https://github.com/dundee/gdu/pull/51)", May 2021
- Mateusz Czapliński, "[Converting a fragment of real code with error handling to Go 2 'design draft'](https://gist.github.com/akavel/62d90bdc43088574c638eb3b16301a92)", August 2018
- Blake Mizerany, “[How best to account for partial writes when using check/handle?](https://gist.github.com/bmizerany/fcd0348bda96edce05a4fc7426e47751)”, August 2018
# Against
Critiques without counter-proposals
- Pasha Osipyants, “[Error handling mechanism using current go possibilities](https://pkg.go.dev/github.com/pashaosipyants/errors)”, February 2019
- Anonymous, “[Go 2 Error Handling Non-Proposal](https://groups.google.com/d/topic/golang-nuts/1McP4_-oOpo/discussion)”, October 2018
- Stripe developers, “[Feedback on Go 2 draft designs](https://groups.google.com/d/msg/golang-nuts/3A_MpcNKg7k/DWiHBLArCAAJ)”, October 2018
- Tokyo Gophers, "[Against comments from Go 2 feedback event](https://docs.google.com/document/d/1yTDMP0E9hlJyLnKyr-6XL84RogiiwDnk0fMg9HDOKkc/edit#heading=h.fy8rnze9tll5)", Oct 2018
- Liam Breck, “[Golang, How dare you handle my checks!](https://medium.com/@mnmnotmail/golang-how-dare-you-handle-my-checks-d5485f991289)”, September 2018
- Nate Finch, "[Handle and Check, Let's Not](https://npf.io/2018/09/check-and-handle/)", September 2018
- Jozef Slezak, "[Use semicolons instead of new keywords: check+handle](https://gist.github.com/jozef-slezak/93a7d9d3d18d3fce3f8c3990c031f8d0)", September 2018
- Shannon Wynter "[Error Handling as it can already be done](https://gist.github.com/freman/0b372e46c72f6a27652538b9930ee851)", August 2018
# Recurring themes
Concepts that appear repeatedly among the suggestions below.
- Invoke handler via assignment, e.g. `v, ? := f()`
references:
[1](https://gist.github.com/oktalz/f04f36a3c2f61af22c7a6e06095d18eb),
[2](https://gist.github.com/pborman/c69e79690d86dfc5c371f096be22930c),
[3](http://blog.oldcloudguy.com/2019/04/18/error-handling-in-go-2-draft/),
[4](https://github.com/rockmenjack/go-2-proposals/blob/master/error_handling.md),
[5](https://gist.github.com/the-gigi/3c1acfc521d7991309eec140f40ccc2b),
[6](https://gist.github.com/8lall0/cb43e1fa4aae42bc709b138bda02284e),
[7](https://gist.github.com/dpremus/3b141157e7e47418ca6ccb1fc0210fc7),
[8](https://gist.github.com/bserdar/4c728f85ca30de25a433e84ad5a065a1),
[9](https://gist.github.com/mcluseau/1c20c3973fa3acb544d0505637be8d67),
[10](https://didenko.github.io/grab/grab_worth_it_0.1.1.html),
[11](https://github.com/gooid/gonotes/blob/master/inline_style_error_handle.md),
[12](https://gist.github.com/Kiura/4826db047e22b7720d378ac9ac642027),
[13](https://github.com/golang/go/issues/27519),
[14](https://gist.github.com/lldld/bf93ca94c24f172e95baf8c123427ace)
- Invoke one of several handlers by name, e.g. `v := check f() ? name`
references:
[1](https://didenko.github.io/grab/grab_worth_it_0.1.1.html),
[2](https://gist.github.com/forstmeier/b6c6a6d2f6f2f72a81a076322959c959),
[3](https://gist.github.com/mcluseau/1c20c3973fa3acb544d0505637be8d67),
[4](https://gist.github.com/the-gigi/3c1acfc521d7991309eec140f40ccc2b),
[5](https://gist.github.com/PeterRK/4f59579c1162cdbc28086f6b5f7b4fa2),
[6](https://gist.github.com/marlonche/4e5d4e5aec0555958ec1f181991325f6),
[7](https://github.com/alnkapa/Go2ErrorHandlingFeedback/blob/master/README.md),
[8](https://medium.com/@phlatphrog/handling-more-than-just-errors-in-go-f97c5aa2eac4),
[9](https://gist.github.com/gregwebs/02479eeef8082cd199d9e6461cd1dab3),
[10](https://github.com/gooid/gonotes/blob/master/inline_style_error_handle.md),
[11](https://gist.github.com/spakin/86ea86ca48aefc78b672636914f4fc23),
[12](https://gist.github.com/morikuni/bbe4b2b0384507b42e6a79d4eca5fc61),
[13](http://devmethodologies.blogspot.com/2018/10/go-error-handling-using-closures.html),
[14](https://gist.github.com/bserdar/4c728f85ca30de25a433e84ad5a065a1),
[15](https://medium.com/@marode/the-return-of-the-return-278b8ae261ab),
[16](https://gist.github.com/dpremus/3b141157e7e47418ca6ccb1fc0210fc7),
[17](https://github.com/golang/go/issues/27519)
# Modest revisions
- Leidong Liu, "[a, b, !checkError := Sub(...)](https://gist.github.com/lldld/bf93ca94c24f172e95baf8c123427ace)", Nov 2019
- Jin Feng, "[A simplified Go 2 error handling solution with no handler], (https://gist.github.com/jfeng45/416d4ecb42a4df50bebf86ce1c41c668)", July 2019
- Dave Arnold, "[Move special check keyword to left-hand side of assignment](http://blog.oldcloudguy.com/2019/04/18/error-handling-in-go-2-draft/)", April 2019
- Rockmen, "[Add handle and ? as syntax sugar maybe](https://github.com/rockmenjack/go-2-proposals/blob/master/error_handling.md)", December 2018
- Steve Manuel, "[Go 2 `handle` statement to optionally use a type switch](https://github.com/golang/go/issues/28344)", October 2018
- Zlatko Bratkovic, "[In support with tiny change](https://gist.github.com/oktalz/f04f36a3c2f61af22c7a6e06095d18eb)", October 2018
- DeedleFake, "[Possible Solution to `check` Awkwardness with Chained Method Calls](https://gist.github.com/DeedleFake/5e8e9e39203dff4839793981f79123aa)", September 2018
- Yesuu Zhang, "[Pass the check and handle parameters, custom handle](https://github.com/yesuu/go-proposal/blob/master/go2errorhanding.md)", September 2018
- Viktor Kojouharov, "[Reducing the special casing around the new error design draft](https://gist.github.com/urandom/6519990ef9eb7547e888a5f2da7f1a93)", September 2018
- Aleksei Pavliukov, “[Use a function as a handle parameter](https://github.com/a5i/go-proposal/blob/master/use%20a%20function%20as%20a%20handle%20parameter.md)”, September 2018
- Savino Pio Liguori, "[Feedback for Go2 error handling design](https://gist.github.com/8lall0/cb43e1fa4aae42bc709b138bda02284e)", August 2018
- Jeffrey Koehler, "[In support of Handle Chaining; On Check](https://gist.github.com/deef0000dragon1/eb224ce4918d4ec3bdbaedf83a32aeb1)", August 2018
- Garrus, "[Another style of syntactic sugar on error handling](https://gist.github.com/garrus/5b1f73a7640726c92273700eabed9056)", August 2018
- Paul Borman, "[Arguments against the Go 2 error handling proposal](https://gist.github.com/pborman/c69e79690d86dfc5c371f096be22930c)", August 2018
- krhubert, "[Error default handler for tests](https://go.dev/issue/32361)", May 2019
- Franz, Implement error handling like an invariant check of a variable. when the value changes, a function is called. this can then be used in other situations too.
- Brandon Heenan, "[Concise, with more obvious control flow](https://github.com/bmheenan/goerr/blob/main/README.md)", May 2021
## Remove handler chaining
- Markus Heukelom, "[proposal: Improve error handing using `guard` and `must` keywords](https://github.com/golang/go/issues/31442)", April 2019
- Alessandro Arzilli, “[Against check as an operator and handler chains](https://gist.github.com/aarzilli/1a85db632edecc8159505e2c785882ed)”, August 2018
- Simon Howard, “[Go 2 errors response: One Handler Per Function](https://gist.github.com/fragglet/df6c5471771d87b2ad597d2efc57cb3e)”, August 2018
- Eli Bendersky, "[Thoughts on the Go 2 Error Handling proposal](https://gist.github.com/eliben/d0c872054864bfc1110ec761c3c53c47)", September 2018
- Yoshiki Shibukawa, "[Every handles should have return statement](https://gist.github.com/shibukawa/42a9dee400c2f8577b4a763bcb1a5e5f)", September 2018
# Counter-proposals
## Error handling with normal functions
- Azamat Kalberdiev, “[Handling every error with intuitive code](https://gist.github.com/Azamat28/5b2c6f66fc4927a002a2d60044aa9231)”, March 2021
- Andrew Phillips, “[Use closures rather than handlers](http://devmethodologies.blogspot.com/2018/10/go-error-handling-using-closures.html)”, October 2018
- Taihei Morikuni, "[Use functions as an error handler, Add syntactic sugar to remove duplicated if statement](https://gist.github.com/morikuni/bbe4b2b0384507b42e6a79d4eca5fc61)", September 2018
- Scott Pakin, "[Go 2 error handling based on non-local returns](https://gist.github.com/spakin/86ea86ca48aefc78b672636914f4fc23)", September 2018
- Greg Weber "[Error handling with functions and an error return?](https://github.com/golang/go/issues/27567)", September 2018. Originally linked [gist](https://gist.github.com/gregwebs/02479eeef8082cd199d9e6461cd1dab3).
- Gigi Sayfan, “[Go 2 error handling feedback + alternative solution](https://gist.github.com/the-gigi/3c1acfc521d7991309eec140f40ccc2b)", September 2018
- Ruan Kunliang, "[Simple Error Handling for Go 2](https://gist.github.com/PeterRK/4f59579c1162cdbc28086f6b5f7b4fa2)", August 2018
- Martin Rode, "[The return of the return, Error Handling for Go 2](https://medium.com/@marode/the-return-of-the-return-278b8ae261ab)", November 2018
## Labeled error handlers
- Joe Lapp, "[Local-only throw-catch error handling](https://github.com/golang/go/issues/48896)", October 2021
- Danijel Premus, "[Use existing go labels](https://gist.github.com/dpremus/3b141157e7e47418ca6ccb1fc0210fc7)", December 2018
- Burak Serdar, "[Handler for err declares both err and errHandler, less intrusive labeled error handling](https://gist.github.com/bserdar/4c728f85ca30de25a433e84ad5a065a1)", October 2018
- John Forstmeier, "[Labeled error handling](https://gist.github.com/forstmeier/b6c6a6d2f6f2f72a81a076322959c959)", September 2018
- Mikaël Cluseau, "[Multiple handlers, unambiguous on which return value is used](https://gist.github.com/mcluseau/1c20c3973fa3acb544d0505637be8d67)", September 2018
- Kiura Magomadov, “[Addition to Go2 draft error handling](https://gist.github.com/Kiura/4826db047e22b7720d378ac9ac642027)", September 2018
- Liam Breck, “[The `#id/catch` Error Model](https://github.com/golang/go/issues/27519)”, September 2018
- Marlon Che, "[How about separating check and handle?](https://gist.github.com/marlonche/4e5d4e5aec0555958ec1f181991325f6)", August 2018
## Inlining
- Patrick Kelly, "[handling more than just errors in go](https://medium.com/@phlatphrog/handling-more-than-just-errors-in-go-f97c5aa2eac4)", August 2018
- Vlad Didenko, “[Error Handling with `grab | name()`](https://didenko.github.io/grab/grab_worth_it_0.1.1.html)”, November 2017
- Gooid, “[Inline style error handle(simple unambiguous)](https://github.com/gooid/gonotes/blob/master/inline_style_error_handle.md)”, August 2018
## Use defer
- Victoria Raymond, “[Force 'check' to return error instead of allowing customized logic](https://gist.github.com/VictoriaRaymond/d70663a6ec6cdc59816b8806dccf7826)”, August 2018
- Night-walker and daokoder, "[Extend and repurpose defer instead of introducing new syntax](https://github.com/daokoder/dao/issues/191#issuecomment-44784919 )", June 2014
## try/catch/finally syntax
- Mathieu Devos, "[Go2 Error Handling Proposal: Scoped Check/Handle](https://gist.github.com/mathieudevos/2bdae70596aca711e50d1f2ff6d7b7cb)", August 2018
- Rust RFC, “[Trait-Based Exception Handling (wherein `catch` is akin to `try`)](https://github.com/rust-lang/rfcs/blob/master/text/0243-trait-based-exception-handling.md)”, February 2016
- ZhiFeng Hu, "[[Go2ErrorHandling] Go should support Exception handler](https://www.netroby.com/view/3910)", August 2018
- Jan Semmelink, “[if-else-undo-done](https://gist.github.com/jansemmelink/235228a0fb56d0eeba8085ab5f8178f3)”, August 2018
- Vladimir Utoplov, "[Handling throws/throw idiom](https://gist.github.com/trashgenerator/d58e05522d2f83709e1a601564b68fee)", September 2018
- Gokan EKINCI, "[try-with-resources](https://gist.github.com/eau-de-la-seine/9e2e74d6369aef4a76aa50976e34de6d)", December 2018
## Other possibilities
- Alex Hornbake, "[refuse. conditional return keyword](https://gist.github.com/alexhornbake/6a4c1c6a0f2a063da6dda1bf6ec0f5f3)", June 2019
- yaxinlx, "[Use ? as suffix to remove the last error value from multi-value tuples](https://gist.github.com/yaxinlx/1e013fec0e3c2469f97074dbf5d2e2c0)", March 2019
- Plamen Stoev, "[Go 2 block-level checks](https://gist.github.com/coquebg/afe44e410f883a313dc849da3e1ff34c)", November 2018
- Peter Goetz, "[Formalize and Enforce Error Handling](https://medium.com/@peter.gtz/thinking-about-new-ways-of-error-handling-in-go-2-e56d116952f1)", September 2017
- Fedir RYKHTIK, "[Go 2 error handling with exclamation mark](https://gist.github.com/fedir/50158bc351b43378b829948290102470)", September 2018
- Einthusan Vigneswaran, “[Error Aware Keywords - return, defer, if, != and forcing the error object to be the last argument](https://gist.github.com/einthusan/24e18f6359a31b3537815284cde0f6de)”, September 2018
- Andrew Phillips, “[Improving Go Error Handling](http://devmethodologies.blogspot.com/2017/10/improving-go-error-handling.html)”, October 2017
# Uncategorized
Please help categorize the rest of the proposals here.
- Joe Lapp, "[`on...return` for error handling](https://github.com/golang/go/issues/48855)", Oct 2021
- Andrew Gwozdziewycz, "[Check for Go Errors](http://sigusr2.net/check-for-go-errors.html)", June 2019
- DeedleFake, "[Feedback for Go 2 Design Drafts](https://deedlefake.com/2018/08/feedback-for-go-2-design-drafts/)", August 2018
- Loki Verloren, “[Go 2 error handling feedback and my thoughts on how to improve programmer's efficiency and experience](https://gist.github.com/l0k1verloren/8aec03b8c48fdb5d3dab3a77153ce162)”, September 2018
- Gima, "[Procedural code, separate error handling](https://gitlab.com/snippets/1726097)", June 2018
- Konstantin, "[error handling for error-tree](https://github.com/Konstantin8105/Go2ErrorTree)", [Discyssion](https://github.com/golang/go/issues/32099) May 2019
## Adding your feedback
Please format all entries as below.
- _Your Name_, “[_Title_](#URL)”, _month year_
To make it easier to see new feedback, please add your new proposal to the top of the section it is placed in.

58
Go2ErrorValuesFeedback.md

@ -1,58 +1,4 @@
# Go 2 Error Values Feedback The Go wiki on GitHub has moved to go.dev (#61940).
This page is meant to collect and organize feedback about the Go 2 [error values draft designs](https://go.googlesource.com/proposal/+/master/design/go2draft-error-values-overview.md). Try <https://go.dev/wiki/Go2ErrorValuesFeedback> or <https://go.dev/wiki/>.
Please post feedback on your blog, Medium, GitHub Gists, mailing lists, Google Docs, etc. And then please link it here.
As the amount of feedback grows, please feel free to organize this page by specific kind of feedback.
### Further Background
- Ben Johnson, "[Failure is Your Domain](https://middlemost.com/failure-is-your-domain/)", June 2018
### Draft Implementation
- Go Team, “[x/exp/errors](https://pkg.go.dev/golang.org/x/exp/errors)”, November 2018
- Torben Schinke, “[Implementation of the draft design](https://github.com/worldiety/errors)”, December 2018
### Error Inspection
- Ilya Sinelnikov, "[`Is` and `As` differ in behavior which is unexpected](https://github.com/sidh/go2errorsinspection)", December 2018
- Roger Peppe, "[Some thoughts about the draft Go error inspection design](https://gist.github.com/rogpeppe/a435b57473152e3429a5a149401edacf)", November 2018
- Greg Weber, “[Horizontal composition: Error inspection for groups](https://gist.github.com/gregwebs/5a14a83970d607411310a3e0281d55be)”, September 2018
- Eyal Posener, "[Reply](https://gist.github.com/gregwebs/5a14a83970d607411310a3e0281d55be#gistcomment-2710662)", September 2018
- K. Alex mills, "[Rename Wrapper to Unwrapper](https://gist.github.com/kalexmills/46c2cb276c69b659005d8705180b268a)", September 2018
- jimmy frasche, "[Why limit this inspection to errors?](https://gist.github.com/jimmyfrasche/04ca2146c9130dab4d993365313722fb)", August 2018
- Dan Kortschak, [Carrying contract expectations and values causing errors in ev3go](https://github.com/ev3go/ev3dev/blob/master/errors.go), August 2018
- Daniel Theophanes, "[Go 2 Design: Error Inspection with Error Lists](https://docs.google.com/document/d/e/2PACX-1vT-CPcBV53awF7vq5bJEi1Y_DkuVmWW0RWl-gsujByB1mjX67rH58-mex1on1waR4Q_gyhPu5TdghMv/pub), August 2018
- Cosmos Nicolaou "[Inspection of errors in a different address space](https://github.com/cosnicolaou/core/wiki/go-2.0-error-handling-feedback)", September 2018
- Chris Siebenmann, "[Error inspection improves current annoyances but may not go far enough](https://utcc.utoronto.ca/~cks/space/blog/programming/Go2ErrorInspectionViews)", September 2018
- Paul Meyer, “[errors.New?]( - _Your Name_, “[_Title_](#URL)”, August 2018
- Vojtech Vitek "[adopt Cause and Wrap from github.com/pkg/errors](https://go.dev/issue/25675)", May 2018
- Andrew Wilkins "[Programmatic Frame inspection](https://gist.github.com/axw/247b6f69d2da016bb21a5eb1be44e611)", January 2019
- _Carl Johnson_, "[_`As()` and `Is()` are useful for optional interfaces beyond error_](https://gist.github.com/carlmjohnson/d06cd8d10e0aef65f565a55cc57cd986), Feb. 2019
- ques0942, "[xerrors has less feature about trace's detail](https://dev.to/ques0942/xerrors-has-less-feature-about-traces-detail-4861)", Mar. 2019
- _Your Name_, “[_Title_](#URL)”, _month year_
- etc.
### Error Printing
- Calle Pettersson, [Multi-line errors and log collection tools](https://gist.github.com/carlpett/bc1714060235edc0ad3fd9ead82f4ce6)”, August 2018
- jimmy frasche, "[Why limit these interfaces to errors?](https://gist.github.com/jimmyfrasche/e02fcbefee5cb14228768afec17abbee)" , August 2018
- Chris Hines, “[Types cannot implement both the errors.Formatter and fmt.Formatter interfaces
](https://gist.github.com/ChrisHines/a732a9b1ef3acb6acfee2ccc174e31ed)”, _August 2018_
- Dean Bassett, “[Make errors.Detailer, not errors.Formatter](https://gist.github.com/deanveloper/61544f16a7d4c3d517bda10c08080270)”, _September 2018_
- Bryan C. Mills, “[Error Wrapping and Redundancy in Go](https://github.com/bcmills/go-experience-reports/blob/master/errors.md)”, _September 2019_
- _Your Name_, “[_Title_](#URL)”, _month year_
- etc.
### Misc
- TJ Holowaychuk, [Structured access for structured logging](https://gist.github.com/tj/638adb053f802e6c19686bd2fee443b7), April, 2019
- Andrew Chambers, [My current error approach](https://gist.github.com/andrewchambers/5cadb2b8b45271440f1a051bb1ccc9c6), August, 2018
- mikioh, [A walkthrough on Error Values for issue 18183](https://gist.github.com/mikioh/93f575120ded671bad18491ecf41743d), October, 2018
### Against Any Change At All
- Rob Pike - [Simplicity is Complicated](https://www.youtube.com/watch?v=rFejpH_tAHM), December 2015

366
Go2GenericsFeedback.md

@ -1,366 +1,4 @@
# Go 2 Generics Feedback The Go wiki on GitHub has moved to go.dev (#61940).
This page is meant to collect and organize feedback about the Go 2 [contracts (generics) draft design](https://go.googlesource.com/proposal/+/master/design/go2draft-generics-overview.md). Try <https://go.dev/wiki/Go2GenericsFeedback> or <https://go.dev/wiki/>.
A prototype implementation of the syntax can be found in https://go.dev/cl/149638 which may be
patched on tip of the Go repo.
Please post feedback on your blog, Medium, GitHub Gists, mailing lists, Google Docs, etc. And then please link it here.
As the amount of feedback grows, please feel free to organize or reorganize this page by specific kind of feedback.
## Supporting
- Roger Peppe, "[Go contracts use case: generic mgo](https://gist.github.com/rogpeppe/cbbaf2521749717137625e33ba203eed)", September 2018
- Richard Fliam, "[Go2 Generics Let You Construct the Natural Numbers](https://gist.github.com/rfliam/c806a4300aa97f2762295ef97d3e924f)", August 2018
- Roger Peppe, "Go generics at runtime", [Part 1](https://gist.github.com/rogpeppe/f9216e5f2b1c99fc13108825dbda6181), [Part 2](https://gist.github.com/rogpeppe/9fa9a267472fb80e9ddc4a940aa26e14), September 2018
## Supplemental (supporting with modifications)
- Matt McCullough, "[Towards Clarity: Syntax Changes for Contracts in Go](https://gist.github.com/tooolbox/6bde6925a1a8c78cb593b2c11e977b07)" and "[Angle Brace Delimiters for Go Contracts](https://gist.github.com/tooolbox/fb385bfa05032ddc989afb393948be48)", May 2020
- Gert Cuykens, "[Complete separation of generic syntax form regular Go code](https://github.com/golang/go/issues/36533)", Januari 2020
- Court Fowler, "[Thoughts from a lazy programmer on the updated design](https://gist.github.com/courtf/ec509e0acdba6a4367a72733a8a5e61b)", September 2019
- Andrew Phillips, "[Example Types as Contracts](https://devmethodologies.blogspot.com/2019/08/example-types-as-contracts.html)", August 2019
- Alexey Nezhdanov, "[A syntax simplification proposal](https://gist.github.com/snakeru/aebc533b14a3f045f2bbb0d8eda5ed27)", August 2019
- Bryan Ford, "[Are Only Type Parameters Generic Enough for Go 2 Generics?](https://bford.info/2019/07/29/go-generics/)", July 2019
- Tom Levy, "[Go 2 Generics Feedback](https://gist.github.com/tom93/fd8c500b8a1d2d94f227e1e108d5315b)", June 2019
- Ole Bulbuk, "[Why Go Contracts Are A Bad Idea In The Light Of A Changing Go Community](https://flowdev.github.io/2019/04/02/why-go-contracts-are-a-bad-idea-in-the-light-of-a-changing-go-community/)", April 2019
- Tony Mottaz, "[Go generic types and import injection](https://gist.github.com/awmottaz/4c63c4f2067a265fac2cd8cc46e25404)", March 2019
- Gustavo Bittencourt, "[Contracts only for Generic Types](https://gist.github.com/gbitten/9faf20886728d3750e106e352c31f0e9)", March 2019
- David Heuschmann, "[Problems With Using Parantheses for Type Argument Lists](https://gist.github.com/dddent/6e4a7490f80cb427c0e910ebca5c3468)", February 2019
- Gustavo Bittencourt, "[Contract with methods](https://gist.github.com/gbitten/6e17ef81be876d70f624c711f5a3b0e2)", February 2019
- Chris Siebenmann, "[Go 2 Generics: Contracts are too clever](https://utcc.utoronto.ca/~cks/space/blog/programming/Go2ContractsTooClever)", November 2018
- Chris Siebenmann, "[Go 2 Generics: A way to make contracts more readable for people](https://utcc.utoronto.ca/~cks/space/blog/programming/Go2ContractsMoreReadable)", November 2018
- Chris Siebenmann, "[Go 2 Generics: Interfaces are not the right model for type constraints](https://utcc.utoronto.ca/~cks/space/blog/programming/Go2GenericsNotWithInterfaces)", November 2018
- alanfo, "[Proposed changes to the Go draft generics design in the light of feedback received](https://gist.github.com/alanfo/72f07362d687f625a958bde1808e0c87)", October 2018
- Andy Balholm "[Enumerated and structural contracts](https://gist.github.com/andybalholm/8165da83c10a48e56590c96542e93ff2)", October 2018
- Burak Serdar "[Types are contracts](https://gist.github.com/bserdar/8f583d6e8df2bbec145912b66a8874b3)", October 2018
- Patrick Smith, "[Go generics for built-in and user-defined type parameters](https://gist.github.com/pat42smith/ed63aca983d4ba14fdfa320296211f40)", September 2018
- Jacob Carlborg, "[Go 2 draft D corrections](https://gist.github.com/jacob-carlborg/b3c91a94f306564158b2a6ac58a57d50)", September 2018
- alanfo, "[A simplified generics constraint system](https://gist.github.com/alanfo/fb2438f376dac0db3be5664702f39aab)", September 2018
- Paul Borman, "[Simplifying syntax](https://gist.github.com/pborman/a6958ee6b7d6668e35fc99db07ea29e4)", September 2018
- mrwhythat, "[Go 2 generics draft notes](https://gist.github.com/mrwhythat/f5f2e1ea2bb9869082da55529586d972)", September 2018
- Roger Peppe, "[Operator overloading](https://gist.github.com/rogpeppe/0a87ef702189689201ef1d4a170939ac)", September 2018
- Peter McKenzie, "[Alternative generics syntax](https://gist.github.com/peter-mckenzie/5cc6530da1d966e743f4a39c150a6ac2)", September 2018
- Ted Singer, "[The design goal for syntax is to help humans read](https://gist.github.com/TedSinger/9ab1857bdd00d1f3523911362380f901)", September 2018
- alanfo, "[Suggested amendment to Go 2 generics draft design](https://gist.github.com/alanfo/5da5932c7b60fd130a928ebbace1f251)", September 2018
- Dean Bassett, "[If we're going to use contracts, allow unary + on string](https://github.com/golang/go/issues/27657), September 2018"
- Kevin Gillette, "[Regarding the Go 2 Generics Draft](https://medium.com/@xtg/regarding-the-go-2-generics-draft-39f7815be89)", September 2018
- jimmy frasche, "[Embedding of type parameters should not be allowed](https://github.com/golang/go/issues/15292#issuecomment-417422599)", August 2018
- Javier Zunzunegui, "[Compiling Generics](https://gist.github.com/JavierZunzunegui/7032f5846fd255811e7af39bd2c74f38)", August 2018
- Liam Breck, “[Please Don't Mangle the Function Signature](https://gist.github.com/networkimprov/7c1f311f26852bc912765e4110af062b)”, August 2018
- DeedleFake, "[Feedback for Go 2 Design Drafts](https://deedlefake.com/2018/08/feedback-for-go-2-design-drafts/)", August 2018
- Roberto (empijei) Clapis, "[Hard to read syntax](https://gist.github.com/empijei/a9665ac5e3059671be229acee8826798)", August 2018
- Dominik Honnef, "[My thoughts on the Go Generics Draft](http://honnef.co/posts/2018/08/opinions-on-go-generics-draft/)", August 2018
## Counterproposals
- dotaheor, "[Declare generics as mini-packages with generic parameters](https://github.com/dotaheor/unify-Go-builtin-and-custom-generics/blob/master/use-package-as-gen.md)", August 2020
- Beoran, "[Hygienic Macros](https://github.com/golang/go/issues/32620)", June 2019
- Randy O'Reilly, "[Generic Native Types](https://gist.github.com/rcoreilly/bfbee2add03c76ada82810423d81e53d)", June 2019
- Michal Štrba, "[Giving up restricting types](https://gist.github.com/faiface/e5f035f46e88e96231c670abf8cab63f)", May 2019
- Eric Miller, "[Simple generics using const struct fields](https://gist.github.com/HALtheWise/e7db03557ad52b9f9fa2722b4ef0f41e)", March 2019
- dotaheor, "[A solution to unify Go builtin and custom generics](https://github.com/dotaheor/unify-Go-builtin-and-custom-generics)", February 2019
- Quentin Quaadgras, [No syntax changes, 1 new type, 1 new builtin](https://gist.github.com/Splizard/df4c34ffe100c624c55ddaf45ac7eeb6), December 2018
- Andy Balholm, "[Contracts and Adaptors](https://gist.github.com/andybalholm/acecba3acf57bf1254142dadce928890)", November 2018
- Dean Bassett, "[Contract embedding](https://gist.github.com/deanveloper/9063720344d7a041795cba778d7de77c)", October 2018
- Patrick Smith, "[Go Generics with Adaptors](https://gist.github.com/pat42smith/ccf021193971f6de6fdb229d68215302)", October 2018
- Ian Denhardt, "[Go Generics: A Concrete Proposal Re: Using Interfaces Instead Of Contracts.](https://gist.github.com/zenhack/ad508d08c72fce6df945a49945ad826d)", October 2018
- Arendtio "[Generics in Go inspired by Interfaces](https://gist.github.com/arendtio/77dd4df5f4b19dc69da350648434a88a)", September 2018
- Scott Cotton, "[Draft Proposal Modification for Unifying Contracts and Interfaces](https://github.com/wsc1/proposal/blob/master/design/go2draft-contracts.md)" ([diff](https://github.com/golang/proposal/compare/master...wsc1:master)), September 2018
- ohir, "[CGG, Craftsman Go Generics](https://github.com/ohir/gonerics)", September 2018
- ~~Dean Bassett, "[Using interfaces instead of contracts](https://gist.github.com/deanveloper/c495da6b9263b35f98b773e34bd41104)", September 2018~~
_I have made a second proposal ("contract embedding") listed further down that solves the issues with this one_
- dotaheor, "[Combine contract and code together and view generic as compile-time calls with multiple outputs](https://gist.github.com/dotaheor/4b7496dba1939ce3f91a0f8cfccef927)", September 2018. (Updated from time to time)
- Aleksei Pavliukov, "[Extend type and func keywords](https://github.com/a5i/go-proposal/blob/master/generics.md)", September 2018
- Han Tuo, "[Generic as a kind of types -- type T generic {int, float64}](https://gist.github.com/hantuo/574aeda064c18eb69aa6806fbb259510)", September 2018
- Nate Finch, "[Go2 Contracts Go Too Far](https://npf.io/2018/09/go2-contracts-go-too-far/)", September 2018
- Roger Peppe, "[Go Contracts as type structs](https://gist.github.com/rogpeppe/7ea0cb6037aa520934257bf88a1012c5)", September 2018
- Axel Wagner, "[Scrapping contracts](https://blog.merovius.de/2018/09/05/scrapping_contracts.html)", September 2018
- Matt Sherman "[Generics as built-in typeclasses](https://clipperhouse.com/go-generics-typeclasses/)", September 2018
- Roger Peppe, "[Revised generics proposal](https://gist.github.com/rogpeppe/45f5a7578507989ec4ba5ac639ae2c69)", September 2018
- Steven Blenkinsop, “[Response to the Go2 Contracts Draft Design – Auxiliary Types](https://gist.github.com/stevenblenkinsop/7b967bb98f876b99dc15620f9fda9eb1)”, September 2018
- Dave Cheney, "[Maybe adding generics to Go IS about syntax after all](https://dave.cheney.net/2018/09/03/maybe-adding-generics-to-go-is-about-syntax-after-all)", September 2018
- Christian Surlykke, "[Constraints for Go Generics](https://github.com/surlykke/Go-Generics-with-constraints/tree/V2.0), September 2018"
- Some Gophers on go-nuts, “[Unifying Interfaces and Contracts](https://groups.google.com/forum/#!topic/golang-nuts/aw3XQV8k1Vw)”, August 2018
- Roger Peppe, "[Go generics feedback](https://gist.github.com/rogpeppe/2be10112c9d875afc0c85effc5595a09), August 2018
- Ruan Kunliang, "[Package level generics](https://gist.github.com/PeterRK/41d4d3f54b8db55cd616403fd5a389f3)", August 2018
- Emily Maier, "[Getting specific about generics](https://emilymaier.net/words/getting-specific-about-generics/)", August 2018
## Against
- Tokyo Gophers, "[Comments from Go 2 draft design feedback event](https://docs.google.com/document/d/1O6w4eL6ChROXrJ2vw9IhezzsdG7n8ToMnGnYLRQbjQg/edit?usp=sharing)", October 2018
* Jason Moiron, "[Notes on the Go2 Generics Draft](http://jmoiron.net/blog/notes-on-the-go2-generics-draft)", September 2018
* Yoshiki Shibukawa, "[Feedback for generics/contract proposals](https://gist.github.com/shibukawa/9c9eba1e68c3721f96b6f1456cfc4271), September 2018"
## Adding Your Feedback
Please format all entries as below.
- _Your Name_, “[_Title_](#URL)”, _month year_
To make it easier to see new feedback. Please _make a Gist_. And also help to keep the list sorted in reverse-chronological order by including your new entry at the _top_ of the category list.
## Quick comments
- [Chester Gould](https://github.com/Techser/): The only problem with this proposal is that explicit contracts seem to only make the code more verbose which is against the goal of simple readable code. Instead of writing explicit contracts, using the actual code we write as a kind of "implicit contract" would be much more simple and elegant. An example of this is shown [here](https://gist.github.com/Techser/72945cef3e5755d0ea0b8fd113fc25c7). I acknowledge that this is addressed [here](https://go.googlesource.com/proposal/+/refs/heads/master/design/go2draft-contracts.md#type-contracts), but I disagree that explicit contracts are the solution to problem. It seems to me that contracts are very close to what interfaces provide and so the behaviour of interfaces should be extended to allow behaviour closer to contracts rather than adding an entire new type of statement to the language.
- [Izaak Weiss](https://github.com/lalaithion): A lot of the discussion has focused specifically on how to implement contracts, or something like that. However, most of the "useful examples" don't require contracts; they only require parametric polymorphism. Writing a typesafe `Merge` or `SortSlice` is possible without contracts. And for the simpler contracts, we can implement them via higher order functions. A generic hashmap can be parametric over a type with a `Hash` method, or it can take a `func(K) int64` when it is constructed, and use that to hash its keys. If more functions are required, structs holding these functions can be declared as pseudo-contracts, and then those can be passed to the generic function. This makes Go's polymorphism simple, explicit, and leaves room for further innovation regarding contracts or other mechanisms in the future, while allowing most of the benefits of generic types to be realized right now.
- [Christoph Hack](https://github.com/tux21b): I just watched Alexandrescu's last talk [The next big Thing](https://www.youtube.com/watch?v=tcyb1lpEHm0). He states "Concepts are a waste of time" and proposes a completely different, far more powerful, direction (even in comparison to everything possible in C++ today). Go already has most required features, like reflection and testing if a type implements an optional interface. The only thing missing is code generation. For example, ``json.Marshal`` works fine by using reflection, but if it could also (optionally) generate code by implementing a Go function that gets called by the compiler automatically and runs regular Go code, we would have everything. It might sound crazy at first and toy examples might look verbose, but I think Alexandrescu has a point there. Just think about gqlgen vs. the other reflection based graphql-libs for example. Please watch his talk!
- [Bodie Solomon](https://github.com/binary132): I find the generics design a bit confusing and opaque. Please consider integrating some concepts from [Zig's beautiful comptime functions](https://news.ycombinator.com/item?id=13761571)! The design of Go 2 generics is clever, but I feel it goes against Go's traditional tight coupling between simple runtime semantics and simple syntax. Additionally, one of the biggest problems of Go, which prevents it from being a viable competitor everywhere I might like to use it, is that I cannot be rid of the GC and runtime. It was my strong hope that Go 2 would introduce compile-time-only generics such that I could reliably avoid the use of dynamic interfaces where I don't want them, without relying on codegen. Unfortunately it looks like that will be decided by the compiler without my input. Please, at least, consider giving users the ability to constrain generics to compile-time-only resolution, perhaps as a property of a Contract, rejecting compilation of dynamic types to satisfy the contract.
- Dag Sverre Seljebotn: C++ has a huge problem with people abusing metaprogramming ("generics") to do compile-time metaprogramming. I really wished Go had gone down the path of Julia, which offers hygienic macros. Even if it is kept strictly at a compile-time barrier and no run-time code generation, this would at least avoid all the bad tendencies we see in the C++ world that comes from their templating system. Things you can do with generics you can usually pull off with macros too (e.g., `SortSliceOfInts = MakeSliceSorterFunctionMacro!(int)` could generate a new function to sort a slice of integers). Link: https://docs.julialang.org/en/v0.6.1/manual/metaprogramming/
- Maxwell Corbin: The issues raised in the Discussion and Open Questions section all could be avoided by defining generics at the package rather than the function or type level. The reason for this is simple: types can reference themselves, but packages can't import themselves, and while there are many ways to algorithmically generate more type signatures, you cannot do the same with import statements. A quick example of such syntax might be:
```go
\\ list
package list[T]
type T interface{}
type List struct {
Val T
Next *List
}
// main
package main
import (
il "list"[int]
sl "list"[string]
)
var iList = il.List{3}
var sList = sl.List{"hello"}
// etc...
```
The syntax in the example is probably needlessly verbose, but the point is that none of the unfortunate code examples from the blog post are even legal constructions. Package level generics avoids the most abusive problems of meta-programming while retaining the bulk of its usefulness.
- Andrew Gwozdziewycz: The use of the word `contract` gives me pause due to it overloading "contract" as in [Design by Contract](https://en.wikipedia.org/wiki/Design_by_contract). While the generics use case has some similarities with the "contracts" in DbC if you squint a bit, the concepts are quite different. Since "contracts" are an established concept in Computer Science, I think it would be far less confusing to use a different name like `behavior` or `trait`. The design document also suggests reasons why using `interface` is not ideal, though, Go's contract mechanism seems too obvious an extension of interfaces to disregard so quickly... If it can be done `interface setter(x T) { x.Set(string) error }` and `interface addable(x T, y U) { x + y }` seem quite natural to read and understand.
- Russell Johnston: Agreed that it would be great to merge contracts and interfaces. Another way around the operator-naming problem might be to provide some standard interfaces for the operators, with bodies inexpressible in normal Go code. For example, a standard `Multipliable` interface would allow the `*` and `*=` operators, while a standard `Comparable` interface would allow `==`, `!=`, `<`, `<=`, `>=`, and `>`. To express operators with multiple types, these interfaces would presumably need type parameters themselves, for example: `type Multipliable(s Self /* this exists implicitly on all interfaces */, t Other) interface { /* provided by the language */ }`. Then user-written interfaces/contracts could use these standard identifier-based names, neatly sidestepping the issues mentioned in the design document around syntax and types.
- Roberto (empijei) Clapis: I agree on this and on the fact that it should be clearer where to use interfaces and where to use contracts. Unifying the two would be great, as they try to address overlapping issues.
- Kurnia D Win: I think `constraint` is better keyword than `contract`. Personally i like `type addable constraint(x T, y U) { x + y }` instead of merging with interface.
- Hajime Hoshi: I feel like the supposed proposal is too huge to the problems we want to solve listed at https://go.googlesource.com/proposal/+/master/design/go2draft-generics-overview.md . I'm worried this feature would be abused and degrade readability of code. Sorry if I am missing, but the proposal doesn't say anything about `go generate`. Wouldn't `go generate` be enough to the problems?
- Stephen Rowles: I find the method syntax hard to parse, as a human reading it, it might be clearer to use a different type of enclosing brackets for the type section, e.g. : Me too 👍 +1. Yet another 👍 +1(Pasha Osipyants).
```
func Sum<type T Addable>(x []T) T {
var total T
for _, v := range x {
total += v
}
return total
}
```
- yesuu: In this example, think of `T` as the parameter name and `type` as the parameter type. Obviously it is more reasonable to put the `type` behind, and contract is followed by `type`, like `chan int`.
```go
func Sum(T type Addable)(x []T) T
```
- Roberto Clapis: Please read [this section](https://go.googlesource.com/proposal/+/master/design/go2draft-contracts.md#why-not-use-like-c_and-java)
- Seems like a bit of a cop-out tbh. It says "in general" which means there must already be exceptions. Go has a nice clear syntax making code simple to read and easy for teams to collaborate. I think it would be worth making the parser more complicated for the sake of making the code readability better. For large scale and long running project readability of the code, and hence maintainability, is king
- What about [this](https://gist.github.com/empijei/a9665ac5e3059671be229acee8826798)
- Seebs: [Feedback a bit long to inline](https://gist.github.com/seebs/8f943b8b15a8c63c28c7f6f4e5ca6c53), August 2018. Summary basically "I would like a way to specify one contract for each of two types rather than one contract for both types", and "I would prefer `map[T1]T2` to `t1var == t1var` as a canonical form of "T1 must be an allowable map key".
- Seebs: [What if contracts _were_ just the type-parametric functions?](https://github.com/seebs/notes/blob/master/generics_go2.md). (Sep 1, 2018)
- Sean Quinlan: I find the contract syntax quite confusing. For something that is supposed to defined exactly what is needed and will be part of the documentation of an api, it can contain all sorts of cruft that does not impact the contract. Moreover, to quote from the design: "We don’t need to explain the meaning of every statement that can appear in a contract body". That seems like the opposite of what I would want from a contract. The fact one can copy the body of a function into a contract and have it work seems like a bug to me, not a feature. Personally, I would much prefer a model that unifies interfaces and contracts. Interfaces feel much closer to what I would like a contract to look like and there is a lot of overlap. It seems probable that many contracts will also be interfaces?
- Nodir Turakulov: Please elaborate
> Packages like container/list and container/ring, and types like sync.Map, will be updated to be compile-time type-safe.
and
> The math package will be extended to provide a set of simple standard algorithms for all numeric types, such as the ever popular Min and Max functions.
or ideally add a section about transition/migration of existing types/funcs to use type polymorphism.
FWIU adding type parameter(s) to an existing type/func most likely breaks an existing program that uses the type/func.
How exactly will `math.Max` be changed?
Is the intention to make backward-incompatible changes and write tools to automatically convert code to Go2?
What is the general recommendation for authors of other libraries that provide funcs and types that currently operate with `interface{}`?
Were default values for type parameters considered? e.g. type parameter for `math.Max` would default to `float64` and type parameter for `"container/list".List` would default to `interface{}`
- Ward Harold: If only for the sake of completeness the [Modula-3](https://www.cs.purdue.edu/homes/hosking/m3/reference/generics.html) generics design should be incorporated into the [Designs in Other Languages](https://go.googlesource.com/proposal/+/master/design/go2draft-generics-overview.md#designs-in-other-languages) section. Modula-3 was a beautiful language that sadly got introduced at the wrong time.
- Matt Holiday: Ditto mentioning the [Alphard](<https://en.wikipedia.org/wiki/Alphard_(programming_language)>) language, which was developed about the same time as CLU and also influenced the Ada design. See Alphard: Form and Content, Mary Shaw, ed., Springer 1991 for the various papers collected with some glue material. Alphard & Ada were my introductions to generic programming. Could Go beat C++ for finally delivering contracts after 40 years of waiting?
- Ole Begemann: You write on the [Generics Overview page](https://go.googlesource.com/proposal/+/master/design/go2draft-generics-overview.md): "Swift added generics in Swift 4, released in 2017." This is not true. Swift has had generics since its first public release in 2014. Evidence (just one example of many): [a transcript of an Apple developer talk on Swift from WWDC 2014](https://asciiwwdc.com/2014/sessions/404) that talks at length about Swift's generics features.
This is also incorrect: "`Equatable` appears to be a built-in in Swift, not possible to define otherwise." The `Equatable` protocol is defined in the Swift standard library, but there's nothing special about it. It's totally possible to define the same thing in "normal" code.
- Kevin Gillette: correction for "Contracts" Draft, as of 30 August 2018
The one instance of `check.Convert(int, interface{})(0, 0)` should instead be `check.Convert(int, interface{})(0)` or provide an explanation as to why it the function should take two zeros instead of one.
- [Adam Ierymenko](http://adamierymenko.com): I have an idea for doing limited operator overloading in Go that might make this proposal more useful for numeric code. It's big so [I stuck it in a Gist here](https://gist.github.com/adamierymenko/a03a62da1513a8cc2ac4dfac81b44a9f).
- DeedleFake: I completely agree with the arguments against operator overloading, and I'm quite glad overall that Go doesn't have it, but I also think that the inability to resolve the difference between `a == b` and `a.Equals(b)` via a contract is the biggest problem with the draft design as it currently stands. It means that you'd still wind up writing multiple functions for a fair number of things. Try writing a binary tree, for example. Should you use a contract with `t < t` or `t.Less(t)`? For a sum function, should you use `t + t` or `t.Plus(t)`? I definitely want a solution that doesn't involve operator overloading, though. Maybe there could be a way to specify an adapter that basically says `if a type T, which satisfies contract A but not B, is used for a parameter constrained by contract B, apply this to it in order to get it to satisfy contract B`. Contract B could require a `Plus()` method, for example, while contract A requires the use of `+`, so the adapter automatically attaches a user-specified `Plus()` method to `T` for the duration of its use under that contract.
- Something that might work with this proposal is an `equal(a, b)` builtin that uses `a.Equals(b)` if it exists and `a == b` otherwise, failing to compile if the type is incomparable (and likewise for other operators). It's too weird to seriously consider but it would work with contracts and allow dodging the asymmetry between types that have operators and those that cannot without introducing operator overloading —jimmyfrasche
- Another idea would be explicitly overloadable operators: `a + b` is not overloadable, but `a [+] b` can be overloaded. It will use normal + for primitive types, but will use `Operator+()` etc. for objects if those are present. I really do think that generics without some sane form of operator overloading or something like it are a lot less useful to the point that you might as well not even do it. -Adam Ierymenko (original poster)
- Ian Denhardt: DeedleFake outlines the problems with not having operator overloading well I. I think proposals involving making the overloading "loud" are the wrong idea; instead, we should limit which operators can be overloaded to operators which satisfy these critera:
1. The operator's semantics can be understood as a method call. Most of the operators on numbers pass this test; `big.Add` is still addition in the sense that we know it from int32, uint64 etc. Examples of operators that fail this test are `&&` and `||`; these are short circuting, which no function or method can replicate. They are fundamentally not methods, no matter how you look at them, and should not be overridable by methods. I think operator overloading gets a bad rap in part because C++ allows you to override _everything_, including crazy stuff like the _comma operator_.
2. There should be clear use cases for overriding them. Again, arithmetic operators pass this test, along with `<` and friends. Pointer dereferencing passes the first test, but I'm having a hard time coming up with uses for "other types of pointers" that actually seem like a good idea. They are a bit more justifiable in C++, but garbage-collected pointers have basically got you covered.
3. The normal meaning of the operator should be something that is easy to reason about. For example, pointers are a gnarly source of bugs, and having the possibility that `*foo` is doing something other than reading from a memory address makes an already difficult debugging session that much harder. On the other hand, the possibility that `+` may be a call to `big.Add` is relatively self-contained, and unlikely to cause great confusion.
4. Finally, the standard library has to set a good example; methods overriding `+` should be conceptually addition, for example. C++ gets off on an utterly wrong foot here by defining what is morally `os.Stdout.ShiftLeft("Hello, World!")`.
- Eltjon Metko: How about specifying the contract after the type identifier inside the function Parameters? This way it can be inferred what T is and we can eliminate the first group of parenthesis.
```
func Sum(x []T:Addable) T {
var total T
for _, v := range x {
total += v
}
return total
}
```
- Tristan Colgate-McFarlane: After going back and forward for a while, I've come down in favour of the proposal largely as is. A limited syntax for contracts might be preferable, but I believe it should allow referencing specific fields (not just methods as some have proposed). If anything can be done to make compatible interface and contracts inter-use easier, that would also be nice (though I think maybe no additional specifications are needed. Lastly, I think it is worth considering deprecating interface types. Whilst drastic, contracts essentially also allow specifying behaviour. Any contract restrictions that limit that (such as refering to other types within the package), should probably be lifted. contracts appear to be a strict superset of interfaces, and I am generally against having two overlapping features. A tool to aide in writing interaces should also be considered.
- Patrick Smith: We might consider requiring the type keyword when defining methods on generic types. This makes the code a little more verbose, but clearer and more consistent (now type parameters are always preceded by the type keyword).
```
func (x Foo(type T)) Bar()
```
- Patrick Smith: In this example, is `Foo(T)` embedded in `Bar(T)`, or does `Bar(T)` have a method named `Foo`?
```
type Foo(type T) interface {}
type Bar(type T) interface {
Foo(T)
}
```
- Xingtao Zhao: There are too many round brackets in the proposal. In the proposal, it is said that "[]" is ambiguous in some cases. While if we use [type T, S contract], there are no ambiguities any more.
- Dave Cheney: The earlier Type Functions proposal showed that a type declaration can support a parameter. If this is correct, then the proposed contract declaration could be rewritten from
```
contract stringer(x T) {
var s string = x.String()
}
```
to
```
type stringer(x T) contract {
var s string = x.String()
}
```
This supports Roger’s observation that a contract is a superset of an interface. `type stringer(x T) contract { ... }` introduces a new contract type in the same way `type stringer interface { ... }` introduces a new interface type.
- jimmyfrasche: A contract is not a type, though. You can't have a value that is a `stringer`. You can have a value of a type that is a `stringer`. It's a metatype. A type is a kind of predicate on values. You ask the compiler "is this value a `string`" and it answers yes (allowing compilation to continue) or no (stopping to tell you what went wrong). A contract is a predicate on a vector of types. You ask the compiler two questions. Do these types satisfy this contract? Then: do these values satisfy these types? Interfaces kind of blur these lines by storing a `(type, value)` pair, provided that the type has the appropriate methods. It's simultaneously a type and a metatype. Any generics system that does not use interfaces as the metatypes will unavoidably contain a superset of interfaces. While it is entirely possible to define a generics system that exclusively uses interfaces as the metatypes, that does mean losing the ability to write generic functions that use things that interfaces can't talk about, like operators. You have to limit the questions you can ask about the types to their method sets. (I'm fine with this).
- btj: Two very important entries are missing in the draft design document's Designs in Other Languages section: Haskell, with its typeclasses, and Scala, with its implicit arguments.
- iamgoroot: Wouldn't it be natural to make better type aliasing support and let user have generics as option? And you dont need much syntax for that
```
type Key _
type Value _
type IntStringHolder Holder<Key:int, Value:string>
type Holder struct {
K Key
V Value
}
func (h *Holder) Set(k Key, v Value) {
h.K = k
h.V = v
}
func main() {
v:= IntStringHolder{}
v.Set(7,"Lucky")
}
```
- antoniomo: While the draft clearly explains why `F<T>`, `F[T]` and non-ASCII (unable to type it here) `F<<T>>` where discarded, feels like `F{T}` would be more human readable than the sometimes three in a row set of `()`, while not complicating the parser with unbounded lookahead as you can't open a block in those circumstances.
- aprice2704: I really dislike the idea of using regular parentheses `(`, would a two-character sequence cause compiler overhead from unbounded lookahead? How about <| and |> ? would they work? They have the advantages of being quite distinct from `(`, making some visual sense in ascii, and in the 'Fira Code' font (highly recommended) which I use in VSCode there are ligatures to render these as little right or left pointing triangles.
- leaxoy: First I'm sorry for editing the page footer, however I can't remove footer content. This is my opinion: lots of `(` & `)` made go looks so messy, `<` & `>` like other language is better, and is more kindly for those come from other languages.
- Hajime Hoshi: I completely agree on aprice2704's syntax concern. Wouldn't `[[` / `]]` work, for example?

1595
GoArm.md

File diff suppressed because it is too large Load Diff

683
GoForCPPProgrammers.md

@ -1,683 +1,4 @@
Go is a systems programming language intended to be a general-purpose systems language, like C++. These are some notes on Go for experienced C++ programmers. This document discusses the differences between Go and C++, and says little to nothing about the similarities. The Go wiki on GitHub has moved to go.dev (#61940).
An important point to keep in mind is that there are some fundamental differences in the thought processes required to be proficient in the two respective languages. Most formidably, C++'s object model is based on classes and class hierarchies while Go's object model is based on interfaces (and is essentially flat). Consequently, C++ design patterns rarely translate verbatim to Go. To program effectively in Go, one has to consider the _problem_ being solved, not the mechanisms one might use in C++ to solve the problem. Try <https://go.dev/wiki/GoForCPPProgrammers> or <https://go.dev/wiki/>.
For a more general introduction to Go, see the <a href='http://tour.golang.org/'>Go Tour</a>, <a href='https://go.dev/doc/code'>How to Write Go Code</a> and <a href='https://go.dev/doc/effective_go'>Effective Go</a>.
For a detailed description of the Go language, see the <a href='https://go.dev/ref/spec'>Go spec</a>.
<h2>Conceptual Differences</h2>
<ul>
<li>Go does not have classes with constructors or destructors. Instead of class methods, a class inheritance hierarchy, and virtual functions, Go provides <em>interfaces</em>, which are discussed in more detail below. Interfaces are also used where C++ uses templates.</li>
<li>Go provides automatic garbage collection of allocated memory. It is not necessary (or possible) to release memory explicitly. There is no need to worry about heap-allocated vs. stack-allocated storage, <code>new</code> vs. <code>malloc</code>, or <code>delete</code> vs. <code>delete[]</code> vs. <code>free</code>. There is no need to separately manage <code>std::unique_ptr</code>, <code>std::shared_ptr</code>, <code>std::weak_ptr</code>, <code>std::auto_ptr</code>, and ordinary, non-smart "raw" pointers. Go's run-time system handles all of that error-prone code on the programmer's behalf.</li>
<li>Go has pointers but not pointer arithmetic. Go pointers therefore more closely resemble C++ references. One cannot use a Go pointer variable to walk through the bytes of a string. Slices, discussed further below, satisfy most of the need for pointer arithmetic.</li>
<li>Go is "safe" by default. Pointers cannot point to arbitrary memory, and buffer overruns result in crashes, not security exploits. The <code>unsafe</code> package lets programmers bypass some of Go's protection mechanisms where explicitly requested.</li>
<li>Arrays in Go are first class values. When an array is used as a function parameter, the function receives a copy of the array, not a pointer to it. However, in practice functions often use slices for parameters; slices hold pointers to underlying arrays. Slices are discussed further below.</li>
<li>Strings are provided by the language. They may not be changed once they have been created.</li>
<li>Hash tables are provided by the language. They are called maps.</li>
<li>Separate threads of execution, and communication channels between them, are provided by the language. This is discussed further below.</li>
<li>Certain types (maps and channels, described further below) are passed by reference, not by value. That is, passing a map to a function does not copy the map, and if the function changes the map the change will be seen by the caller. In C++ terms, one can think of these as being reference types.</li>
<li>Go does not use header files. Instead, each source file is part of a defined <em>package</em>. When a package defines an object (type, constant, variable, function) with a name starting with an upper case letter, that object is visible to any other file which imports that package.</li>
<li>Go does not support implicit type conversion. Operations that mix different types require casts (called conversions in Go). This is true even of different user-defined aliases of the same underlying type.</li>
<li>Go does not support function overloading and does not support user defined operators.</li>
<li>Go does not support <code>const</code> or <code>volatile</code> qualifiers.</li>
<li>Go uses <code>nil</code> for invalid pointers, where C++ uses <code>NULL</code> or simply <code>0</code> (or in C++11, <code>nullptr</code>).</li>
<li>Idiomatic Go uses multiple return values to convey errors—one or more data results plus an error code—instead of sentinel values (e.g., <code>-1</code>) or structured exception handling (C++'s <code>try</code>…<code>catch</code> and <code>throw</code> or Go's <code>panic</code>…<code>recover</code>).</li>
</ul>
<h2>Syntax</h2>
The declaration syntax is reversed compared to C++. You write the name followed by the type. Unlike in C++, the syntax for a type does not match the way in which the variable is used. Type declarations may be read easily from left to right. (`var v1 int` → "Variable `v1` is an `int`.")
```go
//Go C++
var v1 int // int v1;
var v2 string // const std::string v2; (approximately)
var v3 [10]int // int v3[10];
var v4 []int // int* v4; (approximately)
var v5 struct { f int } // struct { int f; } v5;
var v6 *int // int* v6; (but no pointer arithmetic)
var v7 map[string]int // unordered_map<string, int>* v7; (approximately)
var v8 func(a int) int // int (*v8)(int a);
```
Declarations generally take the form of a keyword followed by the name of the object being declared. The keyword is one of `var`, `func`, `const`, or `type`. Method declarations are a minor exception in that the receiver appears before the name of the object being declared; see the <a href='#interfaces'>discussion of interfaces</a>.
You can also use a keyword followed by a series of declarations in parentheses.
```go
var (
i int
m float64
)
```
When declaring a function, you must either provide a name for each parameter or not provide a name for any parameter. (That is, C++ permits `void f(int i, int);`, but Go does not permit the analogous `func f(i int, int)`.) However, for convenience, in Go you may group several names with the same type:
```go
func f(i, j, k int, s, t string)
```
A variable may be initialized when it is declared. When this is done, specifying the type is permitted but not required. When the type is not specified, the type of the variable is the type of the initialization expression.
```go
var v = *p
```
See also the <a href='#Constants'>discussion of constants, below</a>. If a variable is not initialized explicitly, the type must be specified. In that case it will be implicitly initialized to the type's zero value (`0`, `nil`, etc.). There are no uninitialized variables in Go.
Within a function, a short declaration syntax is available with `:=` .
```go
v1 := v2 // C++11: auto v1 = v2;
```
This is equivalent to
```go
var v1 = v2 // C++11: auto v1 = v2;
```
Go permits multiple assignments, which are done in parallel. That is, first all of the values on the right-hand side are computed, and then these values are assigned to the variables on the left-hand side.
```go
i, j = j, i // Swap i and j.
```
Functions may have multiple return values, indicated by a list in parentheses. The returned values can be stored by assignment to a list of variables.
```go
func f() (i int, j int) { ... }
v1, v2 = f()
```
Multiple return values are Go's primary mechanism for error handling:
```go
result, ok := g()
if !ok {
// Something bad happened.
return nil
}
// Continue as normal.
…
```
or, more tersely,
```go
if result, ok := g(); !ok {
// Something bad happened.
return nil
}
// Continue as normal.
…
```
Go code uses very few semicolons in practice. Technically, all Go statements are terminated by a semicolon. However, Go treats the end of a non-blank line as a semicolon unless the line is clearly incomplete (the exact rules are in <a href='https://go.dev/ref/spec#Semicolons'>the language specification</a>). A consequence of this is that in some cases Go does not permit you to use a line break. For example, you may not write
```go
func g()
{ // INVALID
}
```
A semicolon will be inserted after `g()`, causing it to be a function declaration rather than a function definition. Similarly, you may not write
```go
if x {
}
else { // INVALID
}
```
A semicolon will be inserted after the `}` preceding the `else`, causing a syntax error.
Since semicolons do end statements, you may continue using them as in C++. However, that is not the recommended style. Idiomatic Go code omits unnecessary semicolons, which in practice is all of them other than the initial ` for ` loop clause and cases where you want several short statements on a single line.
While we're on the topic, we recommend that rather than worry about semicolons and brace placement, you format your code with the `gofmt` program. That will produce a single standard Go style, and let you worry about your code rather than your formatting. While the style may initially seem odd, it is as good as any other style, and familiarity will lead to comfort.
When using a pointer to a struct, you use `.` instead of `->`. Thus, syntactically speaking, a structure and a pointer to a structure are used in the same way.
```go
type myStruct struct{ i int }
var v9 myStruct // v9 has structure type
var p9 *myStruct // p9 is a pointer to a structure
f(v9.i, p9.i)
```
Go does not require parentheses around the condition of an `if` statement, or the expressions of a `for` statement, or the value of a `switch` statement. On the other hand, it does require curly braces around the body of an `if` or `for` statement.
```go
if a < b { f() } // Valid
if (a < b) { f() } // Valid (condition is a parenthesized expression)
if (a < b) f() // INVALID
for i = 0; i < 10; i++ {} // Valid
for (i = 0; i < 10; i++) {} // INVALID
```
Go does not have a `while` statement nor does it have a `do/while` statement. The `for` statement may be used with a single condition, which makes it equivalent to a `while` statement. Omitting the condition entirely is an endless loop.
Go permits `break` and `continue` to specify a label. The label must refer to a `for`, `switch`, or `select` statement.
In a `switch` statement, `case` labels do not fall through. You can make them fall through using the `fallthrough` keyword. This applies even to adjacent cases.
```go
switch i {
case 0: // empty case body
case 1:
f() // f is not called when i == 0!
}
```
But a `case` can have multiple values.
```go
switch i {
case 0, 1:
f() // f is called if i == 0 || i == 1.
}
```
The values in a `case` need not be constants--or even integers; any type that supports the equality comparison operator, such as strings or pointers, can be used--and if the `switch` value is omitted it defaults to `true`.
```go
switch {
case i < 0:
f1()
case i == 0:
f2()
case i > 0:
f3()
}
```
The `defer` statement may be used to call a function after the function containing the `defer` statement returns. `defer` often takes the place of a destructor in C++ but is associated with the calling code, not any particular class or object.
```go
fd := open("filename")
defer close(fd) // fd will be closed when this function returns.
```
<h2>Operators</h2>
The `++` and `--` operators may only be used in statements, not in expressions. You cannot write `c = *p++`. `*p++` is parsed as `(*p)++`.
The operator precedence is different. As an example `4 & 3 << 1` evaluates to `0` in Go and `4` in C++.
```
Go operator precedence:
1. * / % << >> & &^
2. + - | ^
3. == != < <= > >=
4. &&
5. ||
```
```
C++ operator precedence (only relevant operators):
1. * / %
2. + -
3. << >>
4. < <= > >=
5. == !=
6. &
7. ^
8. |
9. &&
10. ||
```
<h2>Constants</h2>
In Go constants may be <i>untyped</i>. This applies even to constants named with a `const` declaration, if no type is given in the declaration and the initializer expression uses only untyped constants. A value derived from an untyped constant becomes typed when it is used within a context that requires a typed value. This permits constants to be used relatively freely without requiring general implicit type conversion.
```go
var a uint
f(a + 1) // untyped numeric constant "1" becomes typed as uint
```
The language does not impose any limits on the size of an untyped numeric constant or constant expression. A limit is only applied when a constant is used where a type is required.
```go
const huge = 1 << 100
f(huge >> 98)
```
Go does not support enums. Instead, you can use the special name `iota` in a single `const` declaration to get a series of increasing value. When an initialization expression is omitted for a `const`, it reuses the preceding expression.
```go
const (
red = iota // red == 0
blue // blue == 1
green // green == 2
)
```
<h2>Types</h2>
C++ and Go provide similar, but not identical, built-in types: signed and unsigned integers of various widths, 32-bit and 64-bit floating-point numbers (real and complex), `struct`s, pointers, etc. In Go, `uint8`, `int64`, and like-named integer types are part of the language, not built on top of integers whose sizes are implementation-dependent (e.g., `long long`). Go additionally provides native `string`, `map`, and `chan` (channel) types as well as first-class arrays and slices (described below). Strings are encoded with Unicode, not ASCII.
Go is far more strongly typed than C++. In particular, there is no implicit type conversion in Go, only explicit type conversion. This provides additional safety and freedom from a class of bugs but at the cost of some additional typing. There is also no `union` type in Go, as this would enable subversion of the type system. However, a Go `interface{}` (see below) provides a type-safe alternative.
Both C++ and Go support type aliases (`typedef` in C++, `type` in Go). However, unlike C++, Go treats these as different types. Hence, the following is valid in C++:
```C++
// C++
typedef double position;
typedef double velocity;
position pos = 218.0;
velocity vel = -9.8;
pos += vel;
```
but the equivalent is invalid in Go without an explicit type conversion:
```go
type position float64
type velocity float64
var pos position = 218.0
var vel velocity = -9.8
pos += vel // INVALID: mismatched types position and velocity
// pos += position(vel) // Valid
```
The same is true even for unaliased types: an `int` and a `uint` cannot be combined in an expression without explicitly converting one to the other.
Go does not allow pointers to be cast to and from integers, unlike in C++. However, Go's `unsafe` package enables one to explicitly bypass this safety mechanism if necessary (e.g., for use in low-level systems code).
<h2>Slices</h2>
A slice is conceptually a struct with three fields: a pointer to an array, a length, and a capacity. Slices support the `[]` operator to access elements of the underlying array. The builtin `len` function returns the length of the slice. The builtin `cap` function returns the capacity.
Given an array, or another slice, a new slice is created via `a[i:j]`. This creates a new slice that refers to `a`, starts at index `i`, and ends before index `j`. It has length `j-i`. If `i` is omitted, the slice starts at `0`. If `j` is omitted, the slice ends at `len(a)`. The new slice refers to the same array to which `a` refers. Two implications of this statement are that ① changes made using the new slice may be seen using `a`, and ② slice creation is (intended to be) cheap; no copy needs to be made of the underlying array. The capacity of the new slice is simply the capacity of `a` minus `i`. The capacity of an array is the length of the array.
What this means is that Go uses slices for some cases where C++ uses pointers. If you create a value of type `[100]byte` (an array of 100 bytes, perhaps a buffer) and you want to pass it to a function without copying it, you should declare the function parameter to have type `[]byte`, and pass a slice of the array (`a[:]` will pass the entire array). Unlike in C++, it is not necessary to pass the length of the buffer; it is efficiently accessible via `len`.
The slice syntax may also be used with a string. It returns a new string, whose value is a substring of the original string. Because strings are immutable, string slices can be implemented without allocating new storage for the slices's contents.
<h2>Making values</h2>
Go has a builtin function `new` which takes a type and allocates space on the heap. The allocated space will be zero-initialized for the type. For example, `new(int)` allocates a new int on the heap, initializes it with the value `0`, and returns its address, which has type `*int`. Unlike in C++, `new` is a function, not an operator; `new int` is a syntax error.
Perhaps surprisingly, `new` is not commonly used in Go programs. In Go taking the address of a variable is always safe and never yields a dangling pointer. If the program takes the address of a variable, it will be allocated on the heap if necessary. So these functions are equivalent:
```go
type S struct { I int }
func f1() *S {
return new(S)
}
func f2() *S {
var s S
return &s
}
func f3() *S {
// More idiomatic: use composite literal syntax.
return &S{}
}
```
In contrast, it is not safe in C++ to return a pointer to a local variable:
```C++
// C++
S* f2() {
S s;
return &s; // INVALID -- contents can be overwritten at any time
}
```
Map and channel values must be allocated using the builtin function `make`. A variable declared with map or channel type without an initializer will be automatically initialized to `nil`. Calling `make(map[int]int)` returns a newly allocated value of type `map[int]int`. Note that `make` returns a value, not a pointer. This is consistent with the fact that map and channel values are passed by reference. Calling `make` with a map type takes an optional argument which is the expected capacity of the map. Calling `make` with a channel type takes an optional argument which sets the buffering capacity of the channel; the default is 0 (unbuffered).
The `make` function may also be used to allocate a slice. In this case it allocates memory for the underlying array and returns a slice referring to it. There is one required argument, which is the number of elements in the slice. A second, optional, argument is the capacity of the slice. For example, `make([]int, 10, 20)`. This is identical to `new([20]int)[0:10]`. Since Go uses garbage collection, the newly allocated array will be discarded sometime after there are no references to the returned slice.
<h2>Interfaces</h2>
Where C++ provides classes, subclasses and templates, Go provides interfaces. A Go interface is similar to a C++ pure abstract class: a class with no data members, with methods which are all pure virtual. However, in Go, any type which provides the methods named in the interface may be treated as an implementation of the interface. No explicitly declared inheritance is required. The implementation of the interface is entirely separate from the interface itself.
A method looks like an ordinary function definition, except that it has a <em>receiver</em>. The receiver is similar to the `this` pointer in a C++ class method.
```go
type myType struct{ i int }
func (p *myType) Get() int { return p.i }
```
This declares a method `Get` associated with `myType`. The receiver is named `p` in the body of the function.
Methods are defined on named types. If you convert the value to a different type, the new value will have the methods of the new type,
not the old type.
You may define methods on a builtin type by declaring a new named type derived from it. The new type is distinct from the builtin type.
```go
type myInteger int
func (p myInteger) Get() int { return int(p) } // Conversion required.
func f(i int) {}
var v myInteger
// f(v) is invalid.
// f(int(v)) is valid; int(v) has no defined methods.
```
Given this interface:
```go
type myInterface interface {
Get() int
Set(i int)
}
```
we can make `myType` satisfy the interface by adding
```go
func (p *myType) Set(i int) { p.i = i }
```
Now any function which takes `myInterface` as a parameter will accept a variable of type `*myType`.
```go
func GetAndSet(x myInterface) {}
func f1() {
var p myType
GetAndSet(&p)
}
```
In other words, if we view `myInterface` as a C++ pure abstract base class, defining `Set` and `Get` for `*myType` made `*myType` automatically inherit from `myInterface`. A type may satisfy multiple interfaces.
An anonymous field may be used to implement something much like a C++ child class.
```go
type myChildType struct {
myType
j int
}
func (p *myChildType) Get() int { p.j++; return p.myType.Get() }
```
This effectively implements `myChildType` as a child of `myType`.
```go
func f2() {
var p myChildType
GetAndSet(&p)
}
```
The `Set` method is effectively inherited from `myType`, because methods associated with the anonymous field are promoted to become methods of the enclosing type. In this case, because `myChildType` has an anonymous field of type `myType`, the methods of `myType` also become methods of `myChildType`. In this example, the `Get` method was overridden, and the `Set` method was inherited.
This is not precisely the same as a child class in C++. When a method of an anonymous field is called, its receiver is the field, not the surrounding struct. In other words, methods on anonymous fields are not virtual functions. When you want the equivalent of a virtual function, use an interface.
A variable that has an interface type may be converted to have a different interface type using a special construct called a type assertion. This is implemented dynamically at run time, like C++ `dynamic_cast`. Unlike `dynamic_cast`, there does not need to be any declared relationship between the two interfaces.
```go
type myPrintInterface interface {
Print()
}
func f3(x myInterface) {
x.(myPrintInterface).Print() // type assertion to myPrintInterface
}
```
The conversion to `myPrintInterface` is entirely dynamic. It will work as long as the dynamic type of x defines a `Print` method.
Because the conversion is dynamic, it may be used to implement generic programming similar to templates in C++. This is done by manipulating values of the minimal interface.
```go
type Any interface{}
```
Containers may be written in terms of `Any`, but the caller must unbox using a type assertion to recover values of the contained type. As the typing is dynamic rather than static, there is no equivalent of the way that a C++ template may inline the relevant operations. The operations are fully type-checked at run time, but all operations will involve a function call.
```go
type Iterator interface {
Get() Any
Set(v Any)
Increment()
Equal(arg Iterator) bool
}
```
Note that `Equal` has an argument of type `Iterator`. This does not behave like a C++ template. See <a href='go_faq.html#t_and_equal_interface'>the FAQ</a>.
<h2>Function closures</h2>
In C++ versions prior to C++11, the most common way to create a function with hidden state is to use a "functor"—a class that overloads `operator()` to make instances look like functions. For example, the following code defines a `my_transform` function (a simplified version of the STL's `std::transform`) that applies a given unary operator (`op`) to each element of an array (`in`), storing the result in another array (`out`). To implement a prefix sum (i.e., {`x[0]`, `x[0]+x[1]`, `x[0]+x[1]+x[2]`, …}) the code creates a functor (`MyFunctor`) that keeps track of the running total (`total`) and passes an instance of this functor to `my_transform`.
```C++
// C++
#include <iostream>
#include <cstddef>
template <class UnaryOperator>
void my_transform (size_t n_elts, int* in, int* out, UnaryOperator op)
{
size_t i;
for (i = 0; i < n_elts; i++)
out[i] = op(in[i]);
}
class MyFunctor {
public:
int total;
int operator()(int v) {
total += v;
return total;
}
MyFunctor() : total(0) {}
};
int main (void)
{
int data[7] = {8, 6, 7, 5, 3, 0, 9};
int result[7];
MyFunctor accumulate;
my_transform(7, data, result, accumulate);
std::cout << "Result is [ ";
for (size_t i = 0; i < 7; i++)
std::cout << result[i] << ' ';
std::cout << "]\n";
return 0;
}
```
C++11 adds anonymous ("lambda") functions, which can be stored in variables and passed to functions. They can optionally serve as closures, meaning they can reference state from parent scopes. This feature greatly simplifies `my_transform`:
```C++
// C++11
#include <iostream>
#include <cstddef>
#include <functional>
void my_transform (size_t n_elts, int* in, int* out, std::function<int(int)> op)
{
size_t i;
for (i = 0; i < n_elts; i++)
out[i] = op(in[i]);
}
int main (void)
{
int data[7] = {8, 6, 7, 5, 3, 0, 9};
int result[7];
int total = 0;
my_transform(7, data, result, [&total] (int v) {
total += v;
return total;
});
std::cout << "Result is [ ";
for (size_t i = 0; i < 7; i++)
std::cout << result[i] << ' ';
std::cout << "]\n";
return 0;
}
```
A typical Go version of `my_transform` looks a lot like the C++11 version:
```go
package main
import "fmt"
func my_transform(in []int, xform func(int) int) (out []int) {
out = make([]int, len(in))
for idx, val := range in {
out[idx] = xform(val)
}
return
}
func main() {
data := []int{8, 6, 7, 5, 3, 0, 9}
total := 0
fmt.Printf("Result is %v\n", my_transform(data, func(v int) int {
total += v
return total
}))
}
```
(Note that we chose to return `out` from `my_transform` rather than pass it an `out` to write to. This was an aesthetic decision; the code could have been written more like the C++ version in that regard.)
In Go, functions are always full closures, the equivalent of `[&]` in C++11. An important difference is that it is invalid in C++11 for a closure to reference a variable whose scope has gone away (as may be caused by an <a href='http://en.wikipedia.org/wiki/Funarg_problem'>upward funarg</a>—a function that returns a lambda that references local variables). In Go, this is perfectly valid.
<h2>Concurrency</h2>
Like C++11's `std::thread`, Go permits starting new threads of execution that run concurrently in a shared address space. These are called _goroutines_ and are spawned using the `go` statement. While typical `std::thread` implementations launch heavyweight, operating-system threads, goroutines are implemented as lightweight, user-level threads that are multiplexed among multiple operating-system threads. Consequently, goroutines are (intended to be) cheap and can be used liberally throughout a program.
```go
func server(i int) {
for {
fmt.Print(i)
time.Sleep(10 * time.Second)
}
}
go server(1)
go server(2)
```
(Note that the `for` statement in the `server` function is equivalent to a C++ `while (true)` loop.)
Function literals (which Go implements as closures) can be useful with the `go` statement.
```go
var g int
go func(i int) {
s := 0
for j := 0; j < i; j++ {
s += j
}
g = s
}(1000) // Passes argument 1000 to the function literal.
```
Like C++11, but unlike prior versions of C++, Go defines a <a href='https://go.dev/ref/mem'>memory model</a> for unsynchronized accesses to memory. Although Go provides an analogue of `std::mutex` in its ` sync ` package, this is not the normal way to implement inter-thread communication and synchronization in Go programs. Instead, Go threads more typically communicate by message passing, which is a fundamentally different approach from locks and barriers. The Go mantra for this subject is,
> Do not communicate by sharing memory; instead, share memory by communicating.
That is, _channels_ are used to communicate among goroutines. Values of any type (including other channels!) can be
sent over a channel. Channels can be unbuffered or buffered (using a buffer length specified at channel-construction time).
Channels are first-class values; they can be stored in variables and passed to and from functions like any other value. (When supplied to
functions, channels are passed by reference.) Channels are also typed: a `chan int` is different from a `chan string`.
Because they are so widely used in Go programs, channels are (intended to be) efficient and cheap. To send a value on a channel, use `<-` as a binary operator. To receive a value on a channel, use `<-` as a unary operator. Channels can be shared among multiple senders and multiple receivers and guarantee that each value sent is received by at most one receiver.
Here is an example of using a manager function to control access to a single value.
```go
type Cmd struct {
Get bool
Val int
}
func Manager(ch chan Cmd) {
val := 0
for {
c := <-ch
if c.Get {
c.Val = val
ch <- c
} else {
val = c.Val
}
}
}
```
In that example the same channel is used for input and output. This is incorrect if there are multiple goroutines communicating with the manager at once: a goroutine waiting for a response from the manager might receive a request from another goroutine instead. A solution is to pass in a channel.
```go
type Cmd2 struct {
Get bool
Val int
Ch chan<- int
}
func Manager2(ch <-chan Cmd2) {
val := 0
for {
c := <-ch
if c.Get {
c.Ch <- val
} else {
val = c.Val
}
}
}
```
To use `Manager2`, given a channel to it:
```go
func getFromManagedChannel(ch chan<- Cmd2) int {
myCh := make(chan int)
c := Cmd2{true, 0, myCh} // Composite literal syntax.
ch <- c
return <-myCh
}
func main() {
ch := make(chan Cmd2)
go Manager2(ch)
// ... some code ...
currentValue := getFromManagedChannel(ch)
// ... some more code...
}
```

36
GoGenerateTools.md

@ -1,36 +1,4 @@
[`go generate`](https://go.dev/blog/generate) is only useful if you have tools to use it with! Here is an incomplete list of useful tools that generate code. The Go wiki on GitHub has moved to go.dev (#61940).
* [goyacc](https://pkg.go.dev/golang.org/x/tools/cmd/goyacc) – Yacc for Go.
* [stringer](https://pkg.go.dev/golang.org/x/tools/cmd/stringer) – Implements `fmt.Stringer` interface for enums.
* [gostringer](https://pkg.go.dev/github.com/sourcegraph/gostringer) – Implements `fmt.GoStringer` interface for enums.
* [jsonenums](https://github.com/campoy/jsonenums) – Implements `json.Marshaler` and `json.Unmarshaler` interfaces for enums.
* [go-syncmap](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-syncmap) - Generates Go code using a package as a generic template for `sync.Map`.
* [go-syncpool](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-syncpool) - Generates Go code using a package as a generic template for `sync.Pool`.
* [go-atomicvalue](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-atomicvalue) - Generates Go code using a package as a generic template for `atomic.Value`.
* [go-nulljson](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-nulljson) - Generates Go code using a package as a generic template that implements `database/sql.Scanner` and `database/sql/driver.Valuer`.
* [go-enum](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-enum) - Generates Go code using a package as a generic template which implements interface `fmt.Stringer` | `binary` | `json` | `text` | `sql` | `yaml` for enums.
* [enumer](https://pkg.go.dev/github.com/alvaroloes/enumer) - Generates Go code that convert Go enum to/from strings.
* [go-import](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-import) — Performs auto import of non go files.
* [gojson](https://github.com/ChimeraCoder/gojson) - Generates go struct definitions from example json documents.
* [vfsgen](https://github.com/shurcooL/vfsgen) - Generates a vfsdata.go file that statically implements the given virtual filesystem.
* [goreuse](https://github.com/dc0d/goreuse) - Generates Go code using a package as a generic template by replacing definitions.
* [embedfiles](https://4d63.com/embedfiles) - Embeds files into Go code.
* [ragel](https://www.colm.net/open-source/ragel/) - State machine compiler
* [peachpy](https://github.com/Maratyszcza/PeachPy) - x86-64 assembler embedded in Python, generates Go assembly
* [bundle](https://pkg.go.dev/golang.org/x/tools/cmd/bundle) - Bundle creates a single-source-file version of a source package suitable for inclusion in a particular target package.
* [msgp](https://github.com/tinylib/msgp) - A Go code generator for MessagePack
* [protobuf](https://github.com/golang/protobuf) - protobuf
* [thriftrw](https://github.com/thriftrw/thriftrw-go) - thrift
* [gogen-avro](https://github.com/actgardner/gogen-avro) - avro
* [swagger-gen-types](https://github.com/dnephin/swagger-gen-types) - go types from swagger specifications
* [avo](https://github.com/mmcloughlin/avo) - generate assembly code with Go
* [Wire](https://github.com/google/wire) - Compile-time Dependency Injection for Go
* [sumgen](https://github.com/smasher164/sumgen) - generate interface method implementations from sum-type declarations
* [interface-extractor](https://github.com/urandom/interface-extractor) - generates an interface of a desired type, with only methods used within the package.
* [deep-copy](https://github.com/globusdigital/deep-copy) - creates a deep copy method for the given types.
* [libfsm](https://github.com/katef/libfsm) - fsm toolkit supporting (among others) Go and Go-flavored amd64 assembly for matching regexps
* [re2c](https://re2c.org/index.html) - lexer generator for C, C++ and Go
* [re2dfa](https://gitlab.com/opennota/re2dfa) - Transform regular expressions into finite state machines and output Go source code
* [pigeon](https://github.com/mna/pigeon) - a PEG parser generator for Go
Try <https://go.dev/wiki/GoGenerateTools> or <https://go.dev/wiki/>.

26
GoGetProxyConfig.md

@ -1,26 +1,4 @@
Setting proxies for source code used by ` go get ` (listed in GoGetTools) The Go wiki on GitHub has moved to go.dev (#61940).
## Windows command line Try <https://go.dev/wiki/GoGetProxyConfig> or <https://go.dev/wiki/>.
```
$ set http_proxy=http://proxy.example.com:port
```
## git
```
$ git config [--global] http.proxy http://proxy.example.com:port
```
## mercurial
Edit ` ~/.hgrc ` and add the following:
```
[http_proxy]
host=proxy.example.com:port
```
## svn
Edit ` ~/.subversion/servers ` and add the following:
```
[Global]
http-proxy-host=proxy.example.com
http-proxy-port=xxxx
```

12
GoGetTools.md

@ -1,12 +1,4 @@
# Installing Version Control Tools for ` go get ` The Go wiki on GitHub has moved to go.dev (#61940).
The ` go get ` fetching of source code is done by using one of the following tools expected to be found on your system: Try <https://go.dev/wiki/GoGetTools> or <https://go.dev/wiki/>.
* **svn** - Subversion, download at: http://subversion.apache.org/packages.html
* **hg** - Mercurial, download at https://www.mercurial-scm.org/downloads
* **git** - Git, download at http://git-scm.com/downloads
* **bzr** - Bazaar, download at http://wiki.bazaar.canonical.com/Download
For example, **git** is used for Github, **hg** is used for Bitbucket, etc.
Refer [GoGetProxyConfig](GoGetProxyConfig) for setting proxies for these tools.

96
GoMips.md

@ -1,96 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
Go programs can be cross-compiled e.g., on x86/x86\_64 build systems to run on MIPS target machines. Try <https://go.dev/wiki/GoMips> or <https://go.dev/wiki/>.
# Supported architectures
Go supports the following MIPS architectural families. (Are there more?)
| **Architecture** | **Status** | **GOMIPS value** | **GOARCH value** |
|:-----------------|:-----------|:----------------|:-----------------|
| Big endian (e.g., ar71xx) | supported | GOMIPS=softfloat| GOARCH=mips |
| Little endian | supported | n/a | GOARCH=mipsle |
# Supported operating systems
* MIPS on Linux. Tested with an ar71xx based OpenWrt device.
# Recommended Go version
The tested version for running Go on MIPS systems is Go 1.13.
# Tips and tricks
## Building for ar71xx OpenWrt
This builds a Go program, strips unneeded strings and symbols to minimize its size, and compresses it to further minimize its size:
```
env GOOS=linux GOARCH=mips GOMIPS=softfloat go build -trimpath -ldflags="-s -w" 'server.go'
upx -9 server
```
# Success stories
MIPS hardware comes in a myriad of shapes and sizes. If you've had a success story building and running Go on your Arm system, please detail your results here.
## D-Link DIR-505 Mobile Companion
Architecture: ar71xx
Operating System: OpenWrt
The D-Link DIR-505 Mobile Companion comes with an Atheros AR1311 processor, 8 MB flash and 64 MB RAM. This space is limited but allows us to load Go applications, e.g., from network into `/tmpfs` and execute them from there.
Further information about the device can be found at https://openwrt.org/toh/d-link/dir-505.
## Teltonika
### RUT955
Architecture: ar9344
Operating System: RutOS (based on OpenWrt)
The Teltonika RUT955 has a Atheros Wasp MIPS 74Kc CPU running at 550 MHz with 16 MB flash 128 MB RAM. Inbuilt flash will be insufficient for most applications but a Micro SD or USB stick can be added (running application directly from SD was unreliable but copying to /tmpfs and running from there works OK). The inbuilt IO, GPS etc can be accessed via Modbus TCP and the RS232/RS485 ports worked without issue. Tested with Go 1.14.6, 1.15.3 & 1.21.1 (GOARCH=mips, GOMIPS=softfloat).
Further information about the device can be found at https://teltonika-networks.com/product/rut955/.
### RUT956
Architecture: MediaTek MT7628AN ver:1 eco:2
Operating System: RutOS (based on OpenWrt)
The Teltonika RUT956 has a Mediatek MIPS 24KEc CPU running at 580 MHz with 16 MB flash 128 MB RAM. Inbuilt flash will be insufficient for most applications but a USB stick can be added. The inbuilt IO, GPS etc can be accessed via Modbus TCP and the RS232/RS485 ports worked without issue. Tested with Go 1.21.1 (GOARCH=mipsle, GOMIPS=softfloat). Note that `illegal instruction` is output if `GOMIPS` is not set.
Further information about the device can be found at https://teltonika-networks.com/product/rut956/.
## TP-Link Archer A6 WiFi Router
Architecture: ath79 (same hardware as ar71xx, but with native kernel support)
Operating System: OpenWrt
The TP-Link Archer A6 comes with an Atheros QCA9563 MIPS 24K classic processor, 16 MB flash, and 128 MB RAM. Flash storage is limited and no USB ports are available for storage expansion, so programs are loaded from the network into /tmpfs and executed.
Further information about the device can be found at https://openwrt.org/toh/hwdata/tp-link/tp-link_archer_a6_us_tw.
## Belkin F7D7302 WiFi Router
Architecture: mipsel_74kc
Operating System: DD-WRT
The Belkin F7D7302 comes with a Broadcom BCM4716 little-endian MIPS 74K classic processor, 8 MB flash, and 64 MB RAM. Flash storage is severely limited, but there is a USB port available so programs can be loaded onto a flash drive and executed.
Further information about the device can be found at https://openwrt.org/toh/belkin/f7d3302.
## AVM FRITZ!Box 7362 SL
System type: xRX200 rev 1.2 \
CPU model: MIPS 34Kc V5.6
Operating System: OpenWrt 21
Further information about the device can be found at https://openwrt.org/toh/avm/avm_7362_sl.

59
GoStrings.md

@ -1,59 +1,4 @@
Strings are **not** required to be UTF-8. Go source code **is** required The Go wiki on GitHub has moved to go.dev (#61940).
to be UTF-8. There is a complex path between the two.
In short, there are three kinds of strings. They are: Try <https://go.dev/wiki/GoStrings> or <https://go.dev/wiki/>.
1. the substring of the source that lexes into a string literal.
1. a string literal.
1. a value of type string.
Only the first is required to be UTF-8. The second is required to be
written in UTF-8, but its contents are interpreted various ways
and may encode arbitrary bytes. The third can contain any bytes at
all.
Try this on:
```
var s string = "\xFF語"
```
Source substring: ` "\xFF語" `, UTF-8 encoded. The data:
```
22
5c
78
46
46
e8
aa
9e
22
```
String literal: ` \xFF語 ` (between the quotes). The data:
```
5c
78
46
46
e8
aa
9e
```
The string value (unprintable; this is a UTF-8 stream). The data:
```
ff
e8
aa
9e
```
And for record, the characters (code points):
```
<erroneous byte FF, will appear as U+FFFD if you range over the string value>
語 U+8a9e
```

391
GoTalks.md

@ -1,391 +1,4 @@
# Go talks The Go wiki on GitHub has moved to go.dev (#61940).
Check out http://talks.golang.org for presentations for some of the talks. For a comprehensive, curated and searchable index, try [GopherVids](http://gophervids.appspot.com/) from Damian Gryski. Try <https://go.dev/wiki/GoTalks> or <https://go.dev/wiki/>.
# Official
## Introductory Talks
An introduction to Go.
### Russ Cox's Tour of Go
[[video and discussion](http://research.swtch.com/gotour)]
Three things that make Go fast, fun, and productive:interfaces, reflection, and concurrency. Builds a toy web crawler to demonstrate these.
### Go: a simple programming environment
[[video](http://vimeo.com/53221558)]
[[another video](http://vimeo.com/69237265)]
[[slides](http://talks.golang.org/2012/simple.slide)]
Go is a general-purpose language that bridges the gap between efficient statically typed languages and productive dynamic language. But it’s not just the language that makes Go special – Go has broad and consistent standard libraries and powerful but simple tools.
This talk gives an introduction to Go, followed by a tour of some real programs that demonstrate the power, scope, and simplicity of the Go programming environment.
### Get Started with Go
[[video](http://www.youtube.com/watch?v=2KmHtgtEZ1s)]
Get a feel for the language and its standard libraries and tools in this session, where we go through installing Go and writing some simple but useful
programs.
### Go Programming
[[video](http://www.youtube.com/watch?v=jgVhBThJdXc)]
[[code](http://talks.golang.org/2010/io/)]
A presentation delivered by Rob Pike and Russ Cox at Google I/O 2010. It
illustrates how programming in Go differs from other languages through a set of
examples demonstrating features particular to Go. These include concurrency,
embedded types, methods on any type, and program construction using interfaces.
### The Go Tech Talk
[[video](http://www.youtube.com/watch?v=rKnDgT73v8s)]
[[slides](http://talks.golang.org/2009/go_talk-20091030.pdf)]
An hour-long talk delivered by Rob Pike at Google in October 2009.
The language's first public introduction. The language has changed since it was made,
but it's still a good introduction.
## Development in Go
### Writing Web Apps in Go
[[video](http://www.youtube.com/watch?v=-i0hat7pdpk)]
[[slides](http://talks.golang.org/2011/Writing_Web_Apps_in_Go.pdf)]
A talk by Rob Pike and Andrew Gerrand presented at Google I/O 2011.
It walks through the construction and deployment of a simple web application
and unveils the [Go runtime for App Engine](https://go.dev/blog/2011/05/go-and-google-app-engine.html).
### Real World Go
[[video](http://www.youtube.com/watch?v=7QDVRowyUQA)]
[[slides](http://talks.golang.org/2011/Real_World_Go.pdf)]
A talk by Andrew Gerrand presented at Google I/O Bootcamp 2011.
It gives a broad overview of Go's type system and concurrency model
and provides four examples of Go programs that solve real problems.
### Building Integrated Apps on Google's Cloud Platform
[[video](http://www.youtube.com/watch?v=Mo1YKpIF1PQ)]
A talk by Andrew Gerrand presented at Google Developer Day Japan 2011.
It discusses the development of a web application that runs on Google
App Engine and renders raytraced that it stores on Google Cloud Storage.
### High Performance Apps with Go on App Engine
Google I/O, May 2013
[[video](http://www.youtube.com/watch?v=fc25ihfXhbg)]
[[slides](http://talks.golang.org/2013/highperf.slide)]
### Practical Go Programming
[[video](http://www.youtube.com/watch?v=2-pPAvqyluI)]
[[slides](http://wh3rd.net/practical-go)]
[[code](http://github.com/nf/goto)]
This talk presents the development of a complete web application in Go.
It looks at design, storage, concurrency, and scaling issues in detail, using
the simple example of an URL shortening service.
### Lexical Scanning in Go
[[video](http://www.youtube.com/watch?v=HxaD_trXwRE)]
This GTUG talk by Rob Pike discusses the detailed design of a lexical scanner that uses Go's
features in expressive combinations. (The discussion near the end about avoiding goroutines
at initialization is obsolete: Go 1 allows goroutines in init functions so the extra complexity
is unnecessary.)
### Go in Production
Google I/O, June 2012
[[video](http://www.youtube.com/watch?v=kKQLhGZVN4A)]
Since Go's release in 2009 many companies (besides Google, of course) have used the language to build cool stuff. In this session programmers from several companies will share their first-hand experience using Go in production environments.
### Go: code that grows with grace
[[video](http://vimeo.com/53221560)]
[[slides](http://talks.golang.org/2012/chat.slide)]
One of the Go Programming Language’s key design goals is code adaptability; that it should be easy to take a simple design and build upon it in a clean and natural way. In this talk I describe a simple “chat roulette” server that matches pairs of incoming TCP connections, and then use Go’s concurrency mechanisms, interfaces, and standard library to extend it with a web interface and other features. Although the function of the program changes dramatically, the inherent flexibility of Go allows the original design to remain intact as it grows.
### Implementing a bignum calculator
[[video](https://www.youtube.com/watch?v=PXoG0WX0r_E)]
[[slides](http://go-talks.appspot.com/github.com/robpike/ivy/talks/ivy.slide)]
Rob Pike describes his interpreter for an APL-like calculator language.
### Go in Go
[[video](https://www.youtube.com/watch?v=cF1zJYkBW4A)]
[[slides](https://talks.golang.org/2015/gogo.slide)]
Rob Pike speaks on moving the Go toolchain from C to Go
## Concurrency in Go
### Go concurrency patterns
Google I/O, June 2012
[[video](http://www.youtube.com/watch?v=f6kdp27TYZs)]
### Advanced Concurrency Patterns
[[video](https://www.youtube.com/watch?v=QDDwwePbDtw)]
[[slides](http://talks.golang.org/2013/advconc.slide)]
Google I/0, May 2013
Concurrency is the key to designing high performance network services. This talk expands on last year's popular Go Concurrency Patterns talk to dive deeper into Go's concurrency primitives, and see how tricky concurrency problems can be solved gracefully with simple Go code.
## Design of Go
### The Expressiveness Of Go
[[slides](http://talks.golang.org/2010/ExpressivenessOfGo-2010.pdf)]
A discussion of the qualities that make Go an expressive and comprehensible
language. The talk was presented by Rob Pike at JAOO 2010.
The recording of the event was lost due to a hardware error.
### Another Go at Language Design
[[video](http://sydney.edu.au/engineering/it/videos/seminar_pike) from Sydney University]
[[slides](http://assets.en.oreilly.com/1/event/45/Another%20Go%20at%20Language%20Design%20Presentation.pdf)]
A tour, with some background, of the major features of Go, intended for
an audience new to the language. The talk was presented at OSCON 2010.
This talk was also delivered at Sydney University in September 2010.
### Go Emerging Languages Conference Talk
[[video](http://confreaks.com/videos/115-elcamp2010-go)]
[[slides](http://assets.en.oreilly.com/1/event/45/Go%20Presentation.pdf)]
Rob Pike's Emerging Languages Conference presentation delivered in July 2010. Talk abstract:
> Go’s approach to concurrency differs from that of many languages, even those
> (such as Erlang) that make concurrency central, yet it has deep roots. The path
> from Hoare’s 1978 paper to Go provides insight into how and why Go works as it
> does.
## The State of Go
### June 2014
[[video](https://www.youtube.com/watch?v=0KF44QtoByk)]
[[slides](https://talks.golang.org/2014/state-of-go.slide)]
### February 2015
[[video](https://www.youtube.com/watch?v=Kd8EqTvW5EQ)]
[[slides](https://talks.golang.org/2015/state-of-go.slide)]
### May 2015
[[video](https://www.youtube.com/watch?v=S9Bu6fZnLGM)]
[[slides](https://talks.golang.org/2015/state-of-go-may.slide)]
## Miscellaneous
### The Go frontend for GCC
[[paper](http://talks.golang.org/2010/gofrontend-gcc-summit-2010.pdf)]
A description of the Go language frontend for gcc.
Ian Lance Taylor's paper delivered at the GCC Summit 2010.
### The Go Promo Video
[[video](http://www.youtube.com/watch?v=wwoWei-GAPo)]
A short promotional video featuring Russ Cox demonstrating Go's fast compiler.
### Meet the Go team
Google I/O, June 2012
[[video](http://www.youtube.com/watch?v=sln-gJaURzk)]
A panel discussion with David Symonds, Robert Griesemer, Rob Pike, Ken Thompson, Andrew Gerrand, and Brad Fitzpatrick.
### Fireside Chat with Go team
Google I/0, May 2013
[[video](http://www.youtube.com/watch?v=p9VUCp98ay4)]
A fireside chat with Andrew Gerrand, Brad Fitzpatrick, David Symonds, Ian Lance Taylor, Nigel Tao, Rob Pike, Robert Griesemer, Sameer Ajmani.
### The State of the Gopher
[[video](https://www.youtube.com/watch?v=4KFTacxqkcQ)]
[[slides](https://talks.golang.org/2014/state-of-the-gopher.slide)]
# Unofficial
Talks by members of the community.
### Let's Go, or introduction to Go
[[video (starting at 14:35)](http://live.digicast.ru/view/1582)]
[[slides](http://talks.godoc.org/github.com/AlekSi/LetsGo/lets-go.slide)]
[[source](https://github.com/AlekSi/LetsGo)]
This talk gives an introduction to Go in Russian.
### What are Go modules and how do I use them?
_[Paul Jolly](https://twitter.com/_myitcv) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/6MbIzJmLz6Q)]
[[slides](https://talks.godoc.org/github.com/myitcv/talks/2018-08-15-glug-modules/main.slide#1)]
### What else is in Go 1.11
_[Daniel Martì](https://twitter.com/mvdan_) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/mQYjjVCGVJ8)]
[[slides](https://talks.godoc.org/github.com/mvdan/talks/2018/go1.11.slide#1)]
Sneak peak at the Go 1.11 release
### Get Going with WebAssembly
_[Johan Brandhorst](https://twitter.com/JohanBrandhorst) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/iTrx0BbUXI4)]
[[slides](https://talks.godoc.org/github.com/johanbrandhorst/presentations/wasm-lightning/wasm.slide#1)]
[[code wasm](https://github.com/johanbrandhorst/wasm-experiments)]
[[code grpc](https://github.com/johanbrandhorst/grpcweb-wasm-example)]
In this talk, Johan introduces you to the WebAssembly port in Go 1.11 and how it can help when dealing with JavaScript madness :)
### Go and Mongo - and how it's changing
_[DJ Walker-Morgan](https://twitter.com/codepope) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/W22tZ5p3aDk)]
[[slides](https://github.com/codepope/talks/blob/master/GoAndMongo.pdf)]
### Building a simple concurrency teaching language with Go
_[Nicholas Ng](https://twitter.com/nicholascwng) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/7cEp98y6WCs)]
[[slides](https://talks.godoc.org/github.com/nickng/londongophers-aug18/londongophers-aug18.slide#1)]
In this talk Nicholas presents the design and implementation of a simple language designed for teaching concurrency theory (process calculi), implemented in Go. He covers some of Go's static analysis tools used in the implementation and show how you can use them too!
### Introducing Remoto
_[Mat Ryer](https://twitter.com/matryer) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/dhbq7R7h-C0)]
Mat shares the first glimpse of a new project that aims to make building RPC services easy. gRPC isn’t good for clients (especially web), and RESTful designs sometimes lead to confusing APIs. Remoto lets you define your service with a Go interface, and generate everything you need to build and consume the service.
### Go Swagger
_[Simone Trubian](https://twitter.com/simone_trubian) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/PUejMR82RgU)]
Simone gives an overview of the Go Swagger command line tool and briefly explain how he used it to improve productivity in designing REST API's.
### ORMs in Go
_Renato Serra at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/0XW6wI2FnPA)]
Renato explains where ORMs can help, what the options were and what it's been like to use one.
### Unused parameters in Go code
_[Daniel Martì](https://twitter.com/mvdan_) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/VW5jI6V_Y2c)]
[[slides](https://talks.godoc.org/github.com/mvdan/talks/2018/unparam.slide#1)]
Daniel talks about how to use SSA and callgraphs to write powerful code analysis tools. In particular, he demonstrates how to detect unused parameters in functions.
### Lies, Damn Lies, and Benchmarks
_Amnon at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/YDPKUJndhw4)]
[[slides](https://talks.godoc.org/github.com/amnonbc/talks/lies.slide#1)]
Amnon discusses why microbenchmarks can be misleading for optimising real world systems, why data layout is often more significant than code structure, and how Go can help us in the quest for performance.
### A debugger from scratch
_[Liz Rice](https://twitter.com/LizRice) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/tZ5PUKbGjO4)]
[[slides](https://speakerdeck.com/lizrice/debuggers-from-scratch)]
[[code](https://github.com/lizrice/debugger-from-scratch)]
Liz explains how a debugger works by building one in a few lines of Go. This includes mapping between Go source code and the machine code instructions it compiles to, and using the ptrace system call to set break points and examine and modify the running process.
### Fast Fractal Fun With SDL
_[Sue Spence](https://twitter.com/virtualsue) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/eTjL3grAYAM)]
[[slides](https://gitlab.com/virtualsue/sdl-fractal/blob/master/Fast%20Fractal%20Fun.pdf)]
[[code](https://gitlab.com/virtualsue/sdl-fractal)]
Go programs which create images such as the Mandelbrot & Julia sets often output an image file. I will show how to use Go bindings for the Simple Directmedia Layer library to output them on a display device instead.
### Concurrency: a Journey from Ruby to Go
_[Mathilda Thompson](https://twitter.com/mathildathompso) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/mK3r5PDED-0)]
### Go in a Polyglot Environment
_[Kevin McKelvin](https://twitter.com/kmckelvin) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/kWAxBhsEayk)]
In this talk Kevin goes through his experience of adopting Go, moving to a polyglot environment, successes and challenges, and how Go fits into his company's overall architecture and strategy.
### Delivering Go Services
_[Zak Knill](https://twitter.com/zakknill) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/pRdfJTuGxEw)]
Delivering Go Services: After introducing Go to your company, and deploying your first go service. What are the next steps? This talk focuses on some of the things that come next, touching on the fabled "New service to prod in X (10, 20, 30) mins", as well as some gotchas along the way.
### Go-ing Lambda
_[David Blooman](https://twitter.com/dblooman) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/BBiIr19JOo4)]
Go-ing Lambda - A year in production: How we(FundApps) used Go in lambda functions to build a service for importing/scraping/parsing data for financial services to build API's on top of. Tips and tricks of lambda functions in Go, limitations, performance and using the Apex framework.
### The RED method
_[Tom Wilkie](https://twitter.com/tom_wilkie) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/rc3V-k-JYAo)]
We'll also have a section dedicated to those of you who are hiring or looking to get hired (if we'll miss it like last time, please don't be afraid to remind us).
### Abusing Go’s net package for fun and profit
_[Michał Witkowski](https://twitter.com/MWitkow) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/JDjHFmke0ZI)]
This talks into the details of how Go’s composition-based philosophy, as applied to the net package, can be creatively leveraged to beautiful and useful hacks that significantly augment the functionality of the stack. We’ll explore the net.Conn, and how one can (ab)use them in creative ways. We’ll take a peek into net/http, and explore how the http.Handler and http.Roundtripper interfaces can be creatively appropriated to build useful middleware. We’ll then dig even deeper into the net/http internals and how they related tls.Conn and x/net/http2, to understand how they work, and armed with that knowledge we’ll demonstrate some of our most beautiful hacks.
### 2018's stringer
_[Daniel Martì](https://twitter.com/mvdan_) at [**LondonGophers**](https://twitter.com/LondonGophers)_
[[video](https://youtu.be/IyVEW19IkXE)]
[[slides](https://talks.godoc.org/github.com/mvdan/talks/2018/stringer.slide)]
2018's stringer - a demonstration of new features you likely haven't heard of.

234
GoUserGroups.md

@ -1,234 +1,4 @@
# Africa The Go wiki on GitHub has moved to go.dev (#61940).
* [Golang Buea](https://meetup.com/Docker-Buea) - Buea, Cameroon
* [Go Egypt](https://web.facebook.com/groups/563213043835298/) - Cairo, Egypt.
* [Go Cape Town](http://www.meetup.com/gocapetown/) - Cape Town.
* [golang-dakar](https://plus.google.com/u/0/communities/116552609416802012105) Dakar (Sénégal)
* [Joburg Golang Group](http://www.meetup.com/Joburg-Golang-Group/) - Johannesburg
* [angolang](https://plus.google.com/u/0/b/112645881964422842789/communities/111727796450195570970) Luanda, Angola
* [Golang Nigeria](https://www.meetup.com/GolangNigeria/) - Lagos, Nigeria
* [Golang Abuja](https://www.meetup.com/golang-abuja/) - Abuja, Nigeria
* [Gophers Mauritius](https://www.gophers.mu/) - Mauritius
* [cyberstorm.mu](https://cyberstorm.mu/) - Mauritius
* [Tunisian Gophers](https://www.facebook.com/TunisiaGolangcommunity/) - Tunisia
* [Nairobi Gophers](https://www.meetup.com/nairobi-gophers/) - Nairobi, Kenya
Try <https://go.dev/wiki/GoUserGroups> or <https://go.dev/wiki/>.
# Asia
* [Golang ِArabic Community](https://www.facebook.com/groups/111860102810970/)
* [Golang Azerbaijan](https://www.facebook.com/groups/852343094928521/) - Baku, Azerbaijan 🇦🇿
* [Golang Iraq](https://www.facebook.com/groups/go.iraq/) - Iraq
* [Indonesia](https://golang-id.org) - Indonesia
* [GoJakarta](https://gophers.id/GoJakarta) - Jakarta, Indonesia.
* [Golang Surabaya](https://github.com/golangSurabaya) - Surabaya, Indonesia.
- Persia
* [Telegram Iranian Group](https://t.me/GolangFarsi) - Iran
* [devheroes Iran](https://devheroes.club/c/go) - Iran
- India
* [Golang New Delhi](https://www.meetup.com/GolangNewDelhi) - New Delhi, India.
* [Golang Bangalore](https://www.meetup.com/Golang-Bangalore) - Bangalore, India.
* [Golang Chennai](http://www.meetup.com/Chennai-golang-Meetup/) - Chennai, India
* [Golang Pune](https://www.meetup.com/Golang-Pune/) - Pune, India.
* [Golang Ahmedabad](https://www.meetup.com/Golang-Ahmedabad) - Ahmedabad, India.
* [Golang Kolkata](https://www.facebook.com/groups/125791539385850) - Kolkata, India.
- Japan
* [Gophers Japan](https://gocon.jp/) - Japan.
* [golang.tokyo](https://golangtokyo.github.io/) - Tokyo, Japan.
* [Akiba.go](https://akihabarago.connpass.com/) - Tokyo, Japan.
* [Women Who Go Tokyo](https://web.womenwhogo.tokyo/) - Tokyo, Japan.
* [kyoto.go](https://kyotogo.connpass.com/) - Kyoto, Japan.
* [Umeda.go](https://umedago.connpass.com/) - Osaka, Japan.
* [Sendai.go](https://techplay.jp/community/sendaigo) - Miyagi, Japan.
* [Fukuoka.go](https://fukuokago.dev/) - Fukuoka, Japan.
* [Okayama.go](https://okayamago.connpass.com/) - Okayama, Japan.
* [nagoya.go](https://nagoyago.connpass.com/) - Aichi, Japan.
* [Shizuoka.go](https://shizuoka-go.connpass.com/) - Shizuoka, Japan.
* [Golang札幌](https://golang-sapporo.connpass.com/) - Hokkaido, Japan.
* [Gopher道場](https://gopherdojo.org/) - Japan.
* [Go Language Specification 輪読会](https://gospecreading.connpass.com/) - Japan.
* [ゴリラ.Go](https://gorilla-go.connpass.com/) - Japan.
- Other
* [Golang China](http://groups.google.com/group/golang-china) - China.
* [Golang Korea](https://www.facebook.com/groups/golangko/about/) - Korea.
* [Golang Vietnam](https://www.facebook.com/golang.org.vn) - [github](https://github.com/golang-vietnam) - Vietnam
* [Golang Taiwan](http://golang.tw) - Taiwan.
* [Golang Israel](http://www.meetup.com/Go-Israel) - Israel.
* [Singapore Gophers](https://www.facebook.com/groups/golang.sg/) - [Meetup](http://www.meetup.com/golangsg/) - Singapore
* [Golang UAE](https://plus.google.com/communities/114845275110994424259) - UAE.
* [Golang Malaysia](https://www.facebook.com/groups/mygolang/) - [Homepage](https://golang.my) - Malaysia.
* [Go Developers Network Bangladesh](https://www.facebook.com/groups/godevnet/) - Bangladesh.
* [Golang Pakistan](https://www.facebook.com/gopherpk/) - [Facebook Group](https://www.facebook.com/groups/2547735885480597) - Pakistan
# Europe
* [Bärner Go Meetup](https://www.meetup.com/Berner-Go-Meetup/) - Berne, Switzerland
* [Budapest Go Meetup](https://www.meetup.com/go-budapest/) - Budapest, Hungary
* [Athens Gophers](https://www.meetup.com/Athens-Gophers/) - Athens, Greece.
* [Golang Türkiye](https://www.facebook.com/groups/GolangTurkiye) - Istanbul, Turkey.
* [Gophers Aachen](https://www.meetup.com/Gophers-Aachen/) - Aachen, Germany.
* [Amsterdam, NL](http://www.meetup.com/golang-amsterdam/)
* [Belarus](http://gophers.by/) - Belarus.
* [Belfast Gophers](https://www.meetup.com/Belfast-Gophers/) - Belfast, UK.
* [Barcelona](http://golangbcn.org) - Barcelona, Catalunya, Spain.
* [Brno Golang](http://www.meetup.com/Golang-Brno/) - Brno, the Czech Republic
* [Golang Prague](https://www.meetup.com/Prague-Golang-Meetup/) - Prague, Czech Republic.
* [Cambridge Gophers](http://www.meetup.com/Cambridge-Gophers/) - Cambridge, UK
* [Suffolk Gophers](https://suffolkgophers.github.io/) - Suffolk, UK
* [Stuttgart Gophers](https://www.meetup.com/Stuttgart-Gophers/) - Stuttgart, Germany.
* [GDG Berlin Golang](http://www.meetup.com/golang-users-berlin/) - Berlin, Germany.
* [Go-User-Group-Hamburg](http://www.meetup.com/Go-User-Group-Hamburg) - Hamburg, Germany.
* [Go-User-Group Rhein-Ruhr](https://www.meetup.com/Go-Usergroup-Rhein-Ruhr) - Rhine-Ruhr region, Germany.
* [Go Lithuania User Group](http://gophers.lt/) - Lithuania, Kaunas.
* [Go London User Group](http://www.meetup.com/Go-London-User-Group/) - London, UK.
* [ManGo The Manchester Go User Group](http://mango.computer/) - Manchester, UK.
* [Golang Dorset](https://www.meetup.com/Golang-Dorset/) - Bournemouth, UK.
* [Golang Bristol++](https://www.meetup.com/golang-bristol/) - Bristol, UK.
* [GoSheffield](https://www.meetup.com/GoSheffield/) - Sheffield, UK.
* [GoMAD](https://www.meetup.com/go-mad/) - Madrid, Spain
* [Go Valhalla](https://t.me/joinchat/AAAAAEJGQn7K_oRUBWaNng) - Valencia, Spain. 🇻🇳
* [Go Wales User Group](http://golang.cymru/) - Wales, UK.
* [Golang Москва](http://www.meetup.com/Golang-Moscow/) - Moscow, Russia.
* [Golang Питер](http://www.meetup.com/Golang-Peter/) - Saint Petersburg, Russia.
* [Golang Новосибирск](http://www.meetup.com/GolangNSK/) - Novosibirsk, Russia.
* [Golang Казань](https://www.meetup.com/Golang-Kazan/) - Kazan, Russia.
* [Go Yola](https://golang-yola.timepad.ru/) - Yoshkar-Ola, Russia.
* [Chisinau Golang Meetup](http://www.meetup.com/Chisinau-Golang-Meetup/) - Chisinau, Moldova
* [Munich Gophers](http://www.meetup.com/Munich-Gophers-Go-User-Group/) - Munich, Germany
* [Golang Paris](http://www.meetup.com/Golang-Paris) - Paris, France.
* [Golang Rennes](http://www.meetup.com/Golang-Rennes/) - Rennes, France.
* [Golang Lyon](http://www.meetup.com/fr-FR/Golang-Lyon/) - Lyon, France.
* [Golang Lille](http://www.meetup.com/Golang-Lille) - Lille, France.
* [Golang Marseille](https://www.meetup.com/Golang-Marseille/) - Marseille, France.
* [golang-pl](https://groups.google.com/forum/?fromgroups#!forum/golang-pl) - Poland.
* [Gophers Katowice](http://www.meetup.com/Gophers-Katowice) - Katowice, Poland.
* [Golang Warsaw](http://www.meetup.com/Golang-Warsaw) - Warsaw, Poland.
* [G.L.U.G. Wroclaw](http://www.meetup.com/GoLang-User-Group-Wroclaw/) - Wroclaw, Poland
* [Golang User Group Trójmiasto](https://www.meetup.com/Golang-User-Group-Trojmiasto/) - Gdańsk/Gdynia/Sopot, Poland
* [Go-Stockholm](http://www.meetup.com/Go-Stockholm/) - Stockholm, Sweden.
* [Go-Uppsala](http://www.meetup.com/Go-Uppsala/) - Uppsala, Sweden.
* [Go-Malmö](http://www.meetup.com/Go-Malmo/) - Malmö, Sweden.
* [golang-greece](https://groups.google.com/forum/#!forum/golang-greece) - Greece
* [GolangIT](http://golangit.github.io/) - Italy.
* [Go-Turkey](https://plus.google.com/communities/101920753066440157216) - Turkey.
* [Go Graz](http://gograz.org) - Graz, Austria
* [Meetup Belgium](http://www.meetup.com/Golang-Belgium/) - Belgium
* [Meetup Lausanne](http://www.meetup.com/Lausanne-golang-Meetup) - Lausanne, Switzerland
* [Meetup Zurich](http://www.meetup.com/Zurich-Gophers/) - Zurich, Switzerland
* [Meetup Frankfurt](http://www.meetup.com/Frankfurt-Gophers-Meetup/) - Frankfurt am Main, Germany
* [Go-ningen](http://www.meetup.com/Go-ningen/) - Groningen, The Netherlands
* [Golang Ljubljana](http://www.meetup.com/Slovenian-Go-lang-User-Group/) - Ljubljana, Slovenia
* [Go Euregio](https://plus.google.com/communities/116272759718686417490) - Maastricht, Netherlands; Liège/Hasselt, Belgium; Aachen, Germany
* [Ukrainian Golang User Group](http://www.meetup.com/uagolang/) - Kyiv, Ukraine
* [L'viv Golang Group](http://www.meetup.com/Lviv-Golang-Group/) - L'viv, Ukraine
* [Go SXB, Go!](http://www.meetup.com/fr-FR/Go-SXB-Go/) - Strasbourg, France
* [Hannover Gophers Meetup](http://www.meetup.com/de-DE/Hannover-Gophers-Meetup/) - Hannover, Germany
* [Golang Nürnberg](http://www.meetup.com/de-DE/Golang-Nuernberg/) - Nürnberg, Germany
* [Helsinki Gophers](http://www.meetup.com/Helsinki-Gophers/) - Helsinki, Finland
* [Golang Cologne](http://www.meetup.com/Golang-Cologne/) - Cologne/Bonn, Germany
* [Golang Vilnius](http://www.meetup.com/Vilnius-Golang/) - Vilnius, Lithuania
* [Meetup Surrey](http://www.meetup.com/Surrey-Go-User-Group-Meetup/) - Surrey, UK
* [Golang Zagreb](https://www.meetup.com/Golang-ZG/) - Zagreb, Croatia
* [Meetup Edinburgh](https://www.meetup.com/Edinburgh-Golang-meetup/) - Edinburgh, UK
* [Münster Gophers](https://www.meetup.com/de-DE/Munster-Gophers/) - Münster, Germany
* [Vienna.go - Vienna Go User Group](https://www.meetup.com/Vienna-go-Vienna-Go-User-Group/events/242583645/) - Vienna, Austria
* [Golang Bulgaria](https://www.meetup.com/Golang-Bulgaria/) - Sofia, Bulgaria 🇧🇬
* [Go Oslo User Group](https://www.meetup.com/Go-Oslo-User-Group/) - Oslo, Norway
* [Gophers Linz](https://www.meetup.com/Gophers-Linz/) - Linz, Austria
* [Golang Rotterdam](https://www.meetup.com/Golang-Rotterdam/) - Rotterdam, Netherlands
* [Leipzig Gophers](https://golangleipzig.space/) - Leipzig, Germany
* [Golang Estonia](https://www.meetup.com/Golang-Estonia/) - Estonia
# North America
## Canada
* [Edmonton Go Meetup](https://edmontongo.org/) - Edmonton AB, Canada.
* [vangophers](http://groups.google.com/group/vangophers) - Vancouver BC, Canada.
* [Go Vancouver](https://plus.google.com/u/0/communities/106063002572645508555) - Vancouver BC, Canada.
* [GolangVan meetup](http://www.meetup.com/golangvan/) - Vancouver BC, Canada.
* [GolangVan](http://golangvan.org/) - Vancouver BC, Canada.
* [GoTO](http://www.meetup.com/go-toronto) - Toronto ON, Canada.
* [Ottawa Go](http://www.meetup.com/Ottawa-Go-Meetup/) - Ottawa ON, Canada.
* [KW Go Developers](http://www.meetup.com/Golang-KW/) - Waterloo, ON, Canada.
* [Golang Montréal](https://golangmontreal.org/) - Montréal, QC
* [Golang Winnipeg](https://www.meetup.com/Golang-Wpg-Meetup/) - Winnipeg MB, Canada
## Dominican Republic
* [Golang Dominicana](https://www.facebook.com/groups/golangdominicana) - República Dominicana.
## Latin America
* [Golang-ES](https://www.facebook.com/groups/goenespanol) - Facebook Español-Latino.
* [Gophers LATAM](https://discord.com/invite/AEarh2kSvn) - Discord Español-Latino.
## Mexico
* [Golang - Go MX](https://www.facebook.com/groups/es.golang.mx) - All Mexico
* [GophersMX](https://www.meetup.com/es/GophersMX/) - Ciudad de México, México
* [Golang Monterrey](http://www.meetup.com/Golang-MTY/) - Monterrey, Mexico
* [Golang Guadalajara](https://www.meetup.com/es/Golang-Guadalajara/) - Guadalajara, México
## United States
* [Los-Angeles-Gophers](http://www.meetup.com/Los-Angeles-Gophers/) - Los Angeles CA, USA.
* [Westside GoLang Meetup](https://www.meetup.com/Westside-GoLang-Meetup/) - Los Angeles CA, USA.
* [OC Gophers](http://www.meetup.com/Orange-County-Gophers) - Orange County CA, USA.
* [SDGophers](http://www.meetup.com/sdgophers/) — San Diego CA, USA
* [GoSF](http://www.meetup.com/golangsf/) - San Francisco CA, USA.
* [GoSV](http://www.meetup.com/GolangSV/) - San Mateo CA, USA.
* [Boulder Gophers](https://www.meetup.com/Boulder-Gophers/) - Boulder CO, USA.
* [Denver Go Language User Group](http://www.meetup.com/Denver-Go-Language-User-Group/) - Denver CO, USA.
* [DTC Go Meetup](https://www.meetup.com/Denver-Go-Programming-Language-Meetup/) - Denver Tech Center CO, USA.
* [Go-Miami](http://www.meetup.com/Go-Miami/) - Miami FL, USA.
* [Orlando Go Users](https://www.meetup.com/OrlanGo/) - Orlando FL, USA
* [Go-Users-Group-Atlanta](http://www.meetup.com/Go-Users-Group-Atlanta/) - Atlanta GA, USA.
* [chicagolang](http://groups.google.com/group/chicagolang) - Chicago IL, USA.
* [Chicago Ultimate Golang](https://www.meetup.com/Chicago-Ultimate-Golang/) - Chicago IL, USA.
* [Boston Golang](http://bostongolang.org) - Boston MA, USA.
* [Framingham Go](https://www.meetup.com/Framingham-Golang-Meetup/) - Framingham MA, USA.
* [GoMN](http://www.meetup.com/golangmn/) - Minneapolis MN, USA.
* [Buffalo GoLang Meetup Group](https://www.meetup.com/Buffalo-GoLang-Meetup-Group/) - Buffalo NY, USA.
* [New York Go Language Meetup](http://www.meetup.com/golangny/) - New York NY, USA.
* [New Jersey Go Language Meetup](http://www.meetup.com/golangnj/) - New Jersey NY, USA.
* [Bowery Golang Meetup](https://www.meetup.com/Bowery-Go/) - New York NY, USA.
* [GoLangPhilly](http://www.meetup.com/GoLangPhilly/) - Philadelphia PA, USA.
* [GoLangPhoenix](http://www.meetup.com/Golang-Phoenix/) - Phoenix AZ, USA.
* [GoLangCleveland](https://www.golangcleveland.org/) - Cleveland OH, USA.
* [Cincinnati Golang Meetup](https://www.meetup.com/Cincinnati-Golang-Meetup/) - Cincinnati, OH, USA.
* [EUG-Go](http://www.meetup.com/EUG-Go/) - Eugene, OR, USA.
* [PDX-Go](http://www.meetup.com/PDX-Go/) - Portland, OR, USA.
* [GoLancaster](http://www.meetup.com/GoLancaster/) - Lancaster PA, USA.
* [ATX-Golang](http://www.meetup.com/atxgolang/) - Austin TX, USA.
* [GoDFW](http://www.meetup.com/GoCowboys/) - Dallas TX, USA.
* [Golang Houston](http://www.meetup.com/Golang-Houston/) - Houston TX, USA.
* [Utah Golang (#UTGO)](http://utahgolang.com/) - Salt Lake City UT, USA.
* [Golang-DC](http://www.meetup.com/Golang-DC/) - Arlington VA, USA.
* [Seattle Go Programmers](http://www.meetup.com/golang/) - Seattle WA, USA.
* [Go Charlotte Meetup](http://www.meetup.com/golangclt/) - Charlotte NC, USA
* [Triangle Golang](http://www.meetup.com/Triangle-Golang-Meetup/) - Raleigh NC, USA.
* [Las Vegas Go Meetup](http://www.meetup.com/Las-Vegas-Go-Meetup/) - Las Vegas NV, USA.
* [Ann Arbor Gophers](http://www.meetup.com/Ann-Arbor-Gophers/) - Ann Arbor MI, USA
* [Baltimore Metro Area Golang](http://baltimoregolang.org) - Baltimore MD, USA
* [Nashville Gophers](https://nashgo.org) - Nashville TN, USA
* [Omaha Gophers](https://www.meetup.com/omaha-gophers/) - Omaha NE, USA
* [St Louis Go Meetup](https://www.meetup.com/StL-Go/) - St Louis, MO, USA
# Oceania
* [Canberra Gophers](https://plus.google.com/u/1/communities/114036877112593565975) - Canberra, Australia.
* [golang-sydney](http://www.meetup.com/golang-syd/) - Sydney, Australia.
* [golang-nz](http://groups.google.com/group/golang-nz) - New Zealand.
* [Golang Wellington](https://www.meetup.com/wellington-golang/) - Wellington, New Zealand.
* [Melbourne-Go-Nuts](http://www.meetup.com/Melbourne-Go-Nuts) - Melbourne, Australia.
* [Brisbane Gophers](http://www.meetup.com/Brisbane-Golang-Meetup/) - Brisbane, Australia.
* [Honolulu Go Users](http://hnlgo.org/) - Oahu, Hawaii
# South America
* [Golang Brasil](https://www.meetup.com/pt-BR/golangbr/) - Brazil.
* [Golang Rio de Janeiro](https://www.meetup.com/pt-BR/Gophers-Rio) - Rio de Janeiro, Brazil.
* [Golang Recife](https://linktr.ee/golang_recife) - Recife, Pernambuco, Brazil.
* [Golang Argentina](http://www.meetup.com/es-ES/Golang-Argentina/) - Argentina.
* [Golang Medellín](http://www.meetup.com/Golang-Medellin/) - Colombia.
* [Golang Chile](https://groups.google.com/d/forum/golang-chile) - Chile.
* [Golang Panamá](https://groups.google.com/d/forum/golang-panama) - Panamá.
* [Golang Lima](http://www.meetup.com/es/Golang-Peru/) - Perú
* [Golang Venezuela](https://t.me/golangve) - Venezuela

1880
GoUsers.md

File diff suppressed because it is too large Load Diff

230
Gomote.md

@ -1,230 +1,4 @@
# Gomote The Go wiki on GitHub has moved to go.dev (#61940).
The gomote command is a client for the Go builder infrastructure. It's a remote control for remote Go builder machines. Try <https://go.dev/wiki/Gomote> or <https://go.dev/wiki/>.
## Installation
```
$ go install golang.org/x/build/cmd/gomote@latest # Go 1.16 and later
```
## Usage
The most basic usage of the gomote tool involves just a few steps:
1. Create an instance.
1. Push code to the instance.
1. Run commands on the instance.
Running the `create` command will list available instance types.
```
$ gomote create
(list tons of buildlet types)
```
Then, an instance can be created by specifying an instance type. The instance's name will be printed to stdout, so the result may be stored in an environment variable. (There may be other logging messages, but they will be on stderr and each line will have a '#' prefix.)
```
$ gomote create linux-amd64
# still creating linux-amd64 (1) after 5s; 0 requests ahead of you
user-linux-amd64-0
```
With that instance's name you can now push (more specifically sync the contents of) a local Go repository to the instance and install a bootstrap toolchain. The repository you sync will appear at the `go` subdirectory of `$WORKDIR` (the default directory of all gomote operations). The bootstrap toolchain will always go into the `go1.4` subdirectory (even if the bootstrap toolchain isn't from version 1.4).
```
$ GOROOT=/path/to/local/go/repo gomote push user-linux-amd64-0
$ gomote ls user-linux-amd64-0
go
go1.4
```
Note that `push` really is a "sync" operation, so next time you push the gomote tool will only push what has changed (files added, modified, or removed).
With a toolchain installed, you can now build it by running commands on the instance. The `run` command allows you to specify an executable to run. The executable must be specified relative to `$WORKDIR` (e.g. `go/bin/go`) or via an absolute path (e.g. `/bin/bash`). That executable will then run with its current working directory set to the directory containing the executable.
```
$ gomote run user-linux-amd64-0 go/src/make.bash
```
To then run the built Go toolchain, use `go/bin/go`.
```
$ gomote run user-linux-amd64-0 go/bin/go test -run="TestSomething" -v runtime
```
You can additionally specify a working directory and environment variables to `run` that will be applied before the command is executed.
Note that gomote instances will automatically disappear after 30 minutes of inactivity. Use the `list` command to check how long they have left.
```
$ gomote list
user-linux-amd64-0 linux-amd64 host-linux-amd64-bullseye expires in 10m27.339494527s
```
The `ping` command can be used to keep an instance alive if no other commands are being run against it.
For more information on each command run `gomote help <command>`. For more commands, run `gomote help`.
### Debugging buildlets directly
The `create` command contacts the build coordinator (farmer.golang.org) and requests that it create the buildlet on your behalf. All subsequent commands (such as `gomote run` or `gomote ls`) then proxy your request via the coordinator. To access a buildlet directly (for example, when working on the buildlet code), you can skip the `gomote create` step and use the special builder name `<build-config-name>@ip[:port>`, such as `windows-amd64-2008@10.1.5.3`.
### Groups
Instances may be managed in named groups, and commands are broadcast to all instances in the group.
A group is specified either by the -group global flag or through the `GOMOTE_GROUP` environment variable. The -group flag must always specify a valid group, whereas `GOMOTE_GROUP` may contain an invalid group. Instances may be part of more than one group.
Groups may be explicitly managed with the "group" subcommand, but there are several short-cuts that make this unnecessary in most cases:
- The `create` command can create a new group for instances with the `-new-group` flag.
- The `create` command will automatically create the group in `GOMOTE_GROUP` if it does not exist and no other group is explicitly specified.
- The `destroy` command can destroy a group in addition to its instances with the `-destroy-group` flag.
As a result, the easiest way to use groups is to just set the `GOMOTE_GROUP` environment variable:
```
$ export GOMOTE_GROUP=debug
$ gomote create linux-amd64
$ GOROOT=/path/to/goroot gomote push
$ gomote run go/src/make.bash
```
As this example demonstrates, groups are useful even if the group contains only a single instance: it can dramatically shorten most gomote commands.
## Tips and tricks
### General
The `create` command accepts the `-setup` flag which also pushes a `GOROOT` and runs the appropriate equivalent of `make.bash` for the instance.
Example:
```
$ GOROOT=/path/to/my/goroot gomote create -setup linux-amd64
# Creating user-linux-amd64-0...
# Pushing /path/to/my/goroot to user-linux-amd64-0
# Running make.bash on user-linux-amd64-0...
```
The `create` command accepts the `-count` flag for creating several instances at once.
Example:
```
$ gomote create -count=3 linux-amd64
# Creating user-linux-amd64-0...
# Creating user-linux-amd64-1...
# Creating user-linux-amd64-2...
```
The `run` command accepts the `-collect` flag for automatically writing the output from the command to a file in the current working directory, as well as a copy of the full file tree from the instance. This command is useful for capturing the output of long-running commands in a set-and-forget manner.
Example:
```
$ gomote run -collect user-linux-amd64-0 /bin/bash -c 'echo hi'
# Writing output to user-linux-amd64-0.stdout...
$ cat user-linux-amd64-0.stdout
hi
$ ls user-linux-amd64-0.tar.gz
user-linux-amd64-0.tar.gz
```
The `run` command accepts the `-until` flag for continuously executing a command until the output of the command matches some pattern. This is useful for reproducing rare issues, and especially useful when used together with `-collect`.
Example:
```
$ gomote run -collect -until 'FAIL' user-linux-amd64-0 go/bin/go test -run 'TestFlaky' -count=1000 runtime
# Writing output to user-linux-amd64-0.stdout...
$ cat user-linux-amd64-0.stdout
...
--- FAIL: TestFlaky ---
...
$ ls user-linux-amd64-0.tar.gz
user-linux-amd64-0.tar.gz
```
Note that the `run` command always streams output to a temporary file regardless of any additional flags to avoid losing output due to terminal scrollback. It always prints the location of the file.
#### Reproducing a rare failure
Putting together some of the tricks above and making use of groups, it's much easier to hammer on some test to try to reproduce a rare failure. For example:
```
$ export GOMOTE_GROUP=debug
$ GOROOT=/path/to/goroot gomote create -setup -count=10 linux-amd64
$ gomote run -until='unexpected return pc' -collect go/bin/go run -run="TestFlaky" -count=100 runtime
```
### Windows
```
$ gomote run -path '$PATH,$WORKDIR/go/bin' $MOTE go/src/make.bat
$ gomote run -path '$PATH,$WORKDIR/go/bin' $MOTE go/bin/go.exe test cmd/go -short
```
Note: previous versions of the wiki have advised setting GOROOT for gomote 'run' commands (e.g. "-e GOROOT=c:\workdir\go"); this is no longer recommended (causes problems with Go command caching).
### Subrepos on Windows
```
$ tar --exclude .git -C ~/go/src/ -zc golang.org/x/tools | gomote puttar -dir=gopath/src $MOTE -
$ gomote run -e 'GOPATH=c:/workdir/gopath' $MOTE go/bin/go test -run=TestFixImportsVendorPackage golang.org/x/tools/imports
```
If ssh'd into the machine, these envvars may be handy:
```
$ set GOPATH=c:\workdir\gopath
$ set PATH=%PATH%;c:\workdir\gopath\bin;c:\workdir\go\bin
$ set CGO_ENABLED=0
```
### Subrepos on Unix
Testing golang.org/x/sys/unix on $MOTE
```
$ tar -C $GOPATH/src/ -zc golang.org/x/sys/unix | gomote puttar -dir=gopath/src $MOTE
$ gomote run -e 'GOPATH=/tmp/workdir/gopath' -dir 'gopath/src/golang.org/x/sys/unix' $MOTE go/bin/go test -v golang.org/x/sys/unix
```
(The GOPATH part is for GOPATH compatibility mode; the `-dir` is for modules mode, which looks in the working directory and up for `go.mod`)
### Android
```
export MOTE=`gomote create android-arm64-wikofever`
gomote push $MOTE
gomote run $MOTE go/src/make.bash
```
PATH must contain the exec wrapper, go_android_*_exec, built by make.bash.
```
gomote run -path '$PATH,$WORKDIR/go/bin' $MOTE go/bin/go test math/big
```
## About buildlets
https://farmer.golang.org/builders lists information about how each buildlet is deployed and configured.
The information is from golang.org/x/build/dashboard and golang.org/x/build/env.
## Access
**On August 2022, a new infrastructure was deployed which required the removal of all gomote access from previously approved users. Please re-request access if you still require access.**
To gain access to the gomote service, file an issue with `access: gomote` as the title and cc `@golang/release`. The issue should contain an email address to a google account. The provided account will only be used for authentication purposes.
Authentication is triggered with the first invocation of a command:
```
$ gomote create linux-amd64
Please visit https://www.google.com/device in your browser and enter verification code:
ABCD-4567
...
```
After opening a browser with the provided link the user must authenticate with the google account and paste the verification code into the browser. After a short wait the client will be authenticated.
### gomote ssh
The `gomote ssh` command uses a SSH keys created specifically for gomote. On the first use of the `gomote ssh` a set of keys will be created and stored in the local user configuration directory. You may be asked to add set a password for the keys (a password is not required). The SSH functionality operates with OpenSSH certificate authentication and does not require any additional configuration.

19
Gopher.md

@ -1,19 +1,4 @@
The Go gopher was designed by [Renee French](https://www.instagram.com/reneefrench/). The Go wiki on GitHub has moved to go.dev (#61940).
The design is licensed under the Creative Commons 3.0 Attributions license.
Read [this article](https://go.dev/blog/gopher) and watch [The Go Gopher A Character Study](https://www.youtube.com/watch?v=4rw_B4yY69k) for more details.
## Where can I find more gopher illustrations? Try <https://go.dev/wiki/Gopher> or <https://go.dev/wiki/>.
* [gophers in the Go website repository](https://go.googlesource.com/website/+/refs/heads/master/_content/doc/gopher/)
* [gopher vector](https://github.com/golang-samples/gopher-vector)
* [gopher 3d](https://github.com/golang-samples/gopher-3d)
* [golang graphics](https://github.com/mholt/golang-graphics)
* [print-ready swimming gopher](https://gumroad.com/l/golang)
* [go gopher vector](https://github.com/keygx/Go-gopher-Vector)
* [gopher gala](http://www.gophergala.com/)
* [gophericons](https://github.com/hackraft/gophericons)
* [gophers by Egon Elbre](https://github.com/egonelbre/gophers)
* [Go Gopher model (3d)](https://github.com/StickmanVentures/go-gopher-model)
* [Gopher Artwork by Ashley McNamara](https://github.com/ashleymcnamara/gophers)
* [Gopherize.me](https://gopherize.me/) - a Gopher avatar that's as unique as you
* [Free Gophers Pack](https://github.com/MariaLetta/free-gophers-pack)

92
HandlingIssues.md

@ -1,92 +1,4 @@
This document explains how we handle issue triage and scheduling in [the Go project's issue tracker](https://go.dev/issue). The Go wiki on GitHub has moved to go.dev (#61940).
# Issue States Try <https://go.dev/wiki/HandlingIssues> or <https://go.dev/wiki/>.
Any issue must be in one of the following states. Project contributors move issues from one state to another. The intent behind these explicit states is to describe the (minimum) next steps required to bring the issue to resolution. Issues may move between states in any order, as dictated by the needs of the particular issue.
### New
- The issue has been filed.
- May not be correctly formatted (title, etc).
- To transition from this state, someone must clean up the issue report and optionally CC people who might best investigate or fix it.
### Needs Investigation
- Is correctly formatted.
- The title has a path prefix.
- The body describes the issue.
- Has a milestone.
- If the issue is not important, it is ok to set the milestone to `Backlog`. Otherwise, set it to the next upcoming release.
- Has the label `NeedsInvestigation`.
- May also have the label `WaitingForInfo` if the investigator is waiting for more information from someone (e.g., the issue reporter).
- To transition from this state, someone must examine the issue and confirm that it is valid and not a duplicate of an existing issue.
### Needs Decision
- The issue is real, but we're not sure what action to take.
- The issue can be addressed in Go 1.
- Feedback is required from experts, contributors, and/or the community before a fix can be made.
- Note that the majority of issues will never transition to this state, as most of the time the decision is an obvious “Yes, this should be fixed.”
- Has a milestone.
- Has the label `NeedsDecision`.
- May have the label `WaitingForInfo`.
- May have the label `Blocked` if forward progress depends upon the resolution of another issue or the release of a future version of Go. An accompanying comment should explain the blockage.
- Must not have the label `Go2`. (Those issues are handled separately.)
- To transition from this state, someone must decide how the issue is to be resolved.
- If the decision is complicated, the issue may be given a [`Proposal`](https://github.com/golang/proposal/) label. The issue remains in this state until the proposal process is complete, and moves to `NeedsFix` if approved.
### Needs Fix
- The path to resolution is known, but the work has not been done.
- Has a milestone.
- Has the label `NeedsFix`.
- May have the labels `Blocked` or `WaitingForInfo`.
- To transition from this state, someone must do the work to fix the issue.
### Fixed
- The issue is resolved. No further attention is required.
- The issue is closed.
Issues move from one state to another where appropriate. For example, a contributor may file an issue, assign it to themselves, and immediately apply the `NeedsFix` label. Or, an issue may go from `NeedsDecision` to `NeedsFix`, only to later move back to `NeedsDecision` as complexities arise.
An issue may be closed at any time, with a comment to indicate the reason for closure ("fixed by …", "duplicate of …", "working as intended", etc).
At any state (except New) the issue may be assigned to someone.
Unassigned issues are considered available for anyone to address.
# Milestones
Milestones describe the timeline for issue resolution.
- Go1.x.y
Planned to be fixed in release 1.x.y.
- Go1.x.y with release-blocker label
Must be fixed for release 1.x.y, or explicitly postponed to a later release.
- Proposal
Is a proposal and does not pertain to a specific release.
- Backlog
Someone has plans to work on it, but it is not assigned to a release milestone yet.
- Unplanned
Might be fixed at some point, but nobody is planning to do it.
- Unreleased
Is not included in or needed by a release.
- Gccgo
For gccgo issues.
- Go2
Deferred until Go 2.
Additional milestones may be used to manage specific project work.
The label "Soon" is used independently of milestones to indicate that the issue is time-sensitive.

248
Home.md

@ -1,248 +1,4 @@
Welcome to the Go wiki, a collection of information about the [Go Programming Language](https://go.dev/). [Awesome Go](http://awesome-go.com/) is another great resource for Go programmers, curated by the Go community. The Go wiki on GitHub has moved to go.dev (#61940).
## Questions about Go Try <https://go.dev/wiki/Home> or <https://go.dev/wiki/>.
See [Questions](Questions).
Please do not ask questions by editing or creating a wiki page. Any such changes will be silently reverted.
## Contributing
- This wiki is open to editing by any member of the Go community with a GitHub account.
- If you would like to add a new page, please first open an issue in the [Go issue tracker](https://github.com/golang/go/issues) with the prefix 'wiki' to propose the addition. Clearly state why the content does not fit into any of the existing pages.
- Because renaming of pages in the wiki can break external links, please open an issue before renaming or removing any wiki page.
# Table of Contents
- [Getting started with Go](#getting-started-with-go)
- [Working with Go](#working-with-go)
- [Learning more about Go](#learning-more-about-go)
- [The Go Community](#the-go-community)
- [Using the go toolchain](#using-the-go-toolchain)
- [Additional Go Programming Wikis](#additional-go-programming-wikis)
- [Online Services that work with Go](#online-services-that-work-with-go)
- [Troubleshooting Go Programs in Production](#troubleshooting-go-programs-in-production)
- [Contributing to the Go Project](#contributing-to-the-go-project)
- [Platform Specific Information](#platform-specific-information)
- [Release Specific Information](#release-specific-information)
- [Questions](Questions)
## Getting started with Go
- [The Go Tour](https://go.dev/tour/) is the best place to start.
- [Effective Go](https://go.dev/doc/effective_go) will help you learn how to write idiomatic Go code.
- [Go standard library documentation](https://pkg.go.dev/std) to familiarize yourself with the standard library.
- [Use the Go Playground](https://go.dev/play) to test out Go programs in your browser.
- Still not convinced? Check out this list of [Go Users](GoUsers) and a few of their [Success stories](SuccessStories). We've also assembled a long list of reasons [why you should give Go a try](whygo).
- Read about the companies which have [switched from other languages to Go](https://github.com/golang/go/wiki/FromXToGo).
## Working with Go
Ready to write some Go code of your own? Here are a few links to help you get started.
- Install and Setup your Environment
- Start here: [Official Installation Documentation](https://go.dev/doc/install)
- If you prefer to install from source, [read this first](https://go.dev/doc/install/source).
- [InstallFromSource](InstallFromSource) - Additional tips on source installs.
- Windows user? [Install and configure Go, Git, and Visual Studio Code for Windows](https://github.com/abourget/getting-started-with-golang)
- Mac user? [How I start - Go](https://howistart.org/posts/go/1) - A step-by-step guide to installing Go and building your first web service.
- Having installation problems? [InstallTroubleShooting](InstallTroubleShooting)
- Make sure you have your [$GOPATH environment variable set correctly](https://go.dev/doc/install/source#gopath)
- If you need additional tips on using [$GOPATH, go here](GOPATH).
- [MultipleGoRoots](MultipleGoRoots) - More advanced information on working with multiple go installations and the `$GOROOT` variable.
- [Go IDEs and Editors](IDEsAndTextEditorPlugins) - Information on how to use your favorite editor with Go.
- [Tools for working with Go code](CodeTools) - Formatting, linting, vetting, refactoring, navigation, and visualization.
- Finding Go Libraries and Packages
- Start here: [Go open source projects](Projects).
- Search for Go packages: [pkg.go.dev](http://pkg.go.dev)
- Visualization of the [Go open-source package graph](https://anvaka.github.io/pm/#/galaxy/gosearch?l=1)
- [Modules](Modules) - documentation on the dependency management system built into the Go command, added in 1.11.
- [Managing your dependencies](PackageManagementTools) - An overview of the tools you can use to manage third-party packages (vendoring).
- Publishing Go Packages as Open Source
- Getting ready to publish your package? [Start here.](PackagePublishing)
- [The Go Checklist](https://github.com/matttproud/gochecklist) - A comprehensive guide for publishing a project.
- [How to layout your GitHub repo](GitHubCodeLayout) to make it easy for other Go programmers to use with the `go get` command.
- [Go Package, Go](https://johnsto.co.uk/blog/go-package-go) - A few recommendations for making Go packages easy to use.
## Learning more about Go
Once you have an overview of the language, here are resources you can use to learn more.
- [Learning Go](Learn) - A collection of resources for learning Go - beginner to advanced.
- [Best Practices for a New Go Developer](https://www.cloudbees.com/blog/best-practices-for-a-new-go-developer) - Insights from Go community members.
- [Server programming](LearnServerProgramming) - Building web, mobile, and API servers.
- [More on concurrency](LearnConcurrency)
- [More on error handling](LearnErrorHandling)
- [More on testing](LearnTesting)
- [More on mobile - Android and iOS](Mobile)
- [Books](Books) - A list of Go books that have been published (ebook, paper).
- [Blogs](Blogs) - Blogs about Go.
- [Podcasts](Podcasts) - Podcasts and episodes featuring Go.
- Videos, Talks, and Presentations
- [GopherVids](http://gophervids.appspot.com/) (currently unreachable) is a searchable index of videos about Go.
- [GoTalks](GoTalks) - A collection of talks from Go conferences and meetups.
- [Livestreams](Livestreams) - live interactive Go project streams with members of the community.
- [Screencasts](Screencasts)
- [Articles](Articles) - A collection of articles to help you learn more about Go.
- [Training](Training) - Free and commercial, online, and classroom training for Go.
- [University Courses](Courses) - A list of CS programs and classes using Go.
- [Resources for non-English speakers](NonEnglish)
## The Go Community
Here are some of the places where you can find Gophers online. To get a sense of what it means to be a member of the Go community, read [Damian Gryski's keynote from the GolangUK 2015 conference](https://medium.com/@dgryski/the-go-community-f0d00e3a19e) or watch [Andrew Gerrand's closing keynote from GopherCon 2015](https://www.youtube.com/watch?v=0ht89TxZZnk).
- Where Gophers hangout online:
- [The Go Forum](https://forum.golangbridge.org/) - An all-purpose discussion forum for the Go community.
- [Gophers Slack Channel](http://gophers.slack.com/) - For real-time chat ([request membership](http://blog.gopheracademy.com/gophers-slack-community/)).
- [Golang News](http://golangnews.com) - For curated links about Go Programming.
- There is also a [/r/golang](http://reddit.com/r/golang) sub-reddit.
- On Twitter, follow the [@golang](https://twitter.com/golang) account and keep tabs on the [#golang](https://twitter.com/search?q=%23golang&src=typd) hashtag.
- We've also got a landing page on [Stack Overflow](http://stackoverflow.com/tags/go) for Go Q&A.
- Matrix enthusiasts are invited to join [#Go:matrix.org](https://riot.im/app/#/room/#Go:matrix.org).
- Discord users are welcome at the [Discord Gophers](https://discord.gg/golang) server.
- Hashnode users talk and write about Go in [Hashnode Go community](https://hashnode.com/n/go).
- Mailing Lists
- The mailing list for Go users is [golang-nuts](https://groups.google.com/forum/#!forum/golang-nuts) - very high traffic.
- Before you post, [check to see if it's already been answered](http://stackoverflow.com/tags/go), then read [these tips on how to ask a good question](HowToAsk)
- For discussions about the core Go open source project, join [golang-dev](https://groups.google.com/forum/#!forum/golang-dev).
- To get just our release announcements, join [golang-announce](https://groups.google.com/forum/#!forum/golang-announce)
- User Groups & Meetups - There are [Go Meetups in many cities](http://www.meetup.com/find/?allMeetups=false&keywords=golang&radius=Infinity&userFreeform=Sunnyvale%2C+CA&mcId=z94086&mcName=Sunnyvale%2C+CA&sort=recommended&eventFilter=mysugg)
- [GoBridge](http://golangbridge.org) - Volunteers helping underrepresented communities to teach technical skills and to foster diversity in Go.
- [Women Who Go](http://www.womenwhogo.org/)
- See here for [additional information GoUserGroups](GoUserGroups)
- [GoDiscourse](https://github.com/godiscourse/godiscourse) - Go Discourse is an open-source Go-based forum from `hello world`.
- [Conferences](Conferences) - A list of upcoming and past Go conferences and major events.
- [Companies using Go](GoUsers) - A comprehensive list of companies using Go throughout the world.
- Learn more about the [Go Gopher images](Gopher) by Renee French.
## Using the Go Toolchain
- Start with the standard documentation for the `go` command [available here](https://pkg.go.dev/cmd/go/)
- Start here to learn about [vendoring](https://pkg.go.dev/cmd/go/#hdr-Vendor_Directories).
- See also [PackageManagementTools](PackageManagementTools) for package management tools.
- [Cross Compilation](https://rakyll.org/cross-compilation/)
- Shared libraries and Go (buildmode)
- [Go Shared Libraries](https://github.com/jbuberel/buildmodeshared) - Examples for creating and using shared libraries from Go and Python.
- [Sharing Go Packages with C](http://blog.ralch.com/tutorial/golang-sharing-libraries/) - by [@ralch](https://twitter.com/ralch).
- [Calling Go libraries from Python](https://blog.filippo.io/building-python-modules-with-go-1-5/) - by Filippo Valsorda
- [Calling Go libraries from Ruby](http://c7.se/go-and-ruby-ffi/) - by Peter Hellberg
- [Calling Go libraries from Swift](https://rakyll.org/swift/) - by Jaana Burcu Dogan
- [Build a Ruby Gem with a Go native extension](http://blog.paracode.com/2015/08/28/ruby-and-go-sitting-in-a-tree) - by @jondot
- [gohttplib](https://github.com/shazow/gohttplib) - An experiment in using Go 1.5 buildmode=c-shared.
- See the wikis below for additional details:
- [GoGetTools](GoGetTools)
- [GoGetProxyConfig](GoGetProxyConfig)
- [cgo](cgo)
- [CompilerOptimizations](CompilerOptimizations)
- [GccgoCrossCompilation](GccgoCrossCompilation)
- [GcToolchainTricks](GcToolchainTricks)
- [GoGenerateTools](GoGenerateTools)
- [Go Tooling Essentials](https://rakyll.org/go-tool-flags/) - by Jaana Burcu Dogan
## Additional Go Programming Wikis
- Concurrency
- [Timeouts](Timeouts) - Abandon async calls that take too long
- [LockOSThread](LockOSThread)
- [MutexOrChannel](MutexOrChannel) - When to use one vs the other
- [RaceDetector](RaceDetector) - How to detect and fix race conditions
- Working with Databases
- [database/sql](http://go-database-sql.org/) - Online tutorial for working with the database/sql package.
- [SQLDrivers](SQLDrivers)
- [SQLInterface](SQLInterface)
- From other languages
- [Go for Java Programmers](http://yourbasic.org/golang/go-java-tutorial/)
- [Go for C++ Programmers](GoForCPPProgrammers)
- Strings
- [GoStrings](GoStrings)
- [String Matching](http://blog.gopheracademy.com/advent-2014/string-matching/)
- [Comments](Comments)
- [CommonMistakes](CommonMistakes)
- [Errors](Errors)
- [GcToolchainTricks](GcToolchainTricks)
- [InterfaceSlice](InterfaceSlice)
- [Iota](Iota)
- [MethodSets](MethodSets)
- [PanicAndRecover](PanicAndRecover)
- [Range](Range)
- [RateLimiting](RateLimiting)
- [SignalHandling](SignalHandling)
- [SimultaneousAssignment](SimultaneousAssignment)
- [SliceTricks](SliceTricks)
- [Switch](Switch)
- [TableDrivenTests](TableDrivenTests)
## Online Services that work with Go
If you're looking for services that support Go, here's a list to get you started.
- Cloud Computing - Go is well supported by most cloud service providers.
- [Amazon Web Services](https://github.com/aws/aws-sdk-go)
- [Azure](https://github.com/Azure/azure-sdk-for-go)
- [DigitalOcean](https://github.com/digitalocean/godo)
- [GE Predix](https://github.com/geaviation/goboot-starter)
- [Google Cloud Platform for Go](https://cloud.google.com/go)
- [Heroku](https://github.com/heroku/heroku-buildpack-go)
- [IBM Bluemix](https://developer.ibm.com/bluemix/2015/10/28/getting-started-with-golang-on-bluemix/)
- [OpenStack](https://github.com/openstack/golang-client)
- [Vscale](https://github.com/vscale/go-vscale)
- [Aliyun](https://github.com/aliyun/alibaba-cloud-sdk-go)
- [Tencent](https://github.com/TencentCloud/tencentcloud-sdk-go)
- See here for [information on additional providers](ProviderIntegration)
- [Continuous Integration and Continuous Deployment](HostedContinuousIntegration) - Go is well supported by most CI/CD frameworks
- Monitoring/Logging
- [OpsDash](https://www.opsdash.com/) - Go-based cluster monitoring platform.
- Package and Dependency Management
- [Gopkg.in](http://labix.org/gopkg.in) is a source for stable Go libraries, provided by Gustavo Niemeyer.
## Troubleshooting Go Programs in Production
- Understand the performance of your Go apps using the [pprof package](https://go.dev/blog/profiling-go-programs)
- Heap Dumps
- [[heapdump13]]
- [[heapdump14]]
- [[heapdump15-through-heapdump17]]
## Contributing to the Go Project
- Start by reading the [Go Contribution Guidelines](https://go.dev/doc/contribute)
- If you'd like to propose a change to the Go project, start by reading the [Go Change Proposal Process](https://github.com/golang/proposal)
- An archive of [design documents is also available](DesignDocuments)
- Go releases happen at ~6-month intervals. [See here for more information](Go-Release-Cycle)
- Want to know more about how the [Go source X-repositories are structured?](X-Repositories)
- The Go project requires that all code be reviewed before it is submitted.
- Read more about our [code review practices](CodeReview)
- If you're commenting on code under review, please read [these guidelines](CodeReviewComments)
- Issues
- Bug reports and feature requests should be filed using the [GitHub issue tracker](https://github.com/golang/go/issues)
- Want to understand how we [handle issues that are reported?](HandlingIssues)
- Project Dashboards
- [Go Builds Dashboard info](DashboardBuilders)
- [Performance Dashboard info](PerfDashboard)
- [Download failed logs and debugging](https://github.com/golang/go/wiki/Download-build-farm-failed-logs-and-debugging)
## Platform Specific Information
See [MinimumRequirements](MinimumRequirements) for minimum platform requirements of current Go ports. Considering porting Go to a new platform? [Read our porting policy first](PortingPolicy).
- [ChromeOS](ChromeOS)
- [Darwin](Darwin)
- [DragonFly BSD](DragonFly-BSD)
- [FreeBSD](FreeBSD)
- [Go on ARM](GoArm)
- [Linux](Linux)
- [Ubuntu](Ubuntu)
- [Mobile](Mobile)
- [NetBSD](NetBSD)
- [OpenBSD](OpenBSD)
- [Plan 9](Plan9)
- [Solaris](Solaris)
- [Windows](Windows)
- [WindowsBuild](WindowsBuild)
- [WindowsCrossCompiling](WindowsCrossCompiling)
- [WindowsDLLs](WindowsDLLs)
Notes:
- Please refrain from changing the title of the wiki pages, as some of them might be linked to from [golang.org](https://golang.org) or other websites

15
HostedContinuousIntegration.md

@ -1,13 +1,4 @@
A number of hosted continuous integration platforms have support for Go The Go wiki on GitHub has moved to go.dev (#61940).
Try <https://go.dev/wiki/HostedContinuousIntegration> or <https://go.dev/wiki/>.
| Provider | Documentation | Notes |
|:---------|:--------------|:------|
| [AppVeyor](http://www.appveyor.com/) | [docs](https://bitbucket.org/appveyor/test-go) | Windows |
| [CircleCI](https://circleci.com/) | [docs](https://circleci.com/docs/language-go/)| [howto-1](http://stackengine.com/golang-with-circleci/) [howto-2](https://medium.com/@jgautheron/publish-your-golang-binaries-in-github-with-circleci-e0b64cb21bf8) |
| [Codeship](http://codeship.io) | [docs](https://www.codeship.io/documentation/languages-and-frameworks/go/) | |
| [drone.io](http://drone.io/) | [docs](http://docs.drone.io/golang.html) | [open-source version](https://github.com/drone/drone) |
| [Jenkins](https://jenkins-ci.org/) | [docs](https://wiki.jenkins-ci.org/display/JENKINS/Go+Plugin) | |
| [Magnum CI](https://magnum-ci.com/) | [docs](https://magnum-ci.com/docs/go) | |
| [Travis CI](http://travis-ci.org) | [docs](http://docs.travis-ci.com/user/languages/go/) | [howto](http://loads.pickle.me.uk/2015/08/22/easy-peasy-github-releases-for-go-projects-using-travis/), [go-client-api](https://github.com/AbletonAG/go-travis) |
| [Azure Devops](https://www.visualstudio.com/team-services/) | [docs](https://docs.microsoft.com/en-us/vsts/build-release/apps/go/go) | |
| [Wercker](http://wercker.com/) | [docs](http://devcenter.wercker.com/quickstarts/building/golang.html) | | |

60
How-to-ask-for-help.md

@ -1,60 +1,4 @@
This page gives some hints on how to successfully ask for help in the various [Go support forums][3]. The Go wiki on GitHub has moved to go.dev (#61940).
## Before you ask your question Try <https://go.dev/wiki/How-to-ask-for-help> or <https://go.dev/wiki/>.
Before asking for help, please check that you've addressed the following common issues:
### Always check all errors
Always check all errors. It is common to see problems reported related to nil panics due to code like this
```
result, err := somefunction()
if err != nil {
log.Println("oops an error happened", err)
// return is missing here
}
// the code then continues to use result which is invalid.
```
or
```
result, _ := somefunction()
// code uses result which might be invalid
```
You should make sure it is clear that your code is correctly handling all error conditions before asking for help.
Further reading:
- [Error handling and Go][0]
### Check that your code is free from data races
Unexpected runtime panics are often caused by data races in your program. If your program contains a data race you need to address the race before asking for help.
If your program has good test coverage you can test for races by adding the `-race` flag to your `go test` invocation.
If your program does not have good test coverage or the crash only happens when running the program, you can build a race enabled version of your program by passing `-race` to your `go build` or `go install` invocation.
_The behaviour of a Go program with a data race is undefined. There are no safe data races in Go programs._
Further reading:
- [Introducing the race detector][1]
## Asking questions
The best way to get help is to show
1. **What you did, ideally with a small complete, stand-alone, example.**
If you ran a command, show the command that you ran. If your program failed, provide the source of the program that failed. If the program is too large, or you cannot share the source, instead provide a self contained, runnable example, that demonstrates the problem.
2. **What you expected to happen.** If you expected the command to complete successfully, say that. If you expected the program to produce a particular output, give an example of the output you expected.
3. **What happened instead.**
If the command failed, include the full output of the failure, not just a single line that you though was the cause. If the program failed to produce the expected output, include what it did output.
## Additional tips
- If you are posting the output of a command, paste the text, not a screenshot of the text. If it's actually an image, that's ok.
- If you are posting a large amount of output, you may consider using a pastebin or gist service.
- When posting code samples, use the [Go playground][2] (unless it is unavailable in your country).
[0]: https://go.dev/blog/error-handling-and-go
[1]: https://go.dev/blog/race-detector
[2]: https://go.dev/play
[3]: https://github.com/golang/go/wiki/questions

112
HowToAsk.md

@ -1,112 +1,4 @@
# A quick introduction The Go wiki on GitHub has moved to go.dev (#61940).
Imagine you want to know how to get from "Old street" to "New street". You call a random person to get help and you ask "What is the fastest way I can get from Old street 19 to New street 3?". Would the random person be able to help you? Try <https://go.dev/wiki/HowToAsk> or <https://go.dev/wiki/>.
There are a lot of "New" and "Old" streets in the world, so first he would need to know what country and city you are in. If the street layout is complicated then maybe you need to name some buildings that are near you. Of course because speed is an issue then your means of transportation is also important; are you by foot, bike, car or truck? You can go on foot into places where you can't get by truck.
Those questions around the immediate question "How do I X?" is the context of the problem, it helps other people orient to the problem. Giving advice without context could mean that the other person will describe the wrong city.
In person it's easy to ask those questions and can be done in rapid succession, although on the forums this will result in a lot of back-and-forth questions that can be avoided. So, how to properly give the context to the problem?
# How to ask a good question
People on the forums have limited time available. So, to speed things up, here is a small template for asking a question that will get better answers and answers quicker:
> The gist of the problem you are having.<br>
<blockquote><br>
How did you encounter the problem?<br>
What are you trying to accomplish?<br>
What is the context of the problem?<br>
What are the requirements for the solution?<br>
What are the context-specific constraints/properties?<br>
Your compilable and runnable example on <a href='https://go.dev/play'>play.golang.org</a><br>
<br>
Other notes about the situation (production/school/playing/learning)</blockquote>
Things to keep in mind:<br>
<ul><li>Take your time to spell-check and make sure that your sentences are readable.<br>
</li><li>The solution can be far away from the immediate problem. So be sure that the question contains answers to the <a href='http://en.wikipedia.org/wiki/5_Whys'>5 whys</a>. The template implicitly already contains answers to 3 whys.<br>
</li><li>The context of the question is important, so always give one. Not giving the context may end up hurting you, because you’ll get an answer that’s more suited to a different context. The context is the end-user or domain problem and goal, with the information how it tries to solve it.<br>
</li><li>Try not to ask abstract questions but if you do then add multiple concrete examples. Asking abstract things without concrete examples (usually) wastes time. Although they can be sometimes interesting, the concrete examples allow the discussion to be precise.<br>
</li><li>Avoid imprecise terms such as "a lot of data" or "needs to work fast". Give something measurable such as "it needs to work upto 1GB of data" or "it needs to communicate with 1000 concurrent clients within 100ms".<br>
</li><li>If you are not able to give the compilable example in go, any language will do... many people are well versed in other languages. If you are not able to make it compile or run, it's fine too.<br>
</li><li>Try to explain your situation:<br>
<ul><li>Noting that "it is homework" means people can explain a bit more and won't do the homework for you.<br>
</li><li>Information such as "it needs to work on a cluster of X nodes" can provide situational context. Where and how the code must eventually run.<br>
</li><li>Noting that "it’s for learning X" makes it clear that you are trying to get a deeper understanding of different approaches.<br>
</li><li>Noting that "I’m under NDA and can’t disclose the code", means people won’t bother asking for it. Although you should still try to come up with a similar situation, it helps the answerer.<br>
</li></ul></li><li>Giving a simplified example can be helpful for readers, but do not forget to give the full version as well. The simplified version is different from the full version and therefore the solutions can be different.</li></ul>
Of course, don't worry too much... you can't answer all possible questions. It's not needed to write a 4 page essay on the whole thing. People can always ask when something needs clarification.<br>
<br>
<h1>The story of a bad question</h1>
Why is that template necessary? Let's put you in the shoes of the answerer, and let's say you get this question:<br>
<br>
<blockquote>How do I use the reflect <code>Set</code> method?</blockquote>
From the askers perspective this may look like a straightforward problem. Of course, you have no idea what the asker is trying to do. Is he trying to set a value on a value, struct, array or a map? This means you need to ask the first question: <i>Can you give an example?</i>.<br>
<br>
Now the asker will provide an example:<br>
<br>
<blockquote>I'm basically trying to do this:<br>
<pre><code> m := make(map[string]int)<br>
v := reflect.ValueOf(m)<br>
key := reflect.ValueOf("hello")<br>
val := reflect.ValueOf(123)<br>
v.MapIndex(k).Set(val)<br>
print(m)<br>
</code></pre>
But it just panics.</blockquote>
Now you've got some code that even doesn't compile. This means you need to copy paste it somewhere and fix the mistakes. Putting it on <a href='https://go.dev/play'>play.golang.org</a> makes it easier to see the problem (e.g. <a href='https://go.dev/play/p/fCxBlL9V4Y'>play.golang.org/p/fCxBlL9V4Y</a>).<br>
<br>
<i>The fix is simple; just use <code>SetMapIndex</code> instead.</i> Of course that may not be the full story. The asker now comes back with another problem:<br>
<br>
<blockquote>Yay, I've got the reflection working, but it's not fast enough.<br>
How can I make it faster?</blockquote>
What does "faster" mean? What is he trying to do? So you need to ask more about the specifics of the problem. So you ask: <i>What are you trying to accomplish?</i>
<blockquote>I'm trying to implement a set package that can store generic types.</blockquote>
Well, ok, but that still didn't answer why it needs to be faster. Why is he using <code>reflect</code> for that anyway, when you can use <code>map</code> instead. So you answer: <i>Can't you just use <code>map</code> instead (e.g. <code>map[type]struct{}</code>)? What are you writing the <code>set</code> package for?.</i>
<blockquote>I'm writing a program that goes over multiple sequences and that finds the common elements.<br>
The main use for is for using on nucleotides and it should work on large datasets. But it should also work on proteins, which are represented by another type.</blockquote>
<blockquote>Yes, the <code>map[NucleotideIndex]struct{}</code> works a bit better, but it's still not fast enough, and I would now have to write the same code for proteins.</blockquote>
Finally we have all the information that's needed. The solution is straightforward: <i><code>biogo</code> <a href='https://code.google.com/p/biogo/'>https://code.google.com/p/biogo/</a> has most of the stuff necessary for handling large datasets and parallelism etc. Also what's the "<code>NucleotideIndex</code>".</i> The asker may have found the answer and say: <i>Thanks that's really nice.</i> but there is a possibility of:<br>
<br>
<blockquote>Whoa, that looks nice, but I'm in a bioinformatics course and we need to write that code ourselves. The "<code>NucleotideIndex</code>" is a "<code>struct {Nucleotide Nucleotide; Index int}</code>".</blockquote>
That looks weird, why would you do it that way. Nevertheless we've all done something stupid, so... now you can start suggesting something better: <i>Probably dealing with <code>map[Type]map[int]struct{}</code> would be much easier. Because you are dealing with sequences and the set elements are always used in an increasing order you can just store the index in an array e.g. <code>map[Type][]int</code>. Also if the memory starts to become the problem you could make it into a run-length-encoded set...</i>
Now we can have a more meaningful discussion about the (dis)advantages of different set types.<br>
<br>
Hopefully after this long example, you probably understand why it's useful to provide more information. The initial back and forth questions could have been avoided. Proper question could have saved time for the question asker and the answerer.<br>
<br>
The initial question could have been:<br>
<br>
<blockquote>How do I use the reflect <code>Set</code> method with <code>MapIndex</code>?<br>
<br>
I'm trying to set a value on a generic map for a set package. But it just gives a panic when I try to do that. <a href='https://go.dev/play/p/fCxBlL9V4Y'>play.golang.org/p/fCxBlL9V4Y</a><br>
<br>
I use the set package in a program that goes over multiple sequences and find all the common elements in a sequence. The sequence elements could be nucleotides or proteins. The program needs to be able to deal with data-sizes upto 1GB.<br>
<br>
My current code is available at github.com/... <br>
<br>
I'm writing this for a bioinformatics course, so I need to implement it myself.</blockquote>
Summary:<br>
<br>
<ul><li>The best answer depends on the context. In some cases maybe <a href='http://research.swtch.com/sparse'>research.swtch.com/sparse</a> would be more appropriate. If the speed isn't important using a <code>map</code> would be sufficient. So the requirements are also important.<br>
</li><li>The problem can be somewhere else. As you saw the answerer didn't expect that the structure of the program was at fault. Using a struct <code>NucleotideIndex</code> with a <code>map</code>, meant he had to build elaborate things with reflection. Often when you fix the higher-level problem, everything else will become much easier.<br>
</li><li>Constraints/properties matter. The property "set elements are used in increasing order" meant that there was a simple method that didn't require a full-blown <code>set</code> implementation. This specialized structure can be much faster. The information about the system, context or domain may make the problem much simpler.<br>
</li><li>The solution may differ from your usual approaches. Maybe the asker decided to use <code>reflect</code> package, because he was used to generics in Java. Go is different language, so the final solution may look a lot different from the solution in Java.</li></ul>
<h1>More tips</h1>
</li><li><a href='http://www.catb.org/esr/faqs/smart-questions.html'>Smart questions</a>
</li><li><a href='http://www.sscce.org/'>Short, Self Contained, Correct (Compilable), Example</a>

62
IDEsAndTextEditorPlugins.md

@ -1,62 +1,4 @@
# Editors and IDEs for Go The Go wiki on GitHub has moved to go.dev (#61940).
## Popular
The [Go Developer Survey](https://go.dev/blog/survey2021-results) showed these as the most popular editors.
* **[Visual Studio Code](https://code.visualstudio.com/)**: Free & open source IDE by Microsoft. Visual Studio Code supports Go syntax highlighting out of the box. Additional features are provided by the official [vscode-go](https://github.com/golang/vscode-go) plugin.
* **[GoLand](https://www.jetbrains.com/go/)**: JetBrains's cross-platform, [fully featured](https://www.jetbrains.com/go/features/) Go IDE (commercial). Free for students, teachers, open-source developers, and user-groups ([see details](https://www.jetbrains.com/go/buy/#edition=discounts)). Also available as part of IntelliJ IDEA Ultimate.
* **[Vim](http://www.vim.org/)** & **[Neovim](https://neovim.io/)**: Vi Improved. There are a number of plugins available that make editing Go code easier. Try <https://go.dev/wiki/IDEsAndTextEditorPlugins> or <https://go.dev/wiki/>.
* The [vim-go](https://github.com/fatih/vim-go) plugin includes misc/vim and has many other new improvements.
* The [Syntastic](https://github.com/scrooloose/syntastic) plugin gives instant feedback on compile errors
* The [tagbar](https://github.com/majutsushi/tagbar) plugin uses Gotags, above, to show an outline of the current file
* A [vim compiler plugin](https://github.com/rjohnsondev/vim-compiler-go) for syntax checking
* A [vim-godef](https://github.com/dgryski/vim-godef) plugin integrates with the 'godef' tool, above
* A [vim-go-extra](https://github.com/vim-jp/vim-go-extra) is vim plugin based on misc/vim in go repository. This works fine on windows too!
* The [go-ide](https://github.com/plentiform/go-ide) is a Neovim configuration file that ties go related plugins together making autocomplete, auto-importing, snippets, code formatting, and file search/browsing easier.
* [govim](https://github.com/govim/govim) is an LSP-driven vim plugin for Go development, written in Go using Vim8’s channel support.
* **[Emacs](https://www.gnu.org/software/emacs/)**: Extensible and customizable text editor. It has generic LSP support that works well with gopls, the official Go language server.
* **[LSP Mode](https://emacs-lsp.github.io/lsp-mode/)** provides LSP support with a batteries-included approach, with many integrations enabled “out of the box” and several additional behaviors provided by lsp-mode itself.
* **[Eglot](https://github.com/joaotavora/eglot/blob/master/README.md)** provides LSP support with a minimally-intrusive approach, focusing on smooth integration with other established packages. It provides a few of its own eglot- commands but no additional keybindings by default.
* Mode file maintained at https://github.com/dominikh/go-mode.el.
* [GoFlyMake](https://github.com/dougm/goflymake) Flymake-style syntax checking for Go
* [go-errcheck.el](https://github.com/dominikh/go-errcheck.el) Errcheck integration for Emacs
* [flycheck-metalinter](https://github.com/favadi/flycheck-gometalinter) Flycheck integration for go-metalinter utility
* [go-playground](https://github.com/grafov/go-playground) Local playground inside Emacs
## Less popular
These editors are less popular, and may have less modern Go support. In particular, they may not support Go modules.
* **[Atom](https://atom.io/)**: JavaScript-based editor from GitHub. Go support at [go-plus](https://github.com/joefitzgerald/go-plus)
* **[BBEdit](https://www.barebones.com/products/bbedit/)**: free text editor for macOS (with paid upgrade for pro features).
* Go support available with the [Go-bbpackage module](https://github.com/ascarter/go-bbpackage) including syntax highlighting, clippings, ctags standard library completion, and tools
* **[Brackets](http://brackets.io)**: a modern, open source text editor that understands web design.
* [go-ide](https://github.com/David5i6/Brackets-Go-IDE) Go support with autocompletion through gocode.
* **[Chime](https://www.chimehq.com)**: Capable. Focused. Fast. A Go editor for macOS.
* **[CodeLobster IDE](https://www.codelobster.com)** Smart free cross-platform IDE with built-in Go support
* **[CodePerfect 95](https://codeperfect95.com)**: A blazing fast IDE for Go.
* **[jEdit](http://www.jedit.org/)**: open-source, cross-platform text editor written in Java. [Syntax-highlighting file available](https://code.google.com/archive/p/go-stuff/source/default/source).
* **[Kate](https://kate-editor.org/)** Kate is an advanced, cross-platform text editor developed by KDE, with Go support out-of-the-box.
* **[Komodo IDE](https://www.activestate.com/komodo-ide)** Powerful cross-platform IDE with built-in Go support
* **[Komodo Edit](https://www.activestate.com/komodo-edit)** Powerful cross-platform text editor, Go-lang support available via [plugin](https://github.com/Komodo/komodo-go)
* **[LiteIDE](https://github.com/visualfc/liteide)**: A simple, open source and cross-platform Go IDE
* **[Micro](https://micro-editor.github.io)**: A modern and intuitive terminal-based text editor written in Go
* Go language support (gofmt and goimports) via [plugin](https://micro-editor.github.io/plugins.html#c-go)
* **[Notepad++](http://notepad-plus-plus.org/)**: Free source code editor for Windows.
* [notepadplus-go](https://github.com/chai2010/notepadplus-go) Syntax highlighting, functions list panel (for code browsing), code completion for keywords & builtins.
* The GOnpp plugin (available **via Notepad++'s built-in Plugin Manager**) provides code completion (requires gocode), function calltips, goimports integration, and keyboard shortcuts for common go commands. [[sources](https://github.com/tike/GOnpp), [binaries](http://sourceforge.net/projects/gonpp/files/)].
* [GoAutocomplete](https://github.com/steve-perkins/GoAutocomplete) is another code completion plugin.
* **[Nova](https://nova.app)**: Native Mac code editor.
* [Go Language Definition for Nova](https://extensions.panic.com/extensions/gwynethllewelyn/gwynethllewelyn.Go/) — _Go syntax highlighting and interface with the Language Server Protocol (LSP) using Google's official [`gopls`](https://pkg.go.dev/golang.org/x/tools/gopls) language server for Go (if installed)._
* [Go Tools](https://extensions.panic.com/extensions/cloudmanic/cloudmanic.GoTools/) — _Run `goimports` on save or via a command. Syntax highlighting for Go._
* **[Source Insight](https://www.sourceinsight.com)**: Commercial programming editor & code browser with built-in live analysis for C, C++, C#, Java, and more; helping you understand large projects.
* [golang.xclf](https://www.sourceinsight.com/pub/languages/golang.xclf) is a [Custom Language](https://www.sourceinsight.com/download/custom-languages/) file adding syntax formatting and some parsing support to Source Insight for Go language.
* **[Sublime Text](http://www.sublimetext.com/)**: Commercial text editor.
* (Sublime Text 4 only) [LSP + gopls](https://lsp.sublimetext.io/language_servers/#go) is a plugin collection with IDE-like features available.
* [GoSublime](https://github.com/DisposaBoy/GoSublime) is a plugin collection with IDE-like features available.
* [Golang Build](https://github.com/golang/sublime-build) is the official Sublime Text package for Go build system integration.
* **[Textadept](http://foicica.com/textadept/)**: Textadept is a fast, minimalist, and remarkably extensible cross-platform text editor. Supports Go syntax highlighting out of the box.
* **[TextMate](http://macromates.com/)**: Commercial text editor for macOS. [Source code available](https://github.com/textmate/textmate) under the GPLv3. [Bundle for Go available](https://github.com/syscrusher/golang.tmbundle).
* **[Zed](https://zed.dev)**: Code at the speed of thought.
## Cloud Based IDEs
* **[Cloud9](https://aws.amazon.com/cloud9/)**: claims full Go support.
* **[Gitpod](https://gitpod.io)**: GitHub integrated cloud IDE with full Go support.

27
InstallFromSource.md

@ -1,27 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
This is a companion to https://go.dev/doc/install/source providing additional instructions for various operating systems. Try <https://go.dev/wiki/InstallFromSource> or <https://go.dev/wiki/>.
## Install C tools
On OS X, a C compiler is bundled in the command line tools for
[Xcode](http://developer.apple.com/Xcode/),
and you don't need to install the whole Xcode to compile Go.
If you have already installed Xcode 4.3+, you can install command
line tools from the Components tab of the Downloads preferences panel.
In more recent versions of Xcode, you can use ` xcode-select --install `
command to install the command line tools without opening Xcode.
To verify you have a working compiler, just invoke ` gcc `
in a freshly created Terminal window, unless you see the
` "gcc: command not found" ` error, you are ready to go.
On Ubuntu/Debian, use ` sudo apt-get install gcc libc6-dev `.
If you want to build 32-bit binaries on a 64-bit system you'll also need the ` libc6-dev-i386 ` package.
On RedHat/Centos 6, use ` sudo yum install gcc glibc-devel `.
If you want to build 32-bit binaries on a 64-bit system you'll need both
` glibc-devel.i386 ` and ` glibc-devel.x86_64 ` packages.
On Windows, install ` gcc ` with
[TDM-GCC](http://tdm-gcc.tdragon.net/). or try [TDM-GCC Sourceforge link](https://sourceforge.net/projects/tdm-gcc/).
(Make sure you add its ` bin ` subdirectory to your ` PATH `.) Go does not support the Cygwin toolchain.

72
InstallTroubleshooting.md

@ -1,72 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
There are many times in which you may install Go (either from source or from a binary distribution) and things don't work quite right. This page is meant to collect some common wisdom about problems that are relatively common or difficult to diagnose and provide tips and solutions. Try <https://go.dev/wiki/InstallTroubleshooting> or <https://go.dev/wiki/>.
# Contents
* [Introduction](#introduction)
* [Tips](#tips)
* [Environment](#environment)
* [GOROOT vs GOPATH](#goroot-vs-gopath)
* [Troubleshooting](#troubleshooting)
* [Still need help?](#still-need-help)
# Tips
## Environment
To start out with, check the following first:
* GOROOT
* This should _only_ be set if you used a binary distribution and it's not installed in the default location.
* [GOPATH](https://pkg.go.dev/cmd/go#GOPATH_environment_variable)
* This should be set to the directory under which you want your source (and third party packages).
* This can also be set to a list of absolute paths separated by : (or ; on Windows).
* Note that ~/some/path is not absolute and will probably not work the way you expect (try $HOME/some/path instead).
* GOPATH should not be set to or contain GOROOT
* GOBIN
* This should only be set if you _really_ know what you're doing... The default should be fine.
* GOOS, GOARCH, GOHOSTOS, GOHOSTARCH
* You shouldn't need to set these in normal cases.
Under linux and darwin, make sure that any of the above variables which are set are actually exported. When you run the ` env | grep GO ` command, they should be listed. You can also check your environment with the ` go env ` command. In bash, this is done with the ` export GOPATH ` (if it's already set) or ` export GOPATH=/path/to/gopath ` command (similarly for the other variables), usually in your .bashrc or .bash\_profile.
## GOROOT vs GOPATH
Packages under GOROOT store their source files in
` $GOROOT/src/pkg/import/path/*.go `
Notice that this is ` src/pkg `; under GOPATH, source files are stored in
` $GOPATH/src/import/path/*.go `
Because of this inconsistency, it is generally not recommended that GOPATH be set to or contain GOROOT; its directories will be searched automatically for imports regardless of the GOPATH setting.
# Troubleshooting
#### The ` go build ` command doesn't do anything!
The ` go build ` command will only produce a binary; if you run go build in a package directory, it will build the package normally (and report any compile errors), but it will not install it. For that, you use ` go install `. If you think you're building a binary and none is produced, make sure you are in package ` main ` and that you do not have GOBIN set.
#### Why does ` go get ` report ` "Fetching https://runtime/cgo?go-get=1" `?
If you have a source distribution, make sure that your packages are up-to-date. Also double check the environment above.
#### When cross compiling, I get ` "runtime/extern.go:135: undefined: theGoos" `
Read [[WindowsCrossCompiling]] for some helpful scripts. You can also use the ` --no-clean ` argument when you're building the cross-compile toolchain via ` make.bash `.
#### Why does ` go get ` work for some packages and report ` permission denied ` in ` $GOROOT ` for some others (with GOPATH set properly)?
If you at any point installed the package in ` GOROOT ` (either by having no ` GOPATH ` set or by including ` GOROOT ` itself in ` GOPATH `) then there might still be a directory in ` $GOROOT ` (which is always checked first) that is overriding your ` GOPATH `. To verify, run ` go list -f {{.Dir}} importpath ` and if it reports a directory under ` $GOPATH ` try deleting that first.
## Still need help?
Visit us on IRC or ask on the mailing list. You will want to provide the output of the following commands, in addition to any errors you are getting:
### Linux/darwin
```
go version
go env
env | grep GO
```
### Windows
```
go version
go env
set | findstr GO
```

42
InterfaceSlice.md

@ -1,42 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
Given that you can assign a variable of any type to an ` interface{} `, often people will try code like the following. Try <https://go.dev/wiki/InterfaceSlice> or <https://go.dev/wiki/>.
```go
var dataSlice []int = foo()
var interfaceSlice []interface{} = dataSlice
```
This gets the error
```
cannot use dataSlice (type []int) as type []interface { } in assignment
```
The question then, "Why can't I assign any slice to an ` []interface{} `, when I can assign any type to an ` interface{} `?"
## Why?
There are two main reasons for this.
The first is that a variable with type ` []interface{} ` is not an interface! It is a slice whose element type happens to be ` interface{} `. But even given this, one might say that the meaning is clear.
Well, is it? A variable with type ` []interface{} ` has a specific memory layout, known at compile time.
Each ` interface{} ` takes up two words (one word for the type of what is contained, the other word for either the contained data or a pointer to it). As a consequence, a slice with length N and with type ` []interface{} ` is backed by a chunk of data that is N\*2 words long.
This is different than the chunk of data backing a slice with type ` []MyType ` and the same length. Its chunk of data will be N\*sizeof(MyType) words long.
The result is that you cannot quickly assign something of type ` []MyType ` to something of type ` []interface{} `; the data behind them just look different.
## What can I do instead?
It depends on what you wanted to do in the first place.
If you want a container for an arbitrary array type, and you plan on changing back to the original type before doing any indexing operations, you can just use an ` interface{} `. The code will be generic (if not compile-time type-safe) and fast.
If you really want a ` []interface{} ` because you'll be doing indexing before converting back, or you are using a particular interface type and you want to use its methods, you will have to make a copy of the slice.
```go
var dataSlice []int = foo()
var interfaceSlice []interface{} = make([]interface{}, len(dataSlice))
for i, d := range dataSlice {
interfaceSlice[i] = d
}
```

23
InvalidFlag.md

@ -1,23 +1,4 @@
# `invalid flag in #cgo CFLAGS` The Go wiki on GitHub has moved to go.dev (#61940).
This page describes the background for build errors like `invalid flag in #cgo CFLAGS` and what you can do about them. Try <https://go.dev/wiki/InvalidFlag> or <https://go.dev/wiki/>.
[CVE-2018-6574](https://nvd.nist.gov/vuln/detail/CVE-2018-6574) described a potential security violation in the go tool: running `go get` downloads and builds Go code from the Internet, Go code that uses cgo can specify options to pass to the compiler, so careful use of `-fplugin` can cause `go get` to execute arbitrary code. While it is difficult to block every possible way that the compiler might be attacked, we have chosen to block the obvious ones.
As described at [issue 23672](https://go.dev/issue/23672), this is done by using a safelist of compiler/linker options that are permitted during `go get`, `go build`, and friends. When cgo code tries to use to pass an option that is not on the safelist, the go tool will report an error `invalid flag in #cgo CFLAGS` (or `#cgo LDFLAGS`, `pkg-config --cflags`, `pkg-config --ldflags`, and so forth).
This safelist is new in releases 1.8.7, 1.9.4, and 1.10, and all subsequent releases.
## What can I do?
If this happens to you, and the option is benign, you should do two things:
1. Set the environment variable `CGO_CFLAGS_ALLOW` (or `CGO_LDFLAGS_ALLOW`, `CGO_CXXFLAGS_ALLOW`, and so forth) to a [regexp](https://pkg.go.dev/regexp/) that matches the option.
2. [File a bug](https://go.dev/issue/new) requesting that the option be added to the safelist. Be sure to include the complete error message and, if possible, a description of the code you are building.
## Why not use an unsafe list?
Because if some new unsafe option is added to a compiler, all existing Go releases will become immediately vulnerable.
## Why not get a complete list of compiler options and safelist all of them?
Because there are hundreds of options, and there is no clear way to get a complete list. Many compiler and linker options are target dependent, and thus only reported on specific platforms or in specific configurations. The documentation is known to be incomplete.

41
Iota.md

@ -1,41 +1,4 @@
# Summary The Go wiki on GitHub has moved to go.dev (#61940).
Go's ` iota ` identifier is used in ` const ` declarations to simplify definitions of incrementing numbers. Because it can be used in expressions, it provides a generality beyond that of simple enumerations. Try <https://go.dev/wiki/Iota> or <https://go.dev/wiki/>.
The value of iota is reset to 0 whenever the reserved word ` const ` appears in the source (i.e. each const block) and incremented by one after each [ConstSpec](https://go.dev/ref/spec#ConstSpec) e.g. each Line. This can be combined with the constant shorthand (leaving out everything after the constant name) to very concisely define related constants.
Iota: https://go.dev/ref/spec#Iota
Constant declarations: https://go.dev/ref/spec#Constant_declarations
# Examples
The official spec has two great examples:
https://go.dev/ref/spec#Iota
Here's one from Effective Go:
```
type ByteSize float64
const (
_ = iota // ignore first value by assigning to blank identifier
KB ByteSize = 1 << (10 * iota)
MB
GB
TB
PB
EB
ZB
YB
)
```
Weekday enum example - How iota is calculated - From [Learn Go Programming Blog](https://blog.learngoprogramming.com):
![How iota works](https://cdn-images-1.medium.com/max/2000/1*sfAHT3zk-WjxSDRIDMpdaA.gif)
# Articles
* [Ultimate Visual Guide to Go Enums and Iota](https://blog.learngoprogramming.com/golang-const-type-enums-iota-bc4befd096d3) _2017-10-09_

33
LUCI.md

@ -1,33 +1,4 @@
LUCI is the CI infrastructure for the Go project. The primary post-submit dashboard can be found at https://ci.chromium.org/p/golang. The Go wiki on GitHub has moved to go.dev (#61940).
# TryBots Try <https://go.dev/wiki/LUCI> or <https://go.dev/wiki/>.
Voting Commit-Queue+1 asks CQ to run the CL on the TryBots.
When the TryBots finish, CQ will reply with results,
voting either TryBot-Result+1 (pass) or TryBot-Result-1 (fail).
Important results (e.g. failures) will also appear as chips at the top
of the Gerrit page for the CL, under the commit message.
![A red box indicating the location of the checks under the commit
message on the Gerrit page for an example CL.](https://github.com/golang/go/assets/1248668/93267ff3-11cd-41f7-b268-a5cc342cfcd3)
More details about what was run are available at the "Checks" tab
on the Gerrit CL page.
![A red arrow pointing to the location of the checks tab on the
Gerrit page for an example CL.](https://github.com/golang/go/assets/1248668/1a11fa8c-14cd-4b97-968c-6c52a8634c51)
Every TryBot run includes a default set of the most common builders.
[SlowBots](https://go.dev/wiki/SlowBots) provide additional testing controls.
# Troubleshooting
## "infra failed" / purple failure
Builders that fail with "infra failed" have a purple chip rather than green (passed) or red (tests failed). These failures indicate some kind of failure in the CI infrastructure itself. They are unlikely to be due to something in your CL.
If you encounter such errors, you can reach out to [golang-dev](https://groups.google.com/g/golang-dev) for help investigating them. You may also try rerunning the build, which may succeed on a subsequent run depending on the cause of the infra failure.
## build details
The "Steps & Logs" section on a LUCI build page enumerates steps that were executed. Each step can be expanded to get to its logs, environment variables, and command line arguments. The "get go" step includes the output of `go env` from the Go toolchain used in the build.

53
Learn.md

@ -1,53 +1,4 @@
In addition to the resources available [at golang.org](https://go.dev/doc/#learning) there are a range of community-driven initiatives: The Go wiki on GitHub has moved to go.dev (#61940).
* [Boot.dev's "Learn Go"](https://boot.dev/learn/learn-golang) - Code in the browser exercises with answer checking Try <https://go.dev/wiki/Learn> or <https://go.dev/wiki/>.
* [Essential Go](https://www.programming-books.io/essential/go/) -- a free book about Go programming language.
* [Go in 5 Minutes](https://gifm.dev)
* [The Little Go Book](http://openmymind.net/The-Little-Go-Book/)
* [Tutorials Point](https://www.tutorialspoint.com/go/index.htm)
* [Exercism.io - Go](http://exercism.io/languages/go) - Online code exercises for Go for practice and mentorship.
* [EXLskills - A$AP Learn Go](https://exlskills.com/learn-en/courses/aap-learn-go-golang--learn_golang_asap) - Fast-paced free and open course for getting going with Go
* [Learn Go in an Hour - Video](https://www.youtube.com/watch?v=CF9S4QZuV30) _2015-02-15_
* [Learning to Program in Go](https://www.youtube.com/playlist?list=PLei96ZX_m9sVSEXWwZi8uwd2vqCpEm4m6), a multi-part video training class.
* [Learn Go with Tests](https://quii.gitbook.io/learn-go-with-tests/) - An introduction to Go using a TDD approach.
* [Pluralsight Classes for Go](http://www.pluralsight.com/tag/golang) - A growing collection of (paid) online classes.
* [Ardan Labs Training](https://www.ardanlabs.com/) - Commercial, live instruction for Go programming.
* [O'Reilly Go Fundamentals](http://shop.oreilly.com/category/learning-path/go-fundamentals.do) - Video learning path for Go programming.
* [Go By Example](http://gobyexample.com/) provides a series of annotated code snippets.
* [Learn Go in Y minutes](http://learnxinyminutes.com/docs/go/) is a top-to-bottom walk-through of the language.
* [Workshop-Go](https://github.com/sendwithus/workshop-go) - Startup Slam Go Workshop - examples and slides.
* [Go Fragments](http://www.gofragments.net/) - A collection of annotated Go code examples.
* [50 Shades of Go: Traps, Gotchas, Common Mistakes for New Golang Devs](http://devs.cloudimmunity.com/gotchas-and-common-mistakes-in-go-golang/index.html)
* [Free Go Language Workshop](https://www.frameworktraining.co.uk/go-language-free-training-workshop/) Framework Training is running regular free BYOD workshops in London, UK
* [Golang Tutorials](http://golangtutorials.blogspot.com/2011/05/table-of-contents.html) - A free online class.
* Rob Pike's 2011 three day course - [Day 1](http://go.googlecode.com/hg-history/release-branch.r60/doc/GoCourseDay1.pdf), [Day 2](http://go.googlecode.com/hg-history/release-branch.r60/doc/GoCourseDay2.pdf), [Day 3](http://go.googlecode.com/hg-history/release-branch.r60/doc/GoCourseDay3.pdf) (*links are broken*, use the archived links from the wayback machine. [Day 1][wbday1], [Day 2][wbday2], [Day 3][wbday3])
* [The Go Bridge Foundry](https://github.com/gobridge) - A member of the [Bridge Foundry](http://bridgefoundry.org/) family, offering a complete set of free Go training materials with the goal of bringing Go to under-served communities.
* [Golangbot](https://golangbot.com/learn-golang-series/) - Tutorials to get started with programming in Go.
* [Master Go](https://appliedgo.com/courses/mastergo/) - A paid online video course on Go for developers
* [Learn to Create Web Applications using Go](https://www.usegolang.com/) - A paid online video course and book about Web programming with Go
* [Learn Go Programming](https://blog.learngoprogramming.com) - Weekly visual and concise tutorials for programming in Go.
* [Gophercises](https://gophercises.com/) - coding exercises for budding gophers
* [Algorithms to Go](http://yourbasic.org/) - Texts about algorithms and Go, with plenty of code examples.
* [Games With Go](http://gameswithgo.org/) - Video series teaching programming fundamentals with game related projects.
* [Go Language Tutorials](https://www.cybrhome.com/topic/go-language-tutorials) - List of popular sites, blogs and tutorials for learning Go language.
* [Golang Development Video Course](https://www.youtube.com/playlist?list=PLzUGFf4GhXBL4GHXVcMMvzgtO8-WEJIoY) - A growing list of videos focused purely on Go development.
* [Go: The Complete Bootcamp Course](https://www.udemy.com/learn-go-the-complete-bootcamp-course-golang/?couponCode=GOWIKI) - Step by step and intuitive explanations for every aspect of Go using animations (Paid)
* [Learning Golang - TutorialEdge](https://tutorialedge.net/course/golang/) - A growing list of articles and courses on the fundamentals of Go.
* [Go Discourse](https://github.com/godiscourse/godiscourse) - Another forum base on Go, without framework and ORM.
* [دورة لغة غو بالعربي](https://argolang.com/learn-go-lang-beginners-course)
* [Apuntes de Golang en Español](https://apuntes.de/golang/) - Apuntes para aprender Go en Español desde Cero.
* [Go Classes at Codecademy](https://www.codecademy.com/learn/learn-go) - Online courses introducing the basics of Go.
* [Go Tutorial - W3Basic](https://www.w3basic.com/golang/) - A well organized and structured Golang Tutorials for Beginners and Professionals
[wbday1]: http://web.archive.org/web/20160305024536/http://go.googlecode.com/hg-history/release-branch.r60/doc/GoCourseDay1.pdf
[wbday2]: http://web.archive.org/web/20160305081012/http://go.googlecode.com/hg-history/release-branch.r60/doc/GoCourseDay2.pdf
[wbday3]: http://web.archive.org/web/20160305075151/http://go.googlecode.com/hg-history/release-branch.r60/doc/GoCourseDay3.pdf
Learning resources for specific topics:
* [LearnConcurrency](LearnConcurrency) outlines a course of study of Go's concurrency model and patterns.
* [LearnErrorHandling](LearnErrorHandling) links to resources about error handling in Go.
* [LearnTesting](LearnTesting) links to resources about testing in Go.
* [LearnServerProgramming](LearnServerProgramming) links to resources about server programming in Go.
* [Golang Online Courses](https://classpert.com/go-programming) - A collection of Go online courses from several providers at Classpert
* [Hackr.io Golang Tutorials](https://hackr.io/tutorials/learn-golang) - Best Golang tutorials recommended by the programming community.

47
LearnConcurrency.md

@ -1,47 +1,4 @@
This page links to resources for learning about concurrency in Go. The items are presented in order, from beginner material to advanced topics. The Go wiki on GitHub has moved to go.dev (#61940).
## Beginner Try <https://go.dev/wiki/LearnConcurrency> or <https://go.dev/wiki/>.
- Read [Effective Go: Concurrency](https://go.dev/doc/effective_go#concurrency)
- Watch [Simulating a real-world system in Go](https://www.dotconferences.com/2017/11/sameer-ajmani-simulating-a-real-world-system-in-go)
- Study [The Go Programming Language Specification](https://go.dev/ref/spec), especially
- [Go statements](https://go.dev/ref/spec#Go_statements)
- [Channel types](https://go.dev/ref/spec#Channel_types)
- [Send statements](https://go.dev/ref/spec#Send_statements)
- [Receive operator](https://go.dev/ref/spec#Receive_operator)
- [Select statements](https://go.dev/ref/spec#Select_statements)
- Code [A Tour of Go: Concurrency](http://tour.golang.org/concurrency/1)
- Read the [Frequently Asked Questions (FAQ)](https://go.dev/doc/faq), especially
- [Why build concurrency on the ideas of CSP?](https://go.dev/doc/faq#csp)
- [Why goroutines instead of threads?](https://go.dev/doc/faq#goroutines)
- [Why are map operations not defined to be atomic?](https://go.dev/doc/faq#atomic_maps)
- [What operations are atomic? What about mutexes?](https://go.dev/doc/faq#What_operations_are_atomic_What_about_mutexes)
- [Why doesn't my program run faster with more CPUs?](https://go.dev/doc/faq#parallel_slow)
- [How can I control the number of CPUs?](https://go.dev/doc/faq#number_cpus)
- [What happens with closures running as goroutines?](https://go.dev/doc/faq#closures_and_goroutines)
## Intermediate
- Study [Go by Example](https://gobyexample.com) from [goroutines](https://gobyexample.com/goroutines) through [stateful goroutines](https://gobyexample.com/stateful-goroutines)
- Watch [Go Concurrency Patterns](https://talks.golang.org/2012/concurrency.slide#1)
- Watch [A Practical Guide to Preventing Deadlocks and Leaks in Go](https://www.youtube.com/watch?v=3EW1hZ8DVyw)
- Read [Share Memory By Communicating](https://go.dev/blog/share-memory-by-communicating) and do the [codewalk](https://go.dev/doc/codewalk/sharemem/)
- Read [Go Concurrency Patterns: Timing out, moving on](https://go.dev/blog/go-concurrency-patterns-timing-out-and)
- Watch [Concurrency is not Parallelism](http://talks.golang.org/2012/waza.slide#1)
- Read [Go Concurrency Patterns: Pipelines and Cancellation](https://go.dev/blog/pipelines)
- Read [Rethinking Classical Concurrency Patterns](https://github.com/golang/go/wiki/Go-Community-Slides#rethinking-classical-concurrency-patterns)
- Study [Package sync](https://pkg.go.dev/sync/)
- Read [Introducing the Go Race Detector](https://go.dev/blog/race-detector)
- Watch [Go: code that grows with grace](http://talks.golang.org/2012/chat.slide#1)
- Read [Mutexes and Semaphores Demystified](http://www.barrgroup.com/Embedded-Systems/How-To/RTOS-Mutex-Semaphore)
## Advanced
- Watch [Advanced Go Concurrency Patterns](https://go.dev/blog/advanced-go-concurrency-patterns)
- Read [Advanced Go Concurrency Patterns](http://talks.golang.org/2013/advconc.slide#1)
- Read [Go Concurrency Patterns: Context](https://go.dev/blog/context)
- Study [The Go Memory Model](https://go.dev/ref/mem)
- Study [Package atomic](https://pkg.go.dev/sync/atomic/)
- Read [Principles of Designing Go APIs with Channels](https://inconshreveable.com/07-08-2014/principles-of-designing-go-apis-with-channels/)
- Read [Advanced Go Concurrency Primitives](https://encore.dev/blog/advanced-go-concurrency)
- Watch [The Scheduler Saga](https://www.youtube.com/watch?v=YHRO5WQGh0k)
- Read [The Scheduler Saga](https://speakerdeck.com/kavya719/the-scheduler-saga)
- Watch [Understanding Channels](https://www.youtube.com/watch?v=KBZlN0izeiY)
- Read [Understanding Channels](https://speakerdeck.com/kavya719/understanding-channels)

23
LearnErrorHandling.md

@ -1,23 +1,4 @@
This page links to resources about error handling in Go. The Go wiki on GitHub has moved to go.dev (#61940).
## Getting Started Try <https://go.dev/wiki/LearnErrorHandling> or <https://go.dev/wiki/>.
- Read [Effective Go: Errors](https://go.dev/doc/effective_go#errors)
- Code [A Tour of Go: Errors](http://tour.golang.org/methods/19) and do the [exercise](http://tour.golang.org/methods/20)
- Study [The Go Programming Language Specification: Errors](https://go.dev/ref/spec#Errors)
- Study [Package errors](https://pkg.go.dev/errors/)
- Study [func fmt.Errorf](https://pkg.go.dev/fmt/#Errorf)
## Standard Practice
- Read [Why does Go not have exceptions?](https://go.dev/doc/faq#exceptions)
- Read [Error handling and Go](https://go.dev/blog/error-handling-and-go)
- Read [Go by Example: Errors](https://gobyexample.com/errors)
- Read [Errors are values](https://go.dev/blog/errors-are-values)
- Read [Working with Errors in Go 1.13](https://go.dev/blog/go1.13-errors)
- Read [golang/go/wiki: Errors](Errors)
## Advanced Topics
- Read [Why is my nil error value not equal to nil?](https://go.dev/doc/faq#nil_error)
- Read [Defer, Panic, and Recover](https://go.dev/blog/defer-panic-and-recover)

124
LearnServerProgramming.md

@ -1,124 +1,4 @@
This page links to resources for learning about server programming in Go - both web services and mobile backends. The items are organized into sections by topic. The Go wiki on GitHub has moved to go.dev (#61940).
## Getting Started Try <https://go.dev/wiki/LearnServerProgramming> or <https://go.dev/wiki/>.
- Read [Writing Web Applications with the Go standard library](https://go.dev/doc/articles/wiki/)
- Read [Build a Web Application With Go](https://astaxie.gitbooks.io/build-web-application-with-golang/content/) from the author of the [BeeGo web framework][beego]
- Read [Webapps in Go the anti textbook](https://github.com/thewhitetulip/web-dev-golang-anti-textbook)
- Read [Building Web Applications in Go](https://codegangsta.gitbooks.io/building-web-apps-with-go/content/) from the author of the [Negroni](https://github.com/codegangsta/negroni) and [Martini](http://martini.codegangsta.io/) webserver toolkits. First learn the absolute basics before going to this book.
- Read [Building Your Own Web Framework in Go](https://www.nicolasmerouze.com/build-web-framework-golang/) a 5-part series.
- Watch [Go: code that grows with grace](http://talks.golang.org/2012/chat.slide#1)
- Download a [full working 3-tier application example](https://github.com/sourcegraph/thesrc) from the Sourcegraph Team.
### Middleware
A topic you will see discussed frequently is "middleware". If you're not familiar with that term, we suggest you start out by reading a few of these articles:
* [Middleware in Go: Best practices and examples](https://www.nicolasmerouze.com/middlewares-golang-best-practices-examples/) _2014-11-13_
* Custom Handlers [Part 1 - Avoiding Globals](http://elithrar.github.io/article/custom-handlers-avoiding-globals/), [Part 2 - Error Handling](http://elithrar.github.io/article/http-handler-error-handling-revisited/) _2014-07-16_
* [Making and Using HTTP Middleware](http://www.alexedwards.net/blog/making-and-using-middleware) _2014-10-21_
* [Writing HTTP Middleware in Go](https://justinas.org/writing-http-middleware-in-go/) _2013-10-09_
## Toolkits and Frameworks
Before you decide to adopt a third party web framework or toolkit, keep in mind that the Go standard library provides all of the tools you need to build a sophisticated, modern web application. Keeping with Go's preference for simplicity and composability over complexity and magic, we suggest you [see how far the standard library can take you](https://go.dev/doc/articles/wiki/).
If you decide you need a bit more infrastructure, start by looking at some of the toolkits and libraries available.
### Toolkits & Libraries & Microframeworks
* [Gorilla Toolkit](http://www.gorillatoolkit.org/)
* [Negroni Toolkit - Idiomatic HTTP Middleware for Go](https://github.com/codegangsta/negroni)
* [Echo Framework - Fast and Unfancy](http://echo.labstack.com/)
* [Goji Web Microframework](https://goji.io/)
* [Go Craft Middleware](https://github.com/gocraft/web)
* [Go RESTful](https://github.com/emicklei/go-restful) - Toolkit for RESTful service APIs
* [limiter](https://github.com/ulule/limiter) - Simple rate-limiting middleware for Go
* [Kite Micro-service framework](https://github.com/koding/kite)
* [Alice - Painless middleware chaining for Go](https://github.com/justinas/alice)
* [YAM - Yet Another Mux](https://github.com/thisissoon/yam)
* [Bone - Fast HTTP Router](http://go-zoo.github.io/bone/)
### Frameworks
* [BeeGo Framework][beego]
* [Frodo](https://github.com/kn9ts/frodo) - Go mini web framework inspired by Laravel(php), Slim(php) and ExpressJS(node.js)
* [GinGonic](https://gin-gonic.com/)
* [Macaron](https://github.com/Unknwon/macaron) - Productive, modular web framework in Go.
* [Revel Web Framework](https://revel.github.io/)
* [Ringo](https://github.com/jjyr/ringo) - Lightweight MVC web framework inspired by Rails, Gin.
* [Utron](https://github.com/gernest/utron) - Lightweight MVC framework for web applications.
* [Iris](https://github.com/kataras/iris/) - Fast MVC framework for web applications.
## Communication
- [Package net/http](https://pkg.go.dev/net/http) provides HTTP client and server implementations.
- [Package encoding/json](https://pkg.go.dev/encoding/json) implements encoding and decoding of JSON objects as defined in RFC 4627.
- [Package net/rpc](https://pkg.go.dev/net/rpc) provides access to the exported methods of an object across a network or other I/O connection.
- [Package os/exec](https://pkg.go.dev/os/exec) runs external commands.
## Presentation
- [Package text/template](https://pkg.go.dev/text/template) implements data-driven templates for generating textual output.
- [Package html/template](https://pkg.go.dev/html/template) implements data-driven templates for generating HTML output safe against code injection.
## Profiling and Performance
- Read [Profiling Go Programs](https://go.dev/blog/profiling-go-programs)
- Read [Arrays, slices (and strings): The mechanics of 'append'](https://go.dev/blog/slices)
- Read the [Frequently Asked Questions (FAQ)](https://go.dev/doc/faq), especially
- [Why does Go perform badly on benchmark X?](https://go.dev/doc/faq#Why_does_Go_perform_badly_on_benchmark_x)
- [Why do garbage collection? Won't it be too expensive?](https://go.dev/doc/faq#garbage_collection)
- [Package bufio](https://pkg.go.dev/bufio) implements buffered I/O.
- [Package runtime/pprof](https://pkg.go.dev/runtime/pprof) writes runtime profiling data in the format expected by the pprof visualization tool.
- [Package net/http/pprof](https://pkg.go.dev/net/http/pprof) serves via its HTTP server runtime profiling data in the format expected by the pprof visualization tool.
## Tracing, Monitoring, Logging, and Configuration
- [Package expvar](https://pkg.go.dev/expvar) provides a standardized interface to public variables, such as operation counters in servers.
- [Package flag](https://pkg.go.dev/flag) implements command-line flag parsing.
- [Package log](https://pkg.go.dev/log) implements a simple logging package.
- [Package glog](https://github.com/golang/glog) implements logging analogous to the Google-internal C++ INFO/ERROR/V setup.
## Storage
- [Package os](https://pkg.go.dev/os) provides a platform-independent interface to operating system functionality.
- [Package path/filepath](https://pkg.go.dev/path/filepath) implements utility routines for manipulating filename paths in a way compatible with the target operating system-defined file paths.
- [Package database/sql](https://pkg.go.dev/database/sql) provides a generic interface around SQL (or SQL-like) databases.
## Platforms
### Google Cloud Platform
- Read [Go, Cloud Endpoints and App Engine, Part 1](https://medium.com/google-cloud/go-cloud-endpoints-and-app-engine-19d290dafda3), [Part 2](https://medium.com/@IndianGuru/go-cloud-endpoints-and-app-engine-e3413c01c484)
- Read [Google Cloud Platform: Go Runtime Environment](https://cloud.google.com/appengine/docs/go/)
- Watch [Go and the Google Cloud Platform](https://go.dev/blog/go-and-google-cloud-platform)
- Read [Go on App Engine: tools, tests, and concurrency](https://go.dev/blog/appengine-dec2013)
- Get [Google Cloud Platform Go Libraries](https://pkg.go.dev/google.golang.org/cloud)
- Read [Deploying Go servers with Docker](https://go.dev/blog/docker)
- Search packages for [Google Cloud](https://pkg.go.dev/search?q=google+cloud) or [gcloud](https://pkg.go.dev/search?q=gcloud)
- Search packages for [App Engine](https://pkg.go.dev/search?q=appengine) or [GAE](https://pkg.go.dev/search?q=gae)
### Amazon Web Services
- The [aws-sdk-go](https://github.com/aws/aws-sdk-go) repository provides automatically generated AWS clients in Go. It has [official support](https://aws.amazon.com/blogs/aws/now-available-version-1-0-of-the-aws-sdk-for-go/) from Amazon.
- [Package goamz](https://wiki.ubuntu.com/goamz) enables Go programs to interact with the Amazon Web Services.
- Search packages for [AWS](https://pkg.go.dev/search?q=aws) or [Amazon services](https://pkg.go.dev/search?q=amazon+service)
### Microsoft Azure
- Microsoft OpenTech's [azure-sdk-for-go](https://github.com/MSOpenTech/azure-sdk-for-go) provides a Golang package that makes it easy to consume and manage Microsoft Azure Services.
- Search packages for [Azure](http://pkg.go.dev/search?q=azure)
### Openstack / Rackspace
- [Gophercloud](https://github.com/gophercloud/gophercloud) is a Golang SDK for working with OpenStack clouds.
- Search packages for [Openstack](https://pkg.go.dev/search?q=openstack) or [Rackspace](https://pkg.go.dev/search?q=rackspace)
### IBM BlueMix
- [Write your first Golang app on BlueMix](https://developer.ibm.com/bluemix/2015/10/28/getting-started-with-golang-on-bluemix/)
<!-- Common Links -->
[beego]: https://github.com/beego/beego

11
LearnTesting.md

@ -1,9 +1,4 @@
This page links to resources about testing in Go. The Go wiki on GitHub has moved to go.dev (#61940).
Try <https://go.dev/wiki/LearnTesting> or <https://go.dev/wiki/>.
- Read [How to Write Go Code](https://go.dev/doc/code), especially [Testing](https://go.dev/doc/code#Testing)
- Study [Package testing](https://pkg.go.dev/testing)
- Read [Why does Go not have assertions?](https://go.dev/doc/faq#assertions)
- Read [Where is my favorite helper function for testing?](https://go.dev/doc/faq#testing_framework)
- Watch [Testing Techniques](https://talks.golang.org/2014/testing.slide#1)
- Read [TableDrivenTests](TableDrivenTests)
- Read [Using Subtests and Sub-benchmarks](https://go.dev/blog/subtests)

13
Linux.md

@ -1,13 +1,4 @@
# Go on Linux The Go wiki on GitHub has moved to go.dev (#61940).
| **Kernel version** | **Architectures** | **Initial support version** | **Final support version** | Try <https://go.dev/wiki/Linux> or <https://go.dev/wiki/>.
|:-------------------|:----------------------|:----------------------------|:--------------------------|
| TBD | mips, mipsle | Go 1.8 | |
| TBD | s390x | Go 1.7 | |
| 4.8 or above | mips64le | Go 1.6 | |
| TBD | mips64 | Go 1.6 | |
| TBD | arm64, ppc64, ppc64le | Go 1.5 | |
| 3.1 or above | arm | Go 1.1 _*_ | |
| 2.6.23 or above | amd64, 386 | Go 1 _*_ | |
_*_ Go 1.5 or above is recommended.

263
LinuxKernelSignalVectorBug.md

@ -1,263 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
If you reached this page because of a message like this printed by a Go program: Try <https://go.dev/wiki/LinuxKernelSignalVectorBug> or <https://go.dev/wiki/>.
```
runtime: note: your Linux kernel may be buggy
runtime: note: see https://go.dev/wiki/LinuxKernelSignalVectorBug
runtime: note: mlock workaround for kernel bug failed with errno <number>
```
then you are using a Linux kernel that may have a bug.
This kernel bug may have caused memory corruption in your Go program, and may have caused your Go program to crash.
If you understand why your program crashed, then you can ignore this page.
Otherwise, this page will explain what the kernel bug is, and includes a C program that you can use to check whether your kernel has the bug.
# Bug description
A bug was introduced in Linux kernel version 5.2: if a signal is delivered to a thread, and delivering the signal requires faulting in pages of the thread signal stack, then AVX YMM registers may be corrupted upon returning from the signal to the program.
If the program was executing some function that uses the YMM registers, that function can behave unpredictably.
The bug only happens on systems with an x86 processor.
The bug affects programs written in any language.
The bug only affects programs that receive signals.
Among programs that receive signals, the bug is more likely to affect programs that use an alternate signal stack.
The bug only affects programs that use the YMM registers.
In Go programs in particular the bug will normally cause memory corruption, as Go programs primarily use the YMM registers to implement copying one memory buffer to another.
The bug [was reported to the Linux kernel developers](https://bugzilla.kernel.org/show_bug.cgi?id=205663).
It was quickly fixed.
The bug fix was not ported back to the Linux kernel 5.2 series.
The bug was fixed in Linux kernel versions 5.3.15, 5.4.2, and 5.5 and later.
The bug is only present if the kernel was compiled with GCC 9 or later.
The bug is present in vanilla Linux kernel versions 5.2.x for any x, 5.3.0 through 5.3.14, and 5.4.0 and 5.4.1.
However, many distros that are shipping those kernel versions have in fact backported the patch (which is very small).
And, some distros are still compiling their kernel with GCC 8, in which case the kernel does not have the bug.
In other words, even if your kernel is in the vulnerable range, there is a good chance that it is not vulnerable to the bug.
# Bug test
To test whether your kernel has the bug, you can run the following C program (click on "Details" to see the program).
On a buggy kernel, it will fail almost immediately.
On a kernel without the bug, it will run for 60 seconds and then exit with a 0 status.
<details>
```C
// Build with: gcc -pthread test.c
//
// This demonstrates an issue where AVX state becomes corrupted when a
// signal is delivered where the signal stack pages aren't faulted in.
//
// There appear to be three necessary ingredients, which are marked
// with "!!!" below:
//
// 1. A thread doing AVX operations using YMM registers.
//
// 2. A signal where the kernel must fault in stack pages to write the
// signal context.
//
// 3. Context switches. Having a single task isn't sufficient.
#include <errno.h>
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <pthread.h>
#include <sys/mman.h>
#include <sys/prctl.h>
#include <sys/wait.h>
static int sigs;
static stack_t altstack;
static pthread_t tid;
static void die(const char* msg, int err) {
if (err != 0) {
fprintf(stderr, "%s: %s\n", msg, strerror(err));
} else {
fprintf(stderr, "%s\n", msg);
}
exit(EXIT_FAILURE);
}
void handler(int sig __attribute__((unused)),
siginfo_t* info __attribute__((unused)),
void* context __attribute__((unused))) {
sigs++;
}
void* sender(void *arg) {
int err;
for (;;) {
usleep(100);
err = pthread_kill(tid, SIGWINCH);
if (err != 0)
die("pthread_kill", err);
}
return NULL;
}
void dump(const char *label, unsigned char *data) {
printf("%s =", label);
for (int i = 0; i < 32; i++)
printf(" %02x", data[i]);
printf("\n");
}
void doAVX(void) {
unsigned char input[32];
unsigned char output[32];
// Set input to a known pattern.
for (int i = 0; i < sizeof input; i++)
input[i] = i;
// Mix our PID in so we detect cross-process leakage, though this
// doesn't appear to be what's happening.
pid_t pid = getpid();
memcpy(input, &pid, sizeof pid);
while (1) {
for (int i = 0; i < 1000; i++) {
// !!! Do some computation we can check using YMM registers.
asm volatile(
"vmovdqu %1, %%ymm0;"
"vmovdqa %%ymm0, %%ymm1;"
"vmovdqa %%ymm1, %%ymm2;"
"vmovdqa %%ymm2, %%ymm3;"
"vmovdqu %%ymm3, %0;"
: "=m" (output)
: "m" (input)
: "memory", "ymm0", "ymm1", "ymm2", "ymm3");
// Check that input == output.
if (memcmp(input, output, sizeof input) != 0) {
dump("input ", input);
dump("output", output);
die("mismatch", 0);
}
}
// !!! Release the pages of the signal stack. This is necessary
// because the error happens when copy_fpstate_to_sigframe enters
// the failure path that handles faulting in the stack pages.
// (mmap with MMAP_FIXED also works.)
//
// (We do this here to ensure it doesn't race with the signal
// itself.)
if (madvise(altstack.ss_sp, altstack.ss_size, MADV_DONTNEED) != 0)
die("madvise", errno);
}
}
void doTest() {
// Create an alternate signal stack so we can release its pages.
void *altSigstack = mmap(NULL, SIGSTKSZ, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0);
if (altSigstack == MAP_FAILED)
die("mmap failed", errno);
altstack.ss_sp = altSigstack;
altstack.ss_size = SIGSTKSZ;
if (sigaltstack(&altstack, NULL) < 0)
die("sigaltstack", errno);
// Install SIGWINCH handler.
struct sigaction sa = {
.sa_sigaction = handler,
.sa_flags = SA_ONSTACK | SA_RESTART,
};
sigfillset(&sa.sa_mask);
if (sigaction(SIGWINCH, &sa, NULL) < 0)
die("sigaction", errno);
// Start thread to send SIGWINCH.
int err;
pthread_t ctid;
tid = pthread_self();
if ((err = pthread_create(&ctid, NULL, sender, NULL)) != 0)
die("pthread_create sender", err);
// Run test.
doAVX();
}
void *exiter(void *arg) {
sleep(60);
exit(0);
}
int main() {
int err;
pthread_t ctid;
// !!! We need several processes to cause context switches. Threads
// probably also work. I don't know if the other tasks also need to
// be doing AVX operations, but here we do.
int nproc = sysconf(_SC_NPROCESSORS_ONLN);
for (int i = 0; i < 2 * nproc; i++) {
pid_t child = fork();
if (child < 0) {
die("fork failed", errno);
} else if (child == 0) {
// Exit if the parent dies.
prctl(PR_SET_PDEATHSIG, SIGKILL, 0, 0, 0);
doTest();
}
}
// Exit after a while.
if ((err = pthread_create(&ctid, NULL, exiter, NULL)) != 0)
die("pthread_create exiter", err);
// Wait for a failure.
int status;
if (wait(&status) < 0)
die("wait", errno);
if (status == 0)
die("child unexpectedly exited with success", 0);
fprintf(stderr, "child process failed\n");
exit(1);
}
```
</details>
# What to do
If your kernel version is in the range that may contain the bug, run the C program above to see if it fails.
If it fails, your kernel is buggy.
You should upgrade to a newer kernel.
There is no workaround for this bug.
Go programs built with 1.14 will attempt to mitigate the bug by using the `mlock` system call to lock the signal stack page into memory.
This works because the bug only occurs if the signal stack page has to be faulted in.
However, this use of `mlock` can fail.
If you see the message
```
runtime: note: mlock workaround for kernel bug failed with errno 12
```
the `errno 12` (also known as `ENOMEM`) means that `mlock` failed because the system set a limit on the amount of memory that a program can lock.
If you can increase the limit, the program may succeed.
This is done using `ulimit -l`.
When running a program in a docker container, you can increase the limit by invoking docker with the option `-ulimit memlock=67108864`.
If you cannot increase the `mlock` limit, then you can make the bug less likely to interfere with your program by setting the environment variable `GODEBUG=asyncpreemptoff=1` when running a Go program.
However, this just makes your program less likely to suffer memory corruption (because it reduces the number of signals that your program will receive).
The bug is still present, and memory corruption may still occur.
# Questions?
Ask on the mailing list golang-nuts@googlegroups.com, or on any Go forum as described at [Questions](https://go.dev/wiki/Questions).
# Details
To see more details on how the bug affects Go programs and how it was detected and understood, see [#35777](https://go.dev/issue/35777) and [#35326](https://go.dev/issue/35326).

29
Livestreams.md

@ -1,29 +1,4 @@
This table attempts to collect all known regular livestreams centered around Go. Please keep each table sorted alphabetically by name. The Go wiki on GitHub has moved to go.dev (#61940).
Note that conferences and podcasts have their own wiki pages already, and should not be included here. Similarly, meetups are already collected [here](https://www.meetup.com/topics/go/). Try <https://go.dev/wiki/Livestreams> or <https://go.dev/wiki/>.
### In English
| Name | Topic (short) | Frequency | Link |
|--------------------|---------------------------------|----------------------|------|
| Ashley Jeffs | Working on Benthos and OSS | Twice per week | https://www.youtube.com/c/Jeffail |
| Chewxy | Hacking around. Usually machine learning / deep neural networks related | Weekly | https://www.youtube.com/chewxy |
| Jordan Lewis | CockroachDB internals | Twice per week | https://www.twitch.tv/large__data__bank |
| Matt Layher | Linux networking/syscalls in Go | Twice per month | https://www.twitch.tv/mdlayher |
| Matthew Dempsky | Hacking on the Go compiler | Three times per week | https://www.twitch.tv/mdempsky |
| Michael Stapelberg | Hacking on OSS projects | Aiming for 1x/month | https://www.twitch.tv/stapelberg |
| Travis Jeffery | Distributed systems and data streaming | Twice a month | https://www.twitch.tv/travisjeffery |
### In Russian
| Name | Topic (short) | Frequency | Link |
|--------------------|---------------------------------|----------------------|------|
| Good reviewer - Bad reviewer | Code review and commentary for open source projects | Weekly | [YouTube](https://www.youtube.com/channel/UC8_A5W8g7UV0pk0uL66iQAQ) |
| Generic Talks | Podcast about Go and systems programming | Weekly | [YouTube](https://www.youtube.com/channel/UCLW_8skJ-sIHXACL7HZqchA) |
### In Chinese
| Name | Topic (short) | Frequency | Link |
|--------------------|---------------------------------|----------------------|------|
| Go 夜读 - TalkGo | Weekly Go Online Meetup | Weekly | [YouTube](https://www.youtube.com/c/talkgo_night), [Bilibili](https://space.bilibili.com/326749661), [GitHub](https://github.com/talkgo/night) |

49
LockOSThread.md

@ -1,49 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
Some libraries—especially graphical frameworks and libraries like Cocoa, OpenGL, and libSDL—use thread-local state and can require functions to be called only from a specific OS thread, typically the 'main' thread. Go provides the `runtime.LockOSThread` function for this, but it's notoriously difficult to use correctly. Try <https://go.dev/wiki/LockOSThread> or <https://go.dev/wiki/>.
# Solutions
Russ Cox presented a good solution for this problem in this [thread](https://groups.google.com/d/msg/golang-nuts/IiWZ2hUuLDA/SNKYYZBelsYJ).
```Go
package sdl
// Arrange that main.main runs on main thread.
func init() {
runtime.LockOSThread()
}
// Main runs the main SDL service loop.
// The binary's main.main must call sdl.Main() to run this loop.
// Main does not return. If the binary needs to do other work, it
// must do it in separate goroutines.
func Main() {
for f := range mainfunc {
f()
}
}
// queue of work to run in main thread.
var mainfunc = make(chan func())
// do runs f on the main thread.
func do(f func()) {
done := make(chan bool, 1)
mainfunc <- func() {
f()
done <- true
}
<-done
}
```
And then other functions you write in package sdl can be like
```Go
func Beep() {
do(func() {
// whatever must run in main thread
})
}
```

228
LoopvarExperiment.md

@ -1,228 +1,4 @@
For Go 1.22, the Go team is considering changing the semantics of for loop variables to prevent unintended sharing in per-iteration closures and goroutines. Go 1.21 contains a preliminary implementation of the change, enabled by setting `GOEXPERIMENT=loopvar` when building your program. We invite anyone who wants to help us understand the effects of the change to try using `GOEXPERIMENT=loopvar` and let us know about any problems or successes encountered. The Go wiki on GitHub has moved to go.dev (#61940).
This page answers frequently asked questions about the change. Try <https://go.dev/wiki/LoopvarExperiment> or <https://go.dev/wiki/>.
## How do I try the change?
Using Go 1.21, build your program using `GOEXPERIMENT=loopvar`, as in
GOEXPERIMENT=loopvar go install my/program
GOEXPERIMENT=loopvar go build my/program
GOEXPERIMENT=loopvar go test my/program
GOEXPERIMENT=loopvar go test my/program -bench=.
...
## What is the problem this solves?
Consider a loop like:
```go
func TestAllEvenBuggy(t *testing.T) {
testCases := []int{1, 2, 4, 6}
for _, v := range testCases {
t.Run("sub", func(t *testing.T) {
t.Parallel()
if v&1 != 0 {
t.Fatal("odd v", v)
}
})
}
}
```
This test aims to check that all the test cases are even (they are not!), but it passes without `GOEXPERIMENT=loopvar`. The problem is that t.Parallel stops the closure and lets the loop continue, and then it runs all the closures in parallel when `TestAllEvenBuggy` returns. By the time the if statement in the closure executes, the loop is done, and v has its final iteration value, 6. All four subtests now continue executing in parallel, and they all check that 6 is even, instead of checking each of the test cases.
Another variant of this problem is
```go
func TestAllEven(t *testing.T) {
testCases := []int{0, 2, 4, 6}
for _, v := range testCases {
t.Run("sub", func(t *testing.T) {
t.Parallel()
if v&1 != 0 {
t.Fatal("odd v", v)
}
})
}
}
```
This test is not incorrectly passing, since 0, 2, 4, and 6 are all even, but it is also not testing whether it handles 0, 2, and 4 correctly. Like `TestAllEvenBuggy`, it tests 6 four times.
Another less common but still frequent form of this bug is capturing the loop variable in a 3-clause for loop:
```go
func Print123() {
var prints []func()
for i := 1; i <= 3; i++ {
prints = append(prints, func() { fmt.Println(i) })
}
for _, print := range prints {
print()
}
}
```
This program looks like it will print 1, 2, 3, but in fact prints 4, 4, 4.
This kind of unintended sharing bug hits all Go programmers, whether they are just starting to learn Go or have been using it for a decade. Discussion of this problem is one of the [earliest entries in the Go FAQ](https://go.dev/doc/faq#closures_and_goroutines).
Here is a [public example of a production problem caused by this kind of bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1619047), from Let's Encrypt. The code in question said:
```go
// authz2ModelMapToPB converts a mapping of domain name to authz2Models into a
// protobuf authorizations map
func authz2ModelMapToPB(m map[string]authz2Model) (*sapb.Authorizations, error) {
resp := &sapb.Authorizations{}
for k, v := range m {
// Make a copy of k because it will be reassigned with each loop.
kCopy := k
authzPB, err := modelToAuthzPB(&v)
if err != nil {
return nil, err
}
resp.Authz = append(resp.Authz, &sapb.Authorizations_MapElement{Domain: &kCopy, Authz: authzPB})
}
return resp, nil
}
```
Note the `kCopy := k` guarding against the `&kCopy` used at the end of the loop body. Unfortunately, it turns out that `modelToAuthzPB` kept a pointer to a couple fields in `v`, which is impossible to know when reading this loop.
The initial impact of this bug was that Let's Encrypt needed to [revoke over 3 million improperly-issued certificates](https://community.letsencrypt.org/t/revoking-certain-certificates-on-march-4/114864). They ended up not doing that because of the negative impact it would have had on internet security, instead [arguing for an exception](https://bugzilla.mozilla.org/show_bug.cgi?id=1619179), but that gives you a sense of the kind of impact.
The code in question was carefully reviewed when written, and the author was clearly aware of the potential problem, since they wrote `kCopy := k`, and yet it _still had a major bug_, one that is not visible unless you also know exactly what `modelToAuthzPB` does.
## What is the proposed solution?
The solution is to make loop variables declared in for loops using `:=` be a different instance of the variable on each iteration. This way, if the value is captured in a closure or goroutine or otherwise outlasts the iteration, later references to it will see the value it had during that iteration, not a value overwritten by a later iteration.
For range loops, the effect is as if each loop body starts with `k := k` and `v := v` for each range variable.
In the Let's Encrypt example above, the `kCopy := k` would not be necessary, and the bug caused by not having `v := v`
would have been avoided.
For 3-clause for loops, the effect is as if each loop body starts with `i := i` and then the reverse assignment
happens at the end of the loop body, copying the per-iteration `i` back out to the `i` that will be used to
prepare for the next iteration. This sounds complex, but in practice all common for loop idioms continue
to work exactly as they always have. The only time the loop behavior changes is when `i` is captured and shared
with something else. For example, this code runs as it always has:
```go
for i := 0;; i++ {
if i >= len(s) || s[i] == '"' {
return s[:i]
}
if s[i] == '\\' { // skip escaped char, potentially a quote
i++
}
}
```
For full details, see [the design document](https://go.googlesource.com/proposal/+/master/design/60078-loopvar.md).
## Can this change break programs?
Yes, it is possible to write programs that this change would break. For example, here is a surprising way to add the values in a list using a single-element map:
```go
func sum(list []int) int {
m := make(map[*int]int)
for _, x := range list {
m[&x] += x
}
for _, sum := range m {
return sum
}
return 0
}
```
It depends on the fact that there is only one `x` in the loop, so that `&x` is the same in each iteration. With `GOEXPERIMENT=loopvar`, `x` escapes the iteration, so `&x` is different on each iteration, and the map now has multiple entries instead of a single entry.
And here is a surprising way to print the values 0 through 9:
```go
var f func()
for i := 0; i < 10; i++ {
if i == 0 {
f = func() { print(i) }
}
f()
}
```
It depends on the fact that the `f` initialized on the first iteration “sees” the new value of `i` each time it is called. With `GOEXPERIMENT=loopvar`, it prints 0 ten times.
Although it is possible to construct artificial programs that break using `GOEXPERIMENT=loopvar`, we have yet to see any real programs
that execute incorrectly.
C# made a similar change in C# 5.0 and [they also reported](https://github.com/golang/go/discussions/56010#discussioncomment-3788526) having very few problems caused by the change.
More breaking or surprising cases are shown in [here](https://github.com/golang/go/issues/60078#issuecomment-1544324607) and [here](https://github.com/golang/go/issues/60078#issuecomment-1546019456).
## How often does the change break real programs?
Empirically, almost never. Testing on Google's codebase found many tests were fixed. It also identified some buggy tests incorrectly passing due to bad interactions between loop variables and `t.Parallel`, like in `TestAllEvenBuggy` above. We rewrote those tests to correct them.
Our experience suggests that the new semantics fixes buggy code far more often than it breaks correct code. The new semantics only caused test failures in about 1 of every 8,000 test packages (all of them incorrectly passing tests), but running the updated Go 1.20 `loopclosure` vet check over our entire code base flagged tests at a much higher rate: 1 in 400 (20 in 8,000). The `loopclosure` checker has no false positives: all the reports are buggy uses of `t.Parallel` in our source tree. That is, about 5% of the flagged tests were like `TestAllEvenBuggy`; the other 95% were like `TestAllEven`: not (yet) testing what it intended, but a correct test of correct code even with the loop variable bug fixed.
Google has been running with the new loop semantics applied to all for loops in the standard production toolchain since early May 2023 with not a single reported problem (and many cheers).
For more details about our experience at Google, see [this writeup](https://go.googlesource.com/proposal/+/master/design/60078-loopvar.md#fixes).
We also [tried the new loop semantics in Kubernetes](https://github.com/golang/go/issues/60078#issuecomment-1556058025). It identified two newly failing tests due to latent loop variable scoping-related bugs in the underlying code. For comparison, updating Kubernetes from Go 1.20 to Go 1.21 identified three newly failing tests due to reliance on undocumented behaviors in Go itself. The two tests failing due to loop variable changes are not a significant new burden compared to an ordinary release update.
## Will the change make programs slower by causing more allocations?
The vast majority of loops are unaffected. A loop only compiles differently if the loop variable has its address taken (`&i`) or is captured by a closure.
Even for affected loops, the compiler's escape analysis may determine that the loop variable can still be stack-allocated, meaning no new allocations.
However, in some cases, an extra allocation will be added. Sometimes, the extra allocation is inherent to fixing a latent bug. For example, Print123 is now allocating three separate ints (inside the closures, it turns out) instead of one, which is necessary to print the three different values after the loop finishes. In rare other cases, the loop may be correct with a shared variable and still correct with separate variables but is now allocating N different variables instead of one. In very hot loops, this might cause slowdowns. Such problems should be obvious in memory allocation profiles (using `pprof --alloc_objects`).
Benchmarking of the public “bent” bench suite showed no statistically significant performance difference over all, and we've observed no performance problems in Google's internal production use either. We expect most programs to be unaffected.
## If the proposal is accepted, how will the change be deployed?
Consistent with Go's general [approach to compatibility](https://tip.golang.org/doc/godebug), the new for loop semantics will only apply when the package being compiled is from a module that contains a `go` line declaring Go 1.22 or later, like `go 1.22` or `go 1.23`. This conservative approach ensures that _no programs will change behavior due to simply adopting the new Go toolchain_. Instead, each module author controls when their module changes to the new semantics.
The `GOEXPERIMENT=loopvar` trial mechanism does not use the declared Go language version: it applies the new semantics to every for loop in the program unconditionally. This gives a worst case behavior to help identify the maximum possible impact of the change.
## Can I see a list of places in my code affected by the change?
Yes. You can build with `-gcflags=all=-d=loopvar=2` on the command line. That will print a warning-style output line for every loop that is compiling differently, like:
$ go build -gcflags=all=-d=loopvar=2 cmd/go
...
modload/import.go:676:7: loop variable d now per-iteration, stack-allocated
modload/query.go:742:10: loop variable r now per-iteration, heap-allocated
The `all=` prints about changes to all packages in your build. If you omit the `all=`, as in `-gcflags=-d=loopvar=2`, only the
packages you name on the command line (or the package in the current directory) will emit the diagnostic.
## My test fails with the change. How can I debug it?
A new tool called `bisect` enables the change on different subsets of a program to identify which specific loops trigger a test failure when compiled with the change. If you have a failing test, `bisect` will identify the specific loop that is causing the problem. Use:
go install golang.org/x/tools/cmd/bisect@latest
bisect -compile=loopvar go test
See the [bisect transcript section of this comment](https://github.com/golang/go/issues/60078#issuecomment-1556058025) for a real-world example, and [the bisect documentation](https://pkg.go.dev/golang.org/x/tools/cmd/bisect) for more details.
## Does this mean I don’t have to write x := x in my loops anymore?
Not yet. But we hope that in a future version of Go you won't have to, perhaps even Go 1.22.
## How can I send feedback?
The [proposal issue](https://github.com/golang/go/issues/60078) is the place to discuss the proposal. However, please note that arguments about what is intuitive or natural are not productive: different people can quite reasonably have different opinions of what is intuitive or natural.
Instead, the most important feedback you can contribute to the discussion is _empirical data about using the change on real codebases_:
- What fraction of tests started failing with `GOEXPERIMENT=loopvar`?
- Were any of the newly failing tests caused by `GOEXPERIMENT=loopvar` breaking correct production code, as opposed to identifying buggy code or tests?
- Do any of your important, real-world benchmarks get significantly slower or use significantly more memory?

31
MacOS12BSDThreadRegisterIssue.md

@ -1,31 +1,4 @@
# Introduction The Go wiki on GitHub has moved to go.dev (#61940).
If you reached this page because you saw an error message like the following printed by a Go program running on macOS 12 Monterey: Try <https://go.dev/wiki/MacOS12BSDThreadRegisterIssue> or <https://go.dev/wiki/>.
```
fatal error: runtime: bsdthread_register error
runtime stack:
runtime.throw(0x20594e0, 0x21)
/usr/local/go/src/runtime/panic.go:619 +0x81 fp=0x7ff7bfeff878 sp=0x7ff7bfeff858 pc=0x1029751
runtime.goenvs()
/usr/local/go/src/runtime/os_darwin.go:129 +0x83 fp=0x7ff7bfeff8a8 sp=0x7ff7bfeff878 pc=0x10272d3
runtime.schedinit()
/usr/local/go/src/runtime/proc.go:496 +0xa4 fp=0x7ff7bfeff900 sp=0x7ff7bfeff8a8 pc=0x102c014
runtime.rt0_go(0x7ff7bfeff930, 0x3, 0x7ff7bfeff930, 0x1000000, 0x3, 0x7ff7bfeffab0, 0x7ff7bfeffabf, 0x7ff7bfeffac3, 0x0, 0x7ff7bfeffacc, ...)
/usr/local/go/src/runtime/asm_amd64.s:252 +0x1f4 fp=0x7ff7bfeff908 sp=0x7ff7bfeff900 pc=0x1052c64
```
then you are running a program built with an old version of Go (Go 1.10 or before). You will need to update your program or rebuild it with a newer version of Go.
# Details
Programs built with Go 1.10 or before use a way of issuing system calls that is no longer supported by the kernel on macOS 12 Monterey. In [Go 1.11](https://go.dev/doc/go1.11#runtime) and later, system calls are issued via `libSystem.dylib`, which is supported by the OS.
# What to do
If this is a program you downloaded or installed (for example, using Homebrew), you will need to download or install a newer version of it that is built with a newer version of Go.
If this is a program you built from source, you will need to rebuild it with a newer version of Go.
You might want to check your $PATH and manually clean up `$GOPATH/bin` and other old relevant Go binaries you've installed.
If you're trying to compile Go, `go tool dist clean` might help.

137
MethodSets.md

@ -1,137 +1,4 @@
Table of Contents The Go wiki on GitHub has moved to go.dev (#61940).
=================
+ [Introduction](#introduction) Try <https://go.dev/wiki/MethodSets> or <https://go.dev/wiki/>.
+ [The Spec](#the-spec)
+ [Usage](#usage)
+ [Variables](#variables)
+ [Slice Elements](#slice-elements)
+ [Map Elements](#map-elements)
+ [Interfaces](#interfaces)
# Introduction
Method sets of a particular type or value are of particular importance in Go, where the method set determines what interfaces a value implements.
# The Spec
There are two important clauses in the [Go Language Specification](https://go.dev/ref/spec) about method sets. They are as follows:
[Method Sets](https://go.dev/ref/spec#Method_sets):
A type may have a method set associated with it. The method set of an interface type is its interface. The method set of any other named ` type T ` consists of all methods with receiver type ` T `. The method set of the corresponding pointer type ` *T ` is the set of all methods with receiver ` *T ` or ` T ` (that is, it also contains the method set of ` T `). Any other type has an empty method set. In a method set, each method must have a unique name.
[Calls](https://go.dev/ref/spec#Calls):
A method call ` x.m() ` is valid if the method set of (the type of) ` x ` contains ` m ` and the argument list can be assigned to the parameter list of ` m `. If ` x ` is addressable and ` &x `'s method set contains ` m `, ` x.m() ` is shorthand for ` (&x).m() `.
# Usage
There are many different cases during which a method set crops up in day-to-day programming. Some of the main ones are when calling methods on variables, calling methods on slice elements, calling methods on map elements, and storing values in interfaces.
## Variables
In general, when you have a variable of a type, you can pretty much call whatever you want on it. When you combine the two rules above together, the following is valid:
```go
type List []int
func (l List) Len() int { return len(l) }
func (l *List) Append(val int) { *l = append(*l, val) }
func main() {
// A bare value
var lst List
lst.Append(1)
fmt.Printf("%v (len: %d)\n", lst, lst.Len())
// A pointer value
plst := new(List)
plst.Append(2)
fmt.Printf("%v (len: %d)\n", plst, plst.Len())
}
```
Note that both pointer and value methods can both be called on both pointer and non-pointer values. To understand why, let's examine the method sets of both types, directly from the spec:
```go
List
- Len() int
*List
- Len() int
- Append(int)
```
Notice that the method set for ` List ` does not actually contain ` Append(int) ` even though you can see from the above program that you can call the method without a problem. This is a result of the second spec section above. It implicitly translates the first line below into the second:
```go
lst.Append(1)
(&lst).Append(1)
```
Now that the value before the dot is a ` *List `, its method set includes Append, and the call is legal.
To make it easier to remember these rules, it may be helpful to simply consider the pointer- and value-receiver methods separately from the method set. It is legal to call a pointer-valued method on anything that is already a pointer or whose address can be taken (as is the case in the above example). It is legal to call a value method on anything which is a value or whose value can be dereferenced (as is the case with any pointer; this case is specified explicitly in the spec).
## Slice Elements
Slice elements are almost identical to variables. Because they are addressable, both pointer- and value-receiver methods can be called on both pointer- and value-element slices.
## Map Elements
Map elements are not addressable. Therefore, the following is an _illegal_ operation:
```go
lists := map[string]List{}
lists["primes"].Append(7) // cannot be rewritten as (&lists["primes"]).Append(7)
```
However, the following is still valid (and is the far more common case):
```go
lists := map[string]*List{}
lists["primes"] = new(List)
lists["primes"].Append(7)
count := lists["primes"].Len() // can be rewritten as (*lists["primes"]).Len()
```
Thus, both pointer- and value-receiver methods can be called on pointer-element maps, but only value-receiver methods can be called on value-element maps. This is the reason that maps with struct elements are almost always made with pointer elements.
## Interfaces
The concrete value stored in an interface is not addressable, in the same way that a map element is not addressable. Therefore, when you call a method on an interface, it must either have an identical receiver type or it must be directly discernible from the concrete type: pointer- and value-receiver methods can be called with pointers and values respectively, as you would expect. Value-receiver methods can be called with pointer values because they can be dereferenced first. Pointer-receiver methods cannot be called with values, however, because the value stored inside an interface has no address. When assigning a value to an interface, the compiler ensures that all possible interface methods can actually be called on that value, and thus trying to make an improper assignment will fail on compilation. To extend the earlier example, the following describes what is valid and what is not:
```go
type List []int
func (l List) Len() int { return len(l) }
func (l *List) Append(val int) { *l = append(*l, val) }
type Appender interface {
Append(int)
}
func CountInto(a Appender, start, end int) {
for i := start; i <= end; i++ {
a.Append(i)
}
}
type Lener interface {
Len() int
}
func LongEnough(l Lener) bool {
return l.Len()*10 > 42
}
func main() {
// A bare value
var lst List
CountInto(lst, 1, 10) // INVALID: Append has a pointer receiver
if LongEnough(lst) { // VALID: Identical receiver type
fmt.Printf(" - lst is long enough")
}
// A pointer value
plst := new(List)
CountInto(plst, 1, 10) // VALID: Identical receiver type
if LongEnough(plst) { // VALID: a *List can be dereferenced for the receiver
fmt.Printf(" - plst is long enough")
}
}
```

147
MinimumRequirements.md

@ -1,147 +1,4 @@
# Minimum Requirements The Go wiki on GitHub has moved to go.dev (#61940).
## Operating Systems Try <https://go.dev/wiki/MinimumRequirements> or <https://go.dev/wiki/>.
### [Linux](Linux)
Kernel version 2.6.32 or later. [_This depends on architecture though, we need to have specific builder for this._] Linux/ARMv5 requires much newer kernels, at least v3.1 (for `__kuser_cmpxchg64`).
We don't support CentOS 5. The kernel is too old (2.6.18).
For little-endian MIPS64, kernel version [4.1 is known to fail, and 4.8 works](https://go.dev/issue/16848).
If you are using tinyconfig (e.g. make tinyconfig) for embedded systems, you will also almost certainly enable printk in the kernel as well as a console; we will not include those generic options here. For Go, you must also enable CONFIG_FUTEX.
On arm64, an out of date (lower than version 2.33) ld.gold may cause shared library tests to fail (see https://github.com/golang/go/issues/28334).
### [Windows](Windows)
For Go 1.10: Windows XP (w/ Service Pack 3) or higher.
For Go 1.11 and later: Windows 7 and higher or Windows Server 2008 R2 and higher. We test on Windows Server 2008 R2, 2012 R2, and 2016, which are roughly Windows 7, Windows 8.1, and Windows 10.
For Go 1.21 and later: Windows 10 and higher or Windows Server 2016 and higher.
### [macOS (née OS X, aka Darwin)](Darwin)
macOS Sierra 10.12 or higher requires Go 1.7.1 or above.
macOS Monterey 12 or higher requires Go 1.11 or above.
Go 1.15 and later only support macOS Sierra 10.12 or newer; see https://go.dev/doc/go1.15#darwin.
Go 1.17 and later only support macOS High Sierra 10.13 or newer; see https://go.dev/doc/go1.17#darwin.
Go 1.21 and later will support macOS Catalina 10.15 or newer; see https://go.dev/doc/go1.20#darwin.
We have builders for macOS 10.14 through macOS 13 as of 2023-05-31.
### [OpenBSD](OpenBSD)
The current officially supported -stable versions only.
### [DragonFly BSD](DragonFly-BSD)
Generally only the latest release version only. We have a builder, but it's not the most stable of our ports.
### [FreeBSD](FreeBSD)
See https://go.dev/wiki/FreeBSD#go-on-freebsd for supported FreeBSD/Architecture/Go versions matrix.
### [NetBSD](NetBSD)
There are known NetBSD bugs (including kernel crashes) up to the current NetBSD 7.1. There is a reported fix in NetBSD 7.1.1 but it's unverified as of 2017-07-10, as we're not running builders again yet. See https://tip.golang.org/doc/go1.9#known_issues and https://github.com/golang/go/issues/20852
### [Solaris](Solaris)
illumos (former OpenSolaris 10) based distributions or Oracle Solaris 11+.
### iOS
iOS 12 or later.
## Architectures
### Microarchitecture support
For some architectures, Go supports compiling to specific microarchitectures using environment variables, e.g. GOAMD64 for go1.18 and later. Binaries will check at startup whether the requested microarchitecture level is supported. For example, a binary built with `GOAMD64=v3` will fail on a CPU that doesn't have LZCNT support.
Various microarchitecture levels and the environment variables used to select them are described with each architecture.
The build cache understands the microarchitecture environment variables and does not require any cleaning if you change them.
While performance is expected to improve when a higher minimum microarchitecture is requested, this might not be true in all cases. Benchmark your performance-critical code to verify performance improvements.
### amd64
Until Go 1.17, the Go compiler always generated x86 binaries that could be executed by any 64-bit x86 processor.
Go 1.18 introduced [4 architectural levels](https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels) for AMD64.
Each level differs in the set of x86 instructions that the compiler can include in the generated binaries:
* GOAMD64=v1 (default): The baseline. Exclusively generates instructions that all 64-bit x86 processors can execute.
* GOAMD64=v2: all v1 instructions, plus CMPXCHG16B, LAHF, SAHF, POPCNT, SSE3, SSE4.1, SSE4.2, SSSE3.
* GOAMD64=v3: all v2 instructions, plus AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, OSXSAVE.
* GOAMD64=v4: all v3 instructions, plus AVX512F, AVX512BW, AVX512CD, AVX512DQ, AVX512VL.
Setting, for example, GOAMD64=v3, will allow the Go compiler to use AVX2 instructions in the generated binaries (which may improve performance in some cases); but these binaries will not run on older x86 processors that don't support AVX2.
The Go toolchain may also generate newer instructions, but guarded by dynamic checks to ensure they're only executed on capable processors. For example, with GOAMD64=v1, [math/bits.OnesCount](https://pkg.go.dev/math/bits#OnesCount) will still use the [POPCNT](https://www.felixcloutier.com/x86/popcnt) instruction if [CPUID](https://www.felixcloutier.com/x86/cpuid) reports that it's available. Otherwise, it falls back to a generic implementation.
The Go toolchain does not currently generate any AVX512 instructions.
Note that *processor* is a simplification in this context. In practice, support from the entire system (firmware, hypervisor, kernel) is needed.
See section [Microarchitecture support](#microarchitecture-support) for hints on how to use microarchitecture environment variables like GOAMD64.
### 386
See https://go.dev/doc/install/source#environment
* GO386=sse2 (default): Any processor with at least SSE2
* GO386=softfloat: All Pentium MMX or later processors (uses software floating point emulation)
### arm
See https://go.dev/doc/install/source#environment
* GOARM=5: use software floating point; when CPU doesn't have VFP co-processor
* GOARM=6: use VFPv1 only; default if cross compiling; usually ARM11 or better cores (VFPv2 or better is also supported)
* GOARM=7: use VFPv3; usually Cortex-A cores
### arm64
All ARMv8-A processors.
### ppc64 (big endian)
POWER5 and above.
Starting with Go 1.9, only POWER8 and above are supported.
### ppc64le (little endian)
POWER8 and above.
### mips64 (big endian)
MIPS III or higher. Builder is using MIPS64r2.
### mips64le (little endian)
MIPS III or higher in little endian mode.
### s390x
z13
### mips (big endian) and mipsle (little endian)
MIPS32r1
### riscv64
rv64g (rv64imafd)
## cgo
For programs using cgo, gcc 4.6 or newer is required.

69
MinorReleases.md

@ -1,69 +1,4 @@
Our default decision should always be to not backport, but fixes for **security issues**, **serious problems with no workaround**, and **documentation fixes** are backported to the most recent two release branches, if applicable to that branch. (for example, the most current two release branches are `release-branch.go1.16` and `release-branch.go1.17`, from which new `Go 1.16.x` and `Go 1.17.x` releases are cut) Fixes for experimental ports are generally not backported. The Go wiki on GitHub has moved to go.dev (#61940).
A “serious” problem is one that prevents a program from working at all. Try <https://go.dev/wiki/MinorReleases> or <https://go.dev/wiki/>.
As soon as an interested party thinks an issue should be considered for backport, they open one or two “child” issues titled like `package: title [1.17 backport]`. The issue should include a link to the original issue and a short rationale about why the backport might be needed.
GopherBot is capable of opening the backport issues automatically in response to comments like the following on the main issue. (The keywords are `@gopherbot`, `backport`, `please` and optionally the release. The entire message is quoted in the new issue.)
> @gopherbot please consider this for backport to 1.17, it's a regression.
> @gopherbot please open the backport tracking issues. This is a severe compiler bug.
The fix is developed for the main issue, which is closed when the fix is merged to the master branch.
The child issue is assigned to the minor release milestone and labeled **CherryPickCandidate**, and its candidacy is discussed there. Once it is approved it transitions to **CherryPickApproved**. Release managers (a subset of the Go team that handles the release process) and/or code owners approve cherry-picks via an informal process.
When the child issue is labeled **CherryPickApproved**, the original author of the change fixing
that issue should immediately [create and mail a cherry-pick change](#making-cherry-pick-cls) against the release branch, which will be merged as soon as it is ready, closing the child issue.
At release time, any open backport issue which is not release-blocker is pushed to the next minor release milestone, and a minor release is minted with the already merged changes.
## Making cherry-pick CLs
_Note that only the authors of the original CL and approvers have the ability to create the cherry-pick._
Once the main fix has been submitted to master, please make a cherry-pick CL to the applicable release branch.
You can use the Gerrit UI to make a cherry-pick if there are no merge conflicts:
![Top right corner > More > Cherry-pick](https://user-images.githubusercontent.com/1225294/39773359-dc0c2b3a-52c5-11e8-836a-c518186e0ab3.png)
In the popup enter the branch name (like `release-branch.go1.10`), add the commit message prefix (like `[release-branch.go1.10]`), update the "Fixes" line and do not change any of the other automated lines.
To cherry-pick from the command line or to resolve a merge conflict, take note of the final commit hash, then use `git codereview` and `git cherry-pick` to prepare a cherry-pick CL:
```
git checkout release-branch.go1.17
git codereview change cherry-pick-NNNN
git cherry-pick $COMMIT_HASH
git commit --amend # add message prefix and change Fixes line
git codereview mail
```
**The cherry-pick CL must include a message prefix like `[release-branch.go1.10]`, and update the "Fixes" line to the child issue. Do not change or remove the "Change-Id" line nor the other Gerrit lines.**
Gerrit is configured to only allow release managers to submit to release branches, but the code review process is otherwise the usual.
At this time, it's not possible to make a cherry-pick CL by sending a [[Pull Request|GerritBot]]. Only Gerrit is supported. See [golang.org/issue/30037](https://go.dev/issue/30037).
### Cherry-pick CLs for vendored golang.org/x packages
The Go standard library includes some generated files whose source of truth is outside the main repository, in golang.org/x repositories. For example, a copy of the `golang.org/x/sys/unix` package is [vendored](https://go.googlesource.com/go/+/go1.16/src/cmd/vendor/modules.txt#45) into the Go tree, and a copy of the `golang.org/x/net/http2` package is [bundled](https://go.googlesource.com/go/+/go1.16/src/net/http/http.go#5). That means a fix to a golang.org/x package that needs to be backported to a Go release will need two corresponding CLs:
1. In the golang.org/x repository, cherry-pick the fix from the `master` branch to the `internal-branch.go1.x-vendor` branch.
The commit message should include "Updates golang/go#nnn" to mention the backport issue.
2. In the main repository on the `release-branch.go1.x` branch, create a CL that pulls in the fix from the golang.org/x internal branch:
```
go get golang.org/x/repo@internal-branch.go1.x-vendor
go mod tidy
go mod vendor
go generate -run=bundle std # If a bundled package needs regeneration.
```
The commit message should include "Fixes #nnn" to close the backport issue.
(As of Go 1.16, the golang.org/x branch name is always `internal-branch.go1.x-vendor`. In Go 1.15, the name of the golang.org/x branch is `release-branch.go1.x` or `release-branch.go1.x-bundle` in [special cases](https://go.dev/cl/305489).)

231
Mobile.md

@ -1,231 +1,4 @@
**The Go mobile subrepository adds support for mobile platforms (Android and iOS) and provides tools to build mobile applications.** The Go wiki on GitHub has moved to go.dev (#61940).
There are two strategies you can follow to include Go into your mobile stack: Try <https://go.dev/wiki/Mobile> or <https://go.dev/wiki/>.
- Writing all-Go native mobile applications.
- Writing SDK applications by generating bindings from a Go package and invoke them from Java (on Android) and Objective-C (on iOS).
This article will contain step-by-step guides to explain how to achieve
these strategies.
- [Tools](#tools)
- [Native applications](#native-applications)
- [Building and deploying to Android](#building-and-deploying-to-android)
- [Building and deploying to iOS](#building-and-deploying-to-ios)
- [App icon](#app-icon)
- [SDK applications](#sdk-applications-and-generating-bindings)
- [Building and deploying to Android](#building-and-deploying-to-android-1)
- [Building and deploying to iOS](#building-and-deploying-to-ios-1)
- [iOS Simulator](#ios-simulator)
## Tools
You need to have [Go 1.16 or above](https://go.dev/dl/) to install mobile tools.
Go Mobile introduces a tool, [`gomobile`](https://golang.org/x/mobile/cmd/gomobile),
to help you with the build and the binding process.
`gomobile` also supports [Go Modules](https://go.dev/ref/mod), e.g. using
```
$ gomobile bind -v -o android.aar -target=android ./package
```
under a project directory.
On macOS, you will need to have [Xcode Command Line Tools](https://developer.apple.com/downloads/) installed.
To install `gomobile` tools:
```
$ go install golang.org/x/mobile/cmd/gomobile@latest
$ gomobile init
```
The following sections will help you how to use the `gomobile` tool.
## Native applications
The native category includes applications entirely written in Go. Currently, the
[golang.org/x/mobile](https://pkg.go.dev/golang.org/x/mobile)
contains only a small set of packages that focus on:
* App control and configuration
* OpenGL ES 2 and ES 3 bindings
* Asset management
* Event management
* Experimental packages include OpenAL bindings, audio, font, sprite and motion sensors
There are various example native applications under [golang.org/x/mobile/example](https://golang.org/x/mobile/example). We will build and deploy the basic example both to an Android and iOS device.
Grab the application.
```
$ go get -d golang.org/x/mobile/example/basic
```
### Building and deploying to Android
Run `gomobile build` to build an Android APK.
```
$ gomobile build -target=android -androidapi 19 golang.org/x/mobile/example/basic
```
Build command will build an APK named basic.apk.
If an AndroidManifest.xml is defined in the package directory, it is added to the APK output. Otherwise, a default manifest is generated.
If you have the [adb](http://developer.android.com/tools/help/adb.html) command installed on your machine, you can use `gomobile install` to build and push the APK to your mobile device.
```
$ gomobile install golang.org/x/mobile/example/basic
```
### Building and deploying to iOS
Run `gomobile build` to build the package as an iOS application.
Note: target=ios requires the host machine running macOS. You need to obtain a [signing identity and download provisioning profiles](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingCertificates/MaintainingCertificates.html) in order to continue.
```
$ gomobile build -target=ios golang.org/x/mobile/example/basic
```
The build command will build an application bundle, named `basic.app`.
You can deploy .app files by dragging and dropping them to the device.
* In Xcode, open Window > Devices.
* Select the physical device from the left pane.
* Drag and drop the .app file to "Installed Apps" section.
* Check the "Copy items if needed" option
![Deploying app bundle](http://i.imgur.com/fRbQ0EQ.png)
Alternatively, you can deploy application bundles to your iOS device by using the [ios-deploy](https://github.com/phonegap/ios-deploy) utility command line tool. Use ios-deploy to push the application to your device.
```
$ ios-deploy -b basic.app
```
### App icon
It is possible to set an app icon by creating `assets/icon.png`.
## SDK applications and generating bindings
In this category, we will show you how you can use a Go package in
your existing Android or iOS application.
The advantages to following this strategy:
* You can reuse a Go package from a mobile app without making significant changes to your existing application.
* In cases where you want to share a common code base between your Android and iOS application, you can write the common functionality once in Go and glue them to the platform-specific code by invoking the Go package through bindings.
Current limitations are listed below.
* Only a [subset of Go types](https://pkg.go.dev/golang.org/x/mobile/cmd/gobind) are currently supported.
* Language bindings have a performance overhead.
* There are a few limitations on how the exported APIs should look due to the limitations of the target language.
We will use the example package under [golang.org/x/mobile/example/bind/hello](https://golang.org/x/mobile/example/bind/hello) to generate bindings and invoke Greetings function from Java and Objective-C.
Grab the example by running the command below.
```
$ go get -d golang.org/x/mobile/example/bind/...
```
### Building and deploying to Android
Note: Go Mobile runs on the same architectures as Go, which currently means ARM, ARM64, 386 and amd64 devices and emulators. Notably, Android on MIPS devices is not yet supported.
* Run the following command to generate the [aar](https://developer.android.com/studio/projects/android-library.html) file that is suitable for importing into Android projects:
```
$ gomobile bind -o app/hello.aar -target=android golang.org/x/mobile/example/bind/hello
```
Tips: From 1.16, it is recommended to execute `go get -d golang.org/x/mobile/cmd/gomobile` before each execution of `gomobile bind ...`. go get will automatically add indirect references to go.mod. These indirect references maybe automatically deleted by ide or go mod tidy, but they are required!
```
require (
golang.org/x/mobile v0.0.0-20210716004757-34ab1303b554 // indirect
golang.org/x/mod v0.4.2 // indirect
golang.org/x/sys v0.0.0-20210510120138-977fb7262007 // indirect
golang.org/x/tools v0.1.2 // indirect
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
)
```
* Launch Android Studio.
* File > Import Project... to import the reference project from $GOPATH/src/golang.org/x/mobile/example/bind/android.
![Android Studio](http://i.imgur.com/RhNCnnH.png)
* Build and deploy the application to the device.
The app module contains the main application that invokes the `hello.Greetings`. When the application is launched the text view is updated with the string returned value.
If you are not using Android Studio, in order to work with bindings for Android, you need to have [Android SDK](https://developer.android.com/sdk/index.html#Other) installed and ANDROID_HOME environment variable set to the SDK path. You also need the [NDK](https://developer.android.com/ndk/) installed; the easiest way is to run the SDK command `sdkmanager ndk-bundle`.
Alternatively, if you are not familiar with android development, and you do not wish to set up all the required environment (Android SDK, Gradle, etc), you can use [this](https://github.com/AgregoreWeb/gomobile-android-docker) docker image to build the application in [docker](https://www.docker.com/) instead.
Besides, if you try to add yourmodule.aar into your own project, after copy the yourmodule.aar file and yourmodule.jar file to "android\app" folder, below editing in "android\app\build.gradle" file should be done in order to make your module imported correctly.
```
+ repositories {
+ flatDir {
+ dirs '.'
+ }
+ }
```
```
dependencies {
...
+ implementation (name:'yourmodulename', ext:'aar')
}
```
### Building and deploying to iOS
Note: target=ios requires the host machine to be running macOS.
```
$ cd $GOPATH/src/golang.org/x/mobile/example/bind
$ gomobile bind -target=ios golang.org/x/mobile/example/bind/hello
```
Gomobile bind will generate a framework bundle called `Hello.framework`. Open the sample Xcode project by running the command below.
```
$ open ios/bind.xcodeproj
```
Drag and drop the `Hello.framework` bundle to the Xcode project. Check "Copy items if needed" if you need a different copy of the framework bundle within the Xcode otherwise. Otherwise, modifying the Go package source code and rerunning `gomobile bind` will update the hello.framework.
![Drag and drop Hello.framework](http://i.imgur.com/u88CxN9.png)
If you decide to keep `Hello.framework` in the main directory you have to add the main directory to the `Framework Search Paths` in the the targets Build Settings.
![Framework Search Path in Xcode Project](https://i.imgur.com/UXEM2sj.png)
Your project layout should look like what's shown below.
![Xcode project layout with Hello.framework](http://i.imgur.com/JhcSKwC.png)
Build and run it on the simulator or an actual device (Cmd+R). When the application launches, the label on the main view will be modified with the string returned from `GoHelloGreetings` which invokes the `hello.Greetings` function.
Note that you can also invoke `GoHelloGreetings` from Swift by importing Hello.
```swift
@import Hello
// ...
let msg = Hello.GoHelloGreetings("gopher")
```
#### iOS Simulator
As of Go 1.5, only darwin/amd64 works on the iOS simulator. To use the simulator, you need to configure Xcode to only try to run 64-bit binaries.
Xcode matches the bit width of the ARM binaries when running on the X86 simulator. That is, if you configure Xcode to build both 32-bit and 64-bit ARM binaries (the default), it will attempt to run 32-bit X86 binaries on the simulator, which will not work with Go today. Modify the Xcode build settings to only build 64-bit ARM binaries, and the simulator will run the amd64 binary.

1451
Modules.md

File diff suppressed because it is too large Load Diff

34
MutexOrChannel.md

@ -1,34 +1,4 @@
# Use a sync.Mutex or a channel? The Go wiki on GitHub has moved to go.dev (#61940).
One of Go's mottos is _"Share memory by communicating, don't communicate by sharing memory."_ Try <https://go.dev/wiki/MutexOrChannel> or <https://go.dev/wiki/>.
That said, Go does provide traditional locking mechanisms in the <a href='https://pkg.go.dev/sync/'>sync package</a>. Most locking issues can be solved using either channels or traditional locks.
So which should you use?
Use whichever is most expressive and/or most simple.
A common Go newbie mistake is to over-use channels and goroutines just because it's possible, and/or because it's fun. Don't be afraid to use a <a href='https://pkg.go.dev/sync/#Mutex'><code>sync.Mutex</code></a> if that fits your problem best. Go is pragmatic in letting you use the tools that solve your problem best and not forcing you into one style of code.
As a general guide, though:
| **Channel** | **Mutex** |
|:------------|:----------|
| passing ownership of data,<br />distributing units of work,<br /> communicating async results | caches,<br />state |
If you ever find your sync.Mutex locking rules are getting too complex, ask yourself whether using channel(s) might be simpler.
### Wait Group
Another important synchronisation primitive is sync.WaitGroup. These allow co-operating goroutines to collectively wait for a threshold event before proceeding independently again. This is useful typically in two cases.
Firstly, when 'cleaning up', a sync.WaitGroup can be used to ensure that all goroutines - including the main one - wait before all terminating cleanly.
The second more general case is of a cyclic algorithm that involves a set of goroutines that all work independently for a while, then all wait on a barrier, before proceeding independently again. This pattern might be repeated many times. Data might be exchanged at the barrier event. This strategy is the basis of [Bulk Synchronous Parallelism](https://en.wikipedia.org/wiki/Bulk_synchronous_parallel) (BSP).
Channel communication, mutexes and wait-groups are complementary and can be combined.
### More Info
* Channels in Effective Go: https://go.dev/doc/effective_go#channels
* The sync package: https://pkg.go.dev/sync/

28
NetBSD.md

@ -1,28 +1,4 @@
# Go on NetBSD The Go wiki on GitHub has moved to go.dev (#61940).
Go on NetBSD is fairly stable on the architectures below. However, some bugs remain; see the [issue tracker](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3AOS-NetBSD) for details. Try <https://go.dev/wiki/NetBSD> or <https://go.dev/wiki/>.
| **Kernel version** | **Architectures** | **Initial support version** | **Final support version** |
|:----------------------|:------------------|:----------------------------|:--------------------------|
| 8.0 or above | amd64, arm, 386 | | |
| 7.0 through 7.1 | amd64, arm, 386 | Go 1.3 _*_ | |
| 6.0 through 6.1 | amd64, arm, 386 | Go 1.3 _*_ | Go 1.9.7 |
| 5.0 through 5.2 (EOL) | amd64, 386 | Go 1 | Go 1.2.2 |
_*_ Go 1.5 or above is recommended.
Support for the arm64 architecture is a work in progress, see https://go.dev/issue/30824.
# Go packages in pkgsrc
[pkgsrc](https://pkgsrc.org/), the NetBSD package collection, contains up-to-date packages for released Go versions. The packages contain the version in the name (e.g. [`lang/go113`](http://pkgsrc.se/lang/go113)) so that multiple versions can be installed in parallel. [`lang/go`](http://pkgsrc.se/lang/go) is a meta-package that always depends on the default go version.
Note that the `go` binary name is also installed with a version suffix. Install the [`pkgtools/pkg_alternatives`](http://pkgsrc.se/pkgtools/pkg_alternatives) package to get a `go` command symlink in your PATH.
There are a number of packages for software written in Go in pkgsrc. At the moment, module-based builds are experimental, and packages are built using a GOPATH layout.
# Preparing NetBSD for Go
* install NetBSD (remember to install pkgsrc in the last step)
* install shells/bash and devel/git (do ` make package-install clean ` in ` /usr/pkgsrc/shells/bash ` and ` /usr/pkgsrc/devel/git `.
* Using binary packages: ` pkgin install bash git `

49
NewSpeakers.md

@ -1,49 +1,4 @@
# Resources for New Speakers The Go wiki on GitHub has moved to go.dev (#61940).
Go needs everyone's help. Try <https://go.dev/wiki/NewSpeakers> or <https://go.dev/wiki/>.
We want to see more new speakers with new perspectives at Go conferences,
especially more women and others underrepresented in the Go community.
The process of applying to speak at a tech conference can be a bit opaque and confusing
for first-time speakers.
In general, please remember that, first and foremost,
conferences organizers want to find great talks;
there is no single format or recipe for a great talk;
and you need not be a Go expert to give a great talk.
All that you need to be is excited about sharing something
you've observed or learned about using Go.
Here are some good blog posts with tips for writing conference talk proposals:
- “[How to write a successful conference proposal](https://dave.cheney.net/2017/02/12/how-to-write-a-successful-conference-proposal)” by Dave Cheney
- “[How to write a successful conference proposal](https://medium.com/@fox/how-to-write-a-successful-conference-proposal-4461509d3e32)” by Karolina Szczur
- “[Is your conference proposal good enough?](http://rckbt.me/2014/01/conference-proposals/)” by Raquel Vélez (rockbot)
- “[What your conference proposal is missing](http://www.sarahmei.com/blog/2014/04/07/what-your-conference-proposal-is-missing/)” by Sarah Mei
Elsewhere on the wiki, we maintain a list of [upcoming conferences](Conferences) with links to CFPs.
The same page also lists past conferences with links to talk videos. These conferences welcome speakers of all experience levels and backgrounds!
## Contact Us
We, the Go community members listed below,
are happy to discuss or review talk proposals
and answer other questions about the overall speaking process.
Feel free to contact any of us directly.
- Russ Cox, rsc@golang.org, [@_rsc](https://twitter.com/_rsc)
- Steve Francia, spf@golang.org, [@spf13](https://twitter.com/spf13)
- William Kennedy, bill@ardanlabs.com, [@goinggodotnet](https://twitter.com/goinggodotnet)
- Cassandra Salisbury, cassandra@golangbridge.org, [@cassandraoid](https://twitter.com/cassandraoid)
- Ashley McNamara, ashmc@microsoft.com, [@ashleymcnamara](https://twitter.com/ashleymcnamara)
- Brian Ketelsen, bjk@microsoft.com, [@bketelsen](https://twitter.com/bketelsen)
- Natalie Pistunovich natalie@golangbridge.org, [@nataliepis](https://twitter.com/nataliepis)
- Erik St. Martin, erikstm@microsoft.com, [@erikstmartin](https://twitter.com/erikstmartin)
- Francesc Campoy, campoy@golang.org, [@francesc](https://twitter.com/francesc)
- Sameer Ajmani, sameer@google.com, [@Sajma](https://twitter.com/Sajma)
- Florin Pățan, florinpatan@gmail.com, [@dlsniper](https://twitter.com/dlsniper)
- Aaron Schlesinger, arschles@gmail.com, [@arschles](https://twitter.com/arschles)
- Paul Jolly, paul@myitcv.io [@_myitcv](https://twitter.com/_myitcv)
- Alexey Palazhchenko, alexey.palazhchenko@gmail.com [@paaleksey](https://twitter.com/paaleksey) (English, Russian)
- Carmen Andoh, candoh@google.com, [@carmatrocity](https://twitter.com/carmatrocity)
(Experienced speakers, feel free to add your contact information to the list, or email rsc@golang.org if you don't have wiki edit permission.)

31
NoPlusOne.md

@ -1,31 +1,4 @@
When contributing to the Go issue tracker, please **do not** make comments like this: The Go wiki on GitHub has moved to go.dev (#61940).
> +1 Try <https://go.dev/wiki/NoPlusOne> or <https://go.dev/wiki/>.
or
> :+1:
or
> Me too.
or
> I too would like to see this issue fixed.
or
> When is this issue going to be fixed?
Such comments do not help fix issues. In fact, they make it harder by cluttering the discussion. The project admins will delete such comments as a matter of procedure (please don't be offended if we delete yours).
Instead of commenting, you may [add a :+1: reaction](https://help.github.com/articles/about-discussions-in-issues-and-pull-requests/#reacting-to-ideas-in-issues-and-pull-requests) to the comment or issue.
Of course, **please do comment** if your "me too" comment includes information that might help resolve the issue. This includes reports like this:
> This issue also affects me on Windows 10 when running all.bat at revision c0ff33.
(Although there's no need to make such a comment if an identical comment already exists.)
Thanks!

71
NonEnglish.md

@ -1,71 +1,4 @@
Some of this documentation may be out of date. The Go wiki on GitHub has moved to go.dev (#61940).
## Belarusian - Беларуская Try <https://go.dev/wiki/NonEnglish> or <https://go.dev/wiki/>.
* [faq-be](http://www.designcontest.com/show/faq-be) - Frequently Asked Questions.
## Brazilian Portuguese - Português brasileiro
* [A Tour of Go](https://go-tour-br.appspot.com/)
* [golangbr.org](http://golangbr.org/) - Go documentation and news.
## Chinese - 中文
* [Go 语言之旅](https://tour.go-zh.org/)
* [Go 编程语言](https://go-zh.org/) - Chinese Translation of tip.golang.org
* [Effective Go and (old) Tutorial (Deprecated)](http://code.google.com/p/ac-me/downloads/detail?name=fango.pdf)
## Czech - Čeština
* [Pravidla reflexe](http://www.abclinuxu.cz/clanky/google-go-pravidla-reflexe) - a translation of [The Laws of Reflection](https://go.dev/blog/2011/09/laws-of-reflection.html).
## French - Français
* [golang-france](http://code.google.com/p/golang-france/) - Go documentation.
## German - Deutsch
* [Deutschsprachige Go Themenseite - German Go resource page](https://github.com/hweidner/golang-de/wiki)
* [Deutschsprachiges Diskussionsforum - German discussion forum](https://mewe.com/group/5c4b0dcb1c1ea52d0c45b6b0) on [MeWe](https://mewe.com)
([Invitation link](https://mewe.com/join/golang-de)) (requires free registration on MeWe.com).
## Indonesia
* [Komunitas Pengguna Go Indonesia](https://golang-id.org)
## Japanese - 日本語
* [A Tour of Go](https://go-tour-jp.appspot.com/)
* [CodeReviewComments](https://knsh14.github.io/translations/go-codereview-comments/)
## Korean - 한국어
* [A Tour of Go](http://go-tour-kr.appspot.com)
* [golang-kr wiki](http://github.com/golang-kr/golang-doc/wiki) - Korean Translation of golang.org/doc
## Russian - русский язык
* [Effective Go](https://github.com/Konstantin8105/Effective_Go_RU/blob/master/README.md)
* [Contribution Guide](https://github.com/Konstantin8105/Contribution_Guide_RU)
## Spanish - español
* [Video course: Go Course from 0 to 100](https://www.youtube.com/watch?v=7SIIyt5-XK0&list=PLl_hIu4u7P64MEJpR3eVwQ1l_FtJq4a5g)
* [Workshop video: Creating a wiki with Go](https://www.youtube.com/watch?v=0fYb43gIl6I&list=PLfHn_OMWQAHDNxoA3BRWs5NHcstZMAY_B)
* [Sitio web: Go con ejemplos](http://goconejemplos.com/)
* [Apuntes: Aprender de Go desde Cero](https://apuntes.de/golang/)
## Thai - ไทย
* [A Tour of Go](https://go-tour-th.appspot.com)
## Turkish - Türkçe
* [A Tour of Go](https://go-tour-turkish.appspot.com)
## Vietnamese - Tiếng Việt
* [A Tour of Go](http://go-tour-vi.appspot.com/)
## Uzbek — Ўзбекча
* [A Tour of Go](http://go-tour-uz.appspot.com/)

Some files were not shown because too many files have changed in this diff Show More