doc: mention stack allocation of variable-sized make calls

Also mention the bisect tool and flag used to track down
incorrect uses.

Change-Id: Id36a236e1bb2733b8611b22a5b16916e7d9f5522
Reviewed-on: https://go-review.googlesource.com/c/go/+/666075
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Keith Randall <khr@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/doc/next/5-toolchain.md b/doc/next/5-toolchain.md
index c270e9dfc96c7cffff71a97557c5d7c7238f215f..3708700c93bf772912ec35a7ec9f9a0fb8340aaa 100644 (file)
--- a/doc/next/5-toolchain.md
+++ b/doc/next/5-toolchain.md
@@ -38,6 +38,18 @@ successfully in Go 1.25. If this change is affecting your code, the solution is
 the non-nil error check earlier in your code, preferably immediately after
 the error-generating statement.
 
+<!-- CLs 653856, 657937, 663795, TBD 664299 -->
+
+The compiler can now allocate the backing store for slices on the
+stack in more situations, which improves performance. This change has
+the potential to amplify the effects of incorrect
+[unsafe.Pointer](/pkg/unsafe#Pointer) usage, see for example [issue
+73199](/issue/73199). In order to track down these problems, the
+[bisect tool](https://pkg.go.dev/golang.org/x/tools/cmd/bisect) can be
+used to find the allocation causing trouble using the
+`-compile=variablemake` flag. All such new stack allocations can also
+be turned off using `-gcflags=all=-d=variablemakehash=n`.
+
 ## Assembler {#assembler}
 
 ## Linker {#linker}