Adding upstream version 1.18.10.upstream/1.18.10upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1338 insertions, 0 deletions

diff --git a/doc/go1.18.html b/doc/go1.18.html
new file mode 100644
index 0000000..b320579
--- /dev/null
+++ b/doc/go1.18.html
@@ -0,0 +1,1338 @@
+<!--{
+	"Title": "Go 1.18 Release Notes",
+	"Path":  "/doc/go1.18"
+}-->
+
+<!--
+NOTE: In this document and others in this directory, the convention is to
+set fixed-width phrases with non-fixed-width spaces, as in
+<code>hello</code> <code>world</code>.
+Do not send CLs removing the interior tags from such phrases.
+-->
+
+<style>
+  main ul li { margin: 0.5em 0; }
+</style>
+
+<h2 id="introduction">DRAFT RELEASE NOTES — Introduction to Go 1.18</h2>
+
+<p>
+  <strong>
+    Go 1.18 is not yet released. These are work-in-progress
+    release notes. Go 1.18 is expected to be released in February 2022.
+  </strong>
+</p>
+
+<h2 id="language">Changes to the language</h2>
+
+<h3 id="generics">Generics</h3>
+
+<p><!-- https://golang.org/issue/43651, https://golang.org/issue/45346 -->
+  Go 1.18 includes an implementation of generic features as described by the
+  <a href="https://go.googlesource.com/proposal/+/refs/heads/master/design/43651-type-parameters.md">Type
+    Parameters Proposal</a>.
+  This includes major - but fully backward-compatible - changes to the language.
+</p>
+
+<p>
+  These new language changes required a large amount of new code that
+  has not had significant testing in production settings. That will
+  only happen as more people write and use generic code. We believe
+  that this feature is well implemented and high quality. However,
+  unlike most aspects of Go, we can't back up that belief with real
+  world experience. Therefore, while we encourage the use of generics
+  where it makes sense, please use appropriate caution when deploying
+  generic code in production.
+</p>
+
+<p>
+  The following is a list of the most visible changes. For a more comprehensive overview, see the
+  <a href="https://go.googlesource.com/proposal/+/refs/heads/master/design/43651-type-parameters.md">proposal</a>.
+  For details see the <a href="/ref/spec">language spec</a>.
+</p>
+
+<ul>
+  <li>
+    The syntax for
+    <a href="/ref/spec#Function_declarations">function</a> and
+    <a href="/ref/spec#Type_declarations">type declarations</a>
+    now accepts
+    <a href="/ref/spec#Type_parameters">type parameters</a>.
+  </li>
+  <li>
+    Parameterized functions and types can be instantiated by following them with a list of
+    type arguments in square brackets.
+  </li>
+  <li>
+    The new token <code>~</code> has been added to the set of
+    <a href="/ref/spec#Operators_and_punctuation">operators and punctuation</a>.
+  </li>
+  <li>
+    The syntax for
+    <a href="/ref/spec#Interface_types">Interface types</a>
+    now permits the embedding of arbitrary types (not just type names of interfaces)
+    as well as union and <code>~T</code> type elements. Such interfaces may only be used
+    as type constraints.
+    An interface now defines a set of types as well as a set of methods.
+  </li>
+  <li>
+    The new
+    <a href="/ref/spec#Predeclared_identifiers">predeclared identifier</a>
+    <code>any</code> is an alias for the empty interface. It may be used instead of
+    <code>interface{}</code>.
+  </li>
+  <li>
+    The new
+    <a href="/ref/spec#Predeclared_identifiers">predeclared identifier</a>
+    <code>comparable</code> is an interface that denotes the set of all types which can be
+    compared using <code>==</code> or <code>!=</code>. It may only be used as (or embedded in)
+    a type constraint.
+  </li>
+</ul>
+
+<p>
+  There are three experimental packages using generics that may be
+  useful.
+  These packages are in x/exp repository; their API is not covered by
+  the Go 1 guarantee and may change as we gain more experience with
+  generics.
+  <dl>
+    <dt><a href="https://pkg.go.dev/golang.org/x/exp/constraints"><code>golang.org/x/exp/constraints</code></a></dt>
+    <dd>
+      <p>
+	Constraints that are useful for generic code, such as
+	<a href="https://pkg.go.dev/golang.org/x/exp/constraints#Ordered"><code>constraints.Ordered</code></a>.
+      </p>
+    </dd>
+
+    <dt><a href="https://pkg.go.dev/golang.org/x/exp/slices"><code>golang.org/x/exp/slices</code></a></dt>
+    <dd>
+      <p>
+	A collection of generic functions that operate on slices of
+	any element type.
+      </p>
+    </dd>
+
+    <dt><a href="https://pkg.go.dev/golang.org/x/exp/maps"><code>golang.org/x/exp/maps</code></a></dt>
+    <dd>
+      <p>
+	A collection of generic functions that operate on maps of
+	any key or element type.
+      </p>
+    </dd>
+  </dl>
+</p>
+
+<p>
+  The current generics implementation has the following limitations:
+  <ul>
+    <li><!-- https://golang.org/issue/47631 -->
+      The Go compiler cannot currently handle type declarations inside generic functions
+      or methods. We hope to provide support for this feature in Go 1.19.
+    </li>
+    <li><!-- https://golang.org/issue/50937 -->
+      The Go compiler currently does not accept arguments of type parameter type with
+      the predeclared functions <code>real</code>, <code>imag</code>, and <code>complex</code>.
+      We hope to remove this restriction in Go 1.19.
+    </li>
+    <li><!-- https://golang.org/issue/51183 -->
+      The Go compiler currently only supports calling a method <code>m</code> on a value
+      <code>x</code> of type parameter type <code>P</code> if <code>m</code> is explicitly
+      declared by <code>P</code>'s constraint interface.
+      Similarly, method values <code>x.m</code> and method expressions
+      <code>P.m</code> also are only supported if <code>m</code> is explicitly
+      declared by <code>P</code>, even though <code>m</code> might be in the method set
+      of <code>P</code> by virtue of the fact that all types in <code>P</code> implement
+      <code>m</code>. We hope to remove this restriction in Go 1.19.
+    </li>
+    <li><!-- https://golang.org/issue/49030 -->
+      Embedding a type parameter, or a pointer to a type parameter, as
+      an unnamed field in a struct type is not permitted. Similarly,
+      embedding a type parameter in an interface type is not permitted.
+      Whether these will ever be permitted is unclear at present.
+    </li>
+    <li>
+      A union element with more than one term may not contain an
+      interface type with a non-empty method set. Whether this will
+      ever be permitted is unclear at present.
+    </li>
+  </ul>
+</p>
+
+<h3 id="bug_fixes">Bug fixes</h3>
+
+<p>
+  The Go 1.18 compiler now correctly reports <code>declared but not used</code> errors
+  for variables that are set inside a function literal but are never used. Before Go 1.18,
+  the compiler did not report an error in such cases. This fixes long-outstanding compiler
+  issue <a href="https://golang.org/issue/8560">#8560</a>. As a result of this change,
+  (possibly incorrect) programs may not compile anymore. The necessary fix is
+  straightforward: fix the program if it was in fact incorrect, or use the offending
+  variable, for instance by assigning it to the blank identifier <code>_</code>.
+  Since <code>go vet</code> always pointed out this error, the number of affected
+  programs is likely very small.
+</p>
+
+<p>
+  The Go 1.18 compiler now reports an overflow when passing a rune constant expression
+  such as <code>'1' &lt;&lt; 32</code> as an argument to the predeclared functions
+  <code>print</code> and <code>println</code>, consistent with the behavior of
+  user-defined functions. Before Go 1.18, the compiler did not report an error
+  in such cases but silently accepted such constant arguments if they fit into an
+  <code>int64</code>. As a result of this change, (possibly incorrect) programs
+  may not compile anymore. The necessary fix is straightforward: fix the program if it
+  was in fact incorrect, or explicitly convert the offending argument to the correct type.
+  Since <code>go vet</code> always pointed out this error, the number of affected
+  programs is likely very small.
+</p>
+
+<h2 id="ports">Ports</h2>
+
+<h3 id="amd64">AMD64</h3>
+
+<p><!-- CL 349595 -->
+  Go 1.18 introduces the new <code>GOAMD64</code> environment variable, which selects at compile time
+  a minimum target version of the AMD64 architecture. Allowed values are <code>v1</code>,
+  <code>v2</code>, <code>v3</code>, or <code>v4</code>. Each higher level requires,
+  and takes advantage of, additional processor features. A detailed
+  description can be found
+  <a href="https://golang.org/wiki/MinimumRequirements#amd64">here</a>.
+</p>
+<p>
+  The <code>GOAMD64</code> environment variable defaults to <code>v1</code>.
+</p>
+
+<h3 id="riscv">RISC-V</h3>
+
+<p><!-- golang.org/issue/47100, CL 334872 -->
+  The 64-bit RISC-V architecture on Linux (the <code>linux/riscv64</code> port)
+  now supports the <code>c-archive</code> and <code>c-shared</code> build modes.
+</p>
+
+<h3 id="linux">Linux</h3>
+
+<p><!-- golang.org/issue/45964 -->
+  Go 1.18 requires Linux kernel version 2.6.32 or later.
+</p>
+
+<h3 id="windows">Windows</h3>
+
+<p><!-- https://golang.org/issue/49759 -->
+  The <code>windows/arm</code> and <code>windows/arm64</code> ports now support
+  non-cooperative preemption, bringing that capability to all four Windows
+  ports, which should hopefully address subtle bugs encountered when calling
+  into Win32 functions that block for extended periods of time.
+</p>
+
+<h3 id="ios">iOS</h3>
+
+<p><!-- golang.org/issue/48076, golang.org/issue/49616 -->
+  On iOS (the <code>ios/arm64</code> port)
+  and iOS simulator running on AMD64-based macOS (the <code>ios/amd64</code> port),
+  Go 1.18 now requires iOS 12 or later; support for previous versions has been discontinued.
+</p>
+
+<h3 id="freebsd">FreeBSD</h3>
+
+<p>
+  Go 1.18 is the last release that is supported on FreeBSD 11.x, which has
+  already reached end-of-life. Go 1.19 will require FreeBSD 12.2+ or FreeBSD
+  13.0+.
+  FreeBSD 13.0+ will require a kernel with the COMPAT_FREEBSD12 option set (this is the default).
+</p>
+
+<h2 id="tools">Tools</h2>
+
+<h3 id="fuzzing">Fuzzing</h3>
+
+<p>
+  Go 1.18 includes an implementation of fuzzing as described by
+  <a href="https://golang.org/issue/44551">the fuzzing proposal</a>.
+</p>
+
+<p>
+  See the <a href="https://go.dev/doc/fuzz">fuzzing landing page</a> to get
+  started.
+</p>
+
+<p>
+  Please be aware that fuzzing can consume a lot of memory and may impact your
+  machine’s performance while it runs. Also be aware that the fuzzing engine
+  writes values that expand test coverage to a fuzz cache directory within
+  <code>$GOCACHE/fuzz</code> while it runs. There is currently no limit to the
+  number of files or total bytes that may be written to the fuzz cache, so it
+  may occupy a large amount of storage (possibly several GBs).
+</p>
+
+<h3 id="go-command">Go command</h3>
+
+<h4 id="go-get"><code>go</code> <code>get</code></h4>
+
+<p><!-- golang.org/issue/43684 -->
+  <code>go</code> <code>get</code> no longer builds or installs packages in
+  module-aware mode. <code>go</code> <code>get</code> is now dedicated to
+  adjusting dependencies in <code>go.mod</code>. Effectively, the
+  <code>-d</code> flag is always enabled. To install the latest version
+  of an executable outside the context of the current module, use
+  <a href="https://golang.org/ref/mod#go-install"><code>go</code>
+  <code>install</code> <code>example.com/cmd@latest</code></a>. Any
+  <a href="https://golang.org/ref/mod#version-queries">version query</a>
+  may be used instead of <code>latest</code>. This form of <code>go</code>
+  <code>install</code> was added in Go 1.16, so projects supporting older
+  versions may need to provide install instructions for both <code>go</code>
+  <code>install</code> and <code>go</code> <code>get</code>. <code>go</code>
+  <code>get</code> now reports an error when used outside a module, since there
+  is no <code>go.mod</code> file to update. In GOPATH mode (with
+  <code>GO111MODULE=off</code>), <code>go</code> <code>get</code> still builds
+  and installs packages, as before.
+</p>
+
+<h4 id="go-mod-updates">Automatic <code>go.mod</code> and <code>go.sum</code> updates</h4>
+
+<p><!-- https://go.dev/issue/45551 -->
+  The <code>go</code> <code>mod</code> <code>graph</code>,
+  <code>go</code> <code>mod</code> <code>vendor</code>,
+  <code>go</code> <code>mod</code> <code>verify</code>, and
+  <code>go</code> <code>mod</code> <code>why</code> subcommands
+  no longer automatically update the <code>go.mod</code> and
+  <code>go.sum</code> files.
+  (Those files can be updated explicitly using <code>go</code> <code>get</code>,
+  <code>go</code> <code>mod</code> <code>tidy</code>, or
+  <code>go</code> <code>mod</code> <code>download</code>.)
+</p>
+
+<h4 id="go-version"><code>go</code> <code>version</code></h4>
+
+<p><!-- golang.org/issue/37475 -->
+  The <code>go</code> command now embeds version control information in
+  binaries. It includes the currently checked-out revision, commit time, and a
+  flag indicating whether edited or untracked files are present. Version
+  control information is embedded if the <code>go</code> command is invoked in
+  a directory within a Git, Mercurial, Fossil, or Bazaar repository, and the
+  <code>main</code> package and its containing main module are in the same
+  repository. This information may be omitted using the flag
+  <code>-buildvcs=false</code>.
+</p>
+
+<p><!-- golang.org/issue/37475 -->
+  Additionally, the <code>go</code> command embeds information about the build,
+  including build and tool tags (set with <code>-tags</code>), compiler,
+  assembler, and linker flags (like <code>-gcflags</code>), whether cgo was
+  enabled, and if it was, the values of the cgo environment variables
+  (like <code>CGO_CFLAGS</code>).
+  Both VCS and build information may be read together with module
+  information using
+  <code>go</code> <code>version</code> <code>-m</code> <code>file</code> or
+  <code>runtime/debug.ReadBuildInfo</code> (for the currently running binary)
+  or the new <a href="#debug/buildinfo"><code>debug/buildinfo</code></a>
+  package.
+</p>
+
+<p><!-- CL 369977 -->
+  The underlying data format of the embedded build information can change with
+  new go releases, so an older version of <code>go</code> may not handle the
+  build information produced with a newer version of <code>go</code>.
+  To read the version information from a binary built with <code>go</code> 1.18,
+  use the <code>go</code> <code>version</code> command and the
+  <code>debug/buildinfo</code> package from <code>go</code> 1.18+.
+</p>
+
+<h4 id="go-mod-download"><code>go</code> <code>mod</code> <code>download</code></h4>
+
+<p><!-- https://golang.org/issue/44435 -->
+  If the main module's <code>go.mod</code> file
+  specifies <a href="/ref/mod#go-mod-file-go"><code>go</code> <code>1.17</code></a>
+  or higher, <code>go</code> <code>mod</code> <code>download</code> without
+  arguments now downloads source code for only the modules
+  explicitly <a href="/ref/mod#go-mod-file-require">required</a> in the main
+  module's <code>go.mod</code> file. (In a <code>go</code> <code>1.17</code> or
+  higher module, that set already includes all dependencies needed to build the
+  packages and tests in the main module.)
+  To also download source code for transitive dependencies, use
+  <code>go</code> <code>mod</code> <code>download</code> <code>all</code>.
+</p>
+
+<h4 id="go-mod-vendor"><code>go</code> <code>mod</code> <code>vendor</code></h4>
+
+<p><!-- https://golang.org/issue/47327 -->
+  The <code>go</code> <code>mod</code> <code>vendor</code> subcommand now
+  supports a <code>-o</code> flag to set the output directory.
+  (Other <code>go</code> commands still read from the <code>vendor</code>
+  directory at the module root when loading packages
+  with <code>-mod=vendor</code>, so the main use for this flag is for
+  third-party tools that need to collect package source code.)
+</p>
+
+<h4 id="go-mod-tidy"><code>go</code> <code>mod</code> <code>tidy</code></h4>
+
+<p><!-- https://golang.org/issue/47738, CL 344572 -->
+  The <code>go</code> <code>mod</code> <code>tidy</code> command now retains
+  additional checksums in the <code>go.sum</code> file for modules whose source
+  code is needed to verify that each imported package is provided by only one
+  module in the <a href="/ref/mod#glos-build-list">build list</a>. Because this
+  condition is rare and failure to apply it results in a build error, this
+  change is <em>not</em> conditioned on the <code>go</code> version in the main
+  module's <code>go.mod</code> file.
+</p>
+
+<h4 id="go-work"><code>go</code> <code>work</code></h4>
+
+<p><!-- https://golang.org/issue/45713 -->
+  The <code>go</code> command now supports a "Workspace" mode. If a
+  <code>go.work</code> file is found in the working directory or a
+  parent directory, or one is specified using the <code>GOWORK</code>
+  environment variable, it will put the <code>go</code> command into workspace mode.
+  In workspace mode, the <code>go.work</code> file will be used to
+  determine the set of main modules used as the roots for module
+  resolution, instead of using the normally-found <code>go.mod</code>
+  file to specify the single main module. For more information see the
+  <a href="/pkg/cmd/go#hdr-Workspace_maintenance"><code>go work</code></a>
+  documentation.
+</p>
+
+<h4 id="go-build-asan"><code>go</code> <code>build</code> <code>-asan</code></h4>
+
+<p><!-- CL 298612 -->
+  The <code>go</code> <code>build</code> command and related commands
+  now support an <code>-asan</code> flag that enables interoperation
+  with C (or C++) code compiled with the address sanitizer (C compiler
+  option <code>-fsanitize=address</code>).
+</p>
+
+<h4 id="go-test"><code>go</code> <code>test</code></h4>
+
+<p><!-- CL 251441 -->
+  The <code>go</code> command now supports additional command line
+  options for the new <a href="#fuzzing">fuzzing support described
+  above</a>:
+  <ul>
+    <li>
+      <code>go test</code> supports
+      <code>-fuzz</code>, <code>-fuzztime</code>, and
+      <code>-fuzzminimizetime</code> options.
+      For documentation on these see
+      <a href="/pkg/cmd/go#hdr-Testing_flags"><code>go help testflag</code></a>.
+    </li>
+    <li>
+      <code>go clean</code> supports a <code>-fuzzcache</code>
+      option.
+      For documentation see
+      <a href="/pkg/cmd/go#hdr-Remove_object_files_and_cached_files"><code>go help clean</code></a>.
+    </li>
+  </ul>
+</p>
+
+<h4 id="go-build-lines"><code>//go:build</code> lines</h4>
+
+<p><!-- CL 240611 -->
+Go 1.17 introduced <code>//go:build</code> lines as a more readable way to write build constraints,
+instead of <code>//</code> <code>+build</code> lines.
+As of Go 1.17, <code>gofmt</code> adds <code>//go:build</code> lines
+to match existing <code>+build</code> lines and keeps them in sync,
+while <code>go</code> <code>vet</code> diagnoses when they are out of sync.
+</p>
+
+<p>Since the release of Go 1.18 marks the end of support for Go 1.16,
+all supported versions of Go now understand <code>//go:build</code> lines.
+In Go 1.18, <code>go</code> <code>fix</code> now removes the now-obsolete
+<code>//</code> <code>+build</code> lines in modules declaring
+<code>go</code> <code>1.17</code> or later in their <code>go.mod</code> files.
+</p>
+
+<p>
+For more information, see <a href="https://go.dev/design/draft-gobuild">https://go.dev/design/draft-gobuild</a>.
+</p>
+
+<h3 id="gofmt">Gofmt</h3>
+
+<p><!-- https://golang.org/issue/43566 -->
+  <code>gofmt</code> now reads and formats input files concurrently, with a
+  memory limit proportional to <code>GOMAXPROCS</code>. On a machine with
+  multiple CPUs, <code>gofmt</code> should now be significantly faster.
+</p>
+
+<h3 id="vet">Vet</h3>
+
+<h4 id="vet-generics">Updates for Generics</h4>
+
+<p><!-- https://golang.org/issue/48704 -->
+	The <code>vet</code> tool is updated to support generic code. In most cases,
+	it reports an error in generic code whenever it would report an error in the
+	equivalent non-generic code after substituting for type parameters with a
+	type from their
+	<a href="https://golang.org/ref/spec#Interface_types">type set</a>.
+
+	For example, <code>vet</code> reports a format error in
+	<pre>func Print[T ~int|~string](t T) {
+	fmt.Printf("%d", t)
+}</pre>
+	because it would report a format error in the non-generic equivalent of
+	<code>Print[string]</code>:
+	<pre>func PrintString(x string) {
+	fmt.Printf("%d", x)
+}</pre>
+</p>
+
+<h4 id="vet-precision">Precision improvements for existing checkers</h4>
+
+<p><!-- CL 323589 356830 319689 355730 351553 338529 -->
+  The <code>cmd/vet</code> checkers <code>copylock</code>, <code>printf</code>,
+  <code>sortslice</code>, <code>testinggoroutine</code>, and <code>tests</code>
+  have all had moderate precision improvements to handle additional code patterns.
+  This may lead to newly reported errors in existing packages. For example, the
+  <code>printf</code> checker now tracks formatting strings created by
+  concatenating string constants. So <code>vet</code> will report an error in:
+<pre>
+  // fmt.Printf formatting directive %d is being passed to Println.
+  fmt.Println("%d"+` ≡ x (mod 2)`+"\n", x%2)
+</pre>
+</p>
+
+<h2 id="runtime">Runtime</h2>
+
+<p><!-- https://golang.org/issue/44167 -->
+  The garbage collector now includes non-heap sources of garbage collector work
+  (e.g., stack scanning) when determining how frequently to run. As a result,
+  garbage collector overhead is more predictable when these sources are
+  significant. For most applications these changes will be negligible; however,
+  some Go applications may now use less memory and spend more time on garbage
+  collection, or vice versa, than before. The intended workaround is to tweak
+  <code>GOGC</code> where necessary.
+</p>
+
+<p><!-- CL 358675, CL 353975, CL 353974 -->
+  The runtime now returns memory to the operating system more efficiently and has
+  been tuned to work more aggressively as a result.
+</p>
+
+<p><!-- CL 352057, https://golang.org/issue/45728 -->
+  Go 1.17 generally improved the formatting of arguments in stack traces,
+  but could print inaccurate values for arguments passed in registers.
+  This is improved in Go 1.18 by printing a question mark (<code>?</code>)
+  after each value that may be inaccurate.
+</p>
+
+<h2 id="compiler">Compiler</h2>
+
+<p><!-- https://golang.org/issue/40724 -->
+  Go 1.17 <a href="go1.17#compiler">implemented</a> a new way of passing
+  function arguments and results using registers instead of the stack
+  on 64-bit x86 architecture on selected operating systems.
+  Go 1.18 expands the supported platforms to include 64-bit ARM (<code>GOARCH=arm64</code>),
+  big- and little-endian 64-bit PowerPC (<code>GOARCH=ppc64</code>, <code>ppc64le</code>),
+  as well as 64-bit x86 architecture (<code>GOARCH=amd64</code>)
+  on all operating systems.
+  On 64-bit ARM and 64-bit PowerPC systems, benchmarking shows
+  typical performance improvements of 10% or more.
+</p>
+
+<p>
+  As <a href="go1.17#compiler">mentioned</a> in the Go 1.17 release notes,
+  this change does not affect the functionality of any safe Go code and
+  is designed to have no impact on most assembly code. See the
+  <a href="go1.17#compiler">Go 1.17 release notes</a> for more details.
+</p>
+
+<p><!-- CL 355497, CL 356869 -->
+  The compiler now can inline functions that contain range loops or
+  labeled for loops.
+</p>
+
+<p><!-- CL 298611 -->
+  The new <code>-asan</code> compiler option supports the
+  new <code>go</code> command <code>-asan</code> option.
+</p>
+
+<p><!-- https://golang.org/issue/50954 -->
+  Because the compiler's type checker was replaced in its entirety to
+  support generics, some error messages now may use different wording
+  than before. In some cases, pre-Go 1.18 error messages provided more
+  detail or were phrased in a more helpful way.
+  We intend to address these cases in Go 1.19.
+</p>
+
+<p> <!-- https://github.com/golang/go/issues/49569 -->
+  Because of changes in the compiler related to supporting generics, the
+  Go 1.18 compile speed can be roughly 15% slower than the Go 1.17 compile speed.
+  The execution time of the compiled code is not affected.  We
+  intend to improve the speed of the compiler in Go 1.19.
+</p>
+
+<h2 id="linker">Linker</h2>
+
+<p>
+  The linker emits <a href="https://tailscale.com/blog/go-linker/">far fewer relocations</a>.
+  As a result, most codebases will link faster, require less memory to link,
+  and generate smaller binaries.
+  Tools that process Go binaries should use Go 1.18's <code>debug/gosym</code> package
+  to transparently handle both old and new binaries.
+</p>
+
+<p><!-- CL 298610 -->
+  The new <code>-asan</code> linker option supports the
+  new <code>go</code> command <code>-asan</code> option.
+</p>
+
+<h2 id="bootstrap">Bootstrap</h2>
+
+<p><!-- CL 369914, CL 370274 -->
+When building a Go release from source and <code>GOROOT_BOOTSTRAP</code>
+is not set, previous versions of Go looked for a Go 1.4 or later bootstrap toolchain
+in the directory <code>$HOME/go1.4</code> (<code>%HOMEDRIVE%%HOMEPATH%\go1.4</code> on Windows).
+Go now looks first for <code>$HOME/go1.17</code> or <code>$HOME/sdk/go1.17</code>
+before falling back to <code>$HOME/go1.4</code>.
+We intend for Go 1.19 to require Go 1.17 or later for bootstrap,
+and this change should make the transition smoother.
+For more details, see <a href="https://go.dev/issue/44505">go.dev/issue/44505</a>.
+</p>
+
+<h2 id="library">Core library</h2>
+
+<h3 id="debug/buildinfo">New <code>debug/buildinfo</code> package</h3>
+
+<p><!-- golang.org/issue/39301 -->
+  The new <a href="/pkg/debug/buildinfo"><code>debug/buildinfo</code></a> package
+  provides access to module versions, version control information, and build
+  flags embedded in executable files built by the <code>go</code> command.
+  The same information is also available via
+  <a href="/pkg/runtime/debug#ReadBuildInfo"><code>runtime/debug.ReadBuildInfo</code></a>
+  for the currently running binary and via <code>go</code>
+  <code>version</code> <code>-m</code> on the command line.
+</p>
+
+<h3 id="netip">New <code>net/netip</code> package</h3>
+
+<p>
+  The new <a href="/pkg/net/netip/"><code>net/netip</code></a>
+  package defines a new IP address type, <a href="/pkg/net/netip/#Addr"><code>Addr</code></a>.
+  Compared to the existing
+  <a href="/pkg/net/#IP"><code>net.IP</code></a> type, the <code>netip.Addr</code> type takes less
+  memory, is immutable, and is comparable so it supports <code>==</code>
+  and can be used as a map key.
+</p>
+<p>
+  In addition to <code>Addr</code>, the package defines
+  <a href="/pkg/net/netip/#AddrPort"><code>AddrPort</code></a>, representing
+  an IP and port, and
+  <a href="/pkg/net/netip/#Prefix"><code>Prefix</code></a>, representing
+  a network CIDR prefix.
+</p>
+<p>
+  The package also defines several functions to create and examine
+  these new types:
+  <a href="/pkg/net/netip#AddrFrom4"><code>AddrFrom4</code></a>,
+  <a href="/pkg/net/netip#AddrFrom16"><code>AddrFrom16</code></a>,
+  <a href="/pkg/net/netip#AddrFromSlice"><code>AddrFromSlice</code></a>,
+  <a href="/pkg/net/netip#AddrPortFrom"><code>AddrPortFrom</code></a>,
+  <a href="/pkg/net/netip#IPv4Unspecified"><code>IPv4Unspecified</code></a>,
+  <a href="/pkg/net/netip#IPv6LinkLocalAllNodes"><code>IPv6LinkLocalAllNodes</code></a>,
+  <a href="/pkg/net/netip#IPv6Unspecified"><code>IPv6Unspecified</code></a>,
+  <a href="/pkg/net/netip#MustParseAddr"><code>MustParseAddr</code></a>,
+  <a href="/pkg/net/netip#MustParseAddrPort"><code>MustParseAddrPort</code></a>,
+  <a href="/pkg/net/netip#MustParsePrefix"><code>MustParsePrefix</code></a>,
+  <a href="/pkg/net/netip#ParseAddr"><code>ParseAddr</code></a>,
+  <a href="/pkg/net/netip#ParseAddrPort"><code>ParseAddrPort</code></a>,
+  <a href="/pkg/net/netip#ParsePrefix"><code>ParsePrefix</code></a>,
+  <a href="/pkg/net/netip#PrefixFrom"><code>PrefixFrom</code></a>.
+</p>
+<p>
+  The <a href="/pkg/net/"><code>net</code></a> package includes new
+  methods that parallel existing methods, but
+  return <code>netip.AddrPort</code> instead of the
+  heavier-weight <a href="/pkg/net/#IP"><code>net.IP</code></a> or
+  <a href="/pkg/net/#UDPAddr"><code>*net.UDPAddr</code></a> types:
+  <a href="/pkg/net/#Resolver.LookupNetIP"><code>Resolver.LookupNetIP</code></a>,
+  <a href="/pkg/net/#UDPConn.ReadFromUDPAddrPort"><code>UDPConn.ReadFromUDPAddrPort</code></a>,
+  <a href="/pkg/net/#UDPConn.ReadMsgUDPAddrPort"><code>UDPConn.ReadMsgUDPAddrPort</code></a>,
+  <a href="/pkg/net/#UDPConn.WriteToUDPAddrPort"><code>UDPConn.WriteToUDPAddrPort</code></a>,
+  <a href="/pkg/net/#UDPConn.WriteMsgUDPAddrPort"><code>UDPConn.WriteMsgUDPAddrPort</code></a>.
+  The new <code>UDPConn</code> methods support allocation-free I/O.
+</p>
+<p>
+  The <code>net</code> package also now includes functions and methods
+  to convert between the existing
+  <a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>/<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>
+  types and <code>netip.AddrPort</code>:
+  <a href="/pkg/net/#TCPAddrFromAddrPort"><code>TCPAddrFromAddrPort</code></a>,
+  <a href="/pkg/net/#UDPAddrFromAddrPort"><code>UDPAddrFromAddrPort</code></a>,
+  <a href="/pkg/net/#TCPAddr.AddrPort"><code>TCPAddr.AddrPort</code></a>,
+  <a href="/pkg/net/#UDPAddr.AddrPort"><code>UDPAddr.AddrPort</code></a>.
+</p>
+
+<h3 id="tls10">TLS 1.0 and 1.1 disabled by default client-side</h3>
+
+<p><!-- CL 359779, golang.org/issue/45428 -->
+  If <a href="/pkg/crypto/tls/#Config.MinVersion"><code>Config.MinVersion</code></a>
+  is not set, it now defaults to TLS 1.2 for client connections. Any safely
+  up-to-date server is expected to support TLS 1.2, and browsers have required
+  it since 2020. TLS 1.0 and 1.1 are still supported by setting
+  <code>Config.MinVersion</code> to <code>VersionTLS10</code>.
+  The server-side default is unchanged at TLS 1.0.
+</p>
+
+<p>
+  The default can be temporarily reverted to TLS 1.0 by setting the
+  <code>GODEBUG=tls10default=1</code> environment variable.
+  This option will be removed in Go 1.19.
+</p>
+
+<h3 id="sha1">Rejecting SHA-1 certificates</h3>
+
+<p><!-- CL 359777, golang.org/issue/41682 -->
+  <code>crypto/x509</code> will now
+  reject certificates signed with the SHA-1 hash function. This doesn't
+  apply to self-signed root certificates. Practical attacks against SHA-1
+  <a href="https://shattered.io/">have been demonstrated since 2017</a> and publicly
+  trusted Certificate Authorities have not issued SHA-1 certificates since 2015.
+</p>
+
+<p>
+  This can be temporarily reverted by setting the
+  <code>GODEBUG=x509sha1=1</code> environment variable.
+  This option will be removed in Go 1.19.
+</p>
+
+<h3 id="minor_library_changes">Minor changes to the library</h3>
+
+<p>
+  As always, there are various minor changes and updates to the library,
+  made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
+  in mind.
+</p>
+
+<dl id="bufio"><dt><a href="/pkg/bufio/">bufio</a></dt>
+  <dd>
+    <p><!-- CL 345569 -->
+      The new <a href="/pkg/bufio#Writer.AvailableBuffer"><code>Writer.AvailableBuffer</code></a>
+      method returns an empty buffer with a possibly non-empty capacity for use
+      with append-like APIs. After appending, the buffer can be provided to a
+      succeeding <code>Write</code> call and possibly avoid any copying.
+    </p>
+
+    <p><!-- CL 345570 -->
+      The <a href="/pkg/bufio#Reader.Reset"><code>Reader.Reset</code></a> and
+      <a href="/pkg/bufio#Writer.Reset"><code>Writer.Reset</code></a> methods
+      now use the default buffer size when called on objects with a
+      <code>nil</code> buffer.
+    </p>
+  </dd>
+</dl><!-- bufio -->
+
+<dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
+  <dd>
+    <p><!-- CL 351710 -->
+      The new <a href="/pkg/bytes/#Cut"><code>Cut</code></a> function
+      slices a <code>[]byte</code> around a separator. It can replace
+      and simplify many common uses of
+      <a href="/pkg/bytes/#Index"><code>Index</code></a>,
+      <a href="/pkg/bytes/#IndexByte"><code>IndexByte</code></a>,
+      <a href="/pkg/bytes/#IndexRune"><code>IndexRune</code></a>,
+      and <a href="/pkg/bytes/#SplitN"><code>SplitN</code></a>.
+    </p>
+
+    <p><!-- CL 323318, CL 332771 -->
+      <a href="/pkg/bytes/#Trim"><code>Trim</code></a>, <a href="/pkg/bytes/#TrimLeft"><code>TrimLeft</code></a>,
+      and <a href="/pkg/bytes/#TrimRight"><code>TrimRight</code></a> are now allocation free and, especially for
+      small ASCII cutsets, up to 10 times faster.
+    </p>
+
+    <p><!-- CL 359485 -->
+      The <a href="/pkg/bytes/#Title"><code>Title</code></a> function is now deprecated. It doesn't
+      handle Unicode punctuation and language-specific capitalization rules, and is superseded by the
+      <a href="https://golang.org/x/text/cases">golang.org/x/text/cases</a> package.
+    </p>
+  </dd>
+</dl><!-- bytes -->
+
+<dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
+  <dd>
+    <p><!-- CL 320071, CL 320072, CL 320074, CL 361402, CL 360014 -->
+      The <a href="/pkg/crypto/elliptic#P224"><code>P224</code></a>,
+      <a href="/pkg/crypto/elliptic#P384"><code>P384</code></a>, and
+      <a href="/pkg/crypto/elliptic#P521"><code>P521</code></a> curve
+      implementations are now all backed by code generated by the
+      <a href="https://github.com/mmcloughlin/addchain">addchain</a> and
+      <a href="https://github.com/mit-plv/fiat-crypto">fiat-crypto</a>
+      projects, the latter of which is based on a formally-verified model
+      of the arithmetic operations. They now use safer complete formulas
+      and internal APIs. P-224 and P-384 are now approximately four times
+      faster. All specific curve implementations are now constant-time.
+    </p>
+
+    <p>
+      Operating on invalid curve points (those for which the
+      <code>IsOnCurve</code> method returns false, and which are never returned
+      by <a href="/pkg/crypto/elliptic#Unmarshal"><code>Unmarshal</code></a> or
+      a <code>Curve</code> method operating on a valid point) has always been
+      undefined behavior, can lead to key recovery attacks, and is now
+      unsupported by the new backend. If an invalid point is supplied to a
+      <code>P224</code>, <code>P384</code>, or <code>P521</code> method, that
+      method will now return a random point. The behavior might change to an
+      explicit panic in a future release.
+    </p>
+  </dd>
+</dl><!-- crypto/elliptic -->
+
+<dl id="crypto/tls"><dt><a href="/pkg/crypto/tls/">crypto/tls</a></dt>
+  <dd>
+    <p><!-- CL 325250 -->
+      The new <a href="/pkg/crypto/tls/#Conn.NetConn"><code>Conn.NetConn</code></a>
+      method allows access to the underlying
+      <a href="/pkg/net#Conn"><code>net.Conn</code></a>.
+    </p>
+  </dd>
+</dl><!-- crypto/tls -->
+
+<dl id="crypto/x509"><dt><a href="/pkg/crypto/x509">crypto/x509</a></dt>
+  <dd>
+    <p><!-- CL 353132, CL 353403 -->
+      <a href="/pkg/crypto/x509/#Certificate.Verify"><code>Certificate.Verify</code></a>
+      now uses platform APIs to verify certificate validity on macOS and iOS when it
+      is called with a nil
+      <a href="/pkg/crypto/x509/#VerifyOpts.Roots"><code>VerifyOpts.Roots</code></a>
+      or when using the root pool returned from
+      <a href="/pkg/crypto/x509/#SystemCertPool"><code>SystemCertPool</code></a>.
+    </p>
+
+    <p><!-- CL 353589 -->
+      <a href="/pkg/crypto/x509/#SystemCertPool"><code>SystemCertPool</code></a>
+      is now available on Windows.
+    </p>
+
+    <p>
+      On Windows, macOS, and iOS, when a
+      <a href="/pkg/crypto/x509/#CertPool"><code>CertPool</code></a> returned by
+      <a href="/pkg/crypto/x509/#SystemCertPool"><code>SystemCertPool</code></a>
+      has additional certificates added to it,
+      <a href="/pkg/crypto/x509/#Certificate.Verify"><code>Certificate.Verify</code></a>
+      will do two verifications: one using the platform verifier APIs and the
+      system roots, and one using the Go verifier and the additional roots.
+      Chains returned by the platform verifier APIs will be prioritized.
+    </p>
+
+    <p>
+      <a href="/pkg/crypto/x509/#CertPool.Subjects"><code>CertPool.Subjects</code></a>
+      is deprecated. On Windows, macOS, and iOS the
+      <a href="/pkg/crypto/x509/#CertPool"><code>CertPool</code></a> returned by
+      <a href="/pkg/crypto/x509/#SystemCertPool"><code>SystemCertPool</code></a>
+      will return a pool which does not include system roots in the slice
+      returned by <code>Subjects</code>, as a static list can't appropriately
+      represent the platform policies and might not be available at all from the
+      platform APIs.
+    </p>
+  </dd>
+</dl>
+
+<dl id="debug/dwarf"><dt><a href="/pkg/debug/dwarf/">debug/dwarf</a></dt>
+  <dd>
+    <p><!-- CL 380714 -->
+      The <a href="/pkg/debug/dwarf#StructField"><code>StructField</code></a>
+      and <a href="/pkg/debug/dwarf#BasicType"><code>BasicType</code></a>
+      structs both now have a <code>DataBitOffset</code> field, which
+      holds the value of the <code>DW_AT_data_bit_offset</code>
+      attribute if present.
+  </dd>
+</dl>
+
+<dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
+  <dd>
+    <p><!-- CL 352829 -->
+      The <a href="/pkg/debug/elf/#R_PPC64_RELATIVE"><code>R_PPC64_RELATIVE</code></a>
+      constant has been added.
+    </p>
+  </dd>
+</dl><!-- debug/elf -->
+
+<dl id="debug/plan9obj"><dt><a href="/pkg/debug/plan9obj/">debug/plan9obj</a></dt>
+  <dd>
+    <p><!-- CL 350229 -->
+      The <a href="/pkg/debug/plan9obj#File.Symbols">File.Symbols</a>
+      method now returns the new exported error
+      value <a href="/pkg/debug/plan9obj#ErrNoSymbols">ErrNoSymbols</a>
+      if the file has no symbol section.
+    </p>
+  </dd>
+</dl><!-- debug/plan9obj -->
+
+<dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
+  <dd>
+    <p><!-- https://golang.org/issue/47781, CL 325689, CL 327149, CL 348375, CL 348609 -->
+      Per the proposal
+      <a href="https://go.googlesource.com/proposal/+/master/design/47781-parameterized-go-ast.md">
+        Additions to go/ast and go/token to support parameterized functions and types
+      </a>
+      the following additions are made to the <a href="/pkg/go/ast"><code>go/ast</code></a> package:
+      <ul>
+        <li>
+          the <a href="/pkg/go/ast/#FuncType"><code>FuncType</code></a>
+          and <a href="/pkg/go/ast/#TypeSpec"><code>TypeSpec</code></a>
+          nodes have a new field <code>TypeParams</code> to hold type parameters, if any.
+        </li>
+        <li>
+          The new expression node <a href="/pkg/go/ast/#IndexListExpr"><code>IndexListExpr</code></a>
+          represents index expressions with multiple indices, used for function and type instantiations
+          with more than one explicit type argument.
+        </li>
+      </ul>
+    </p>
+  </dd>
+</dl>
+
+<dl id="go/constant"><dt><a href="/pkg/go/constant/">go/constant</a></dt>
+  <dd>
+    <p><!-- https://golang.org/issue/46211, CL 320491 -->
+      The new <a href="/pkg/go/constant/#Kind.String"><code>Kind.String</code></a>
+      method returns a human-readable name for the receiver kind.
+    </p>
+  </dd>
+</dl>
+
+<dl id="go/token"><dt><a href="/pkg/go/token/">go/token</a></dt>
+  <dd>
+    <p><!-- https://golang.org/issue/47781, CL 324992 -->
+      The new constant <a href="/pkg/go/token/#TILDE"><code>TILDE</code></a>
+      represents the <code>~</code> token per the proposal
+      <a href="https://go.googlesource.com/proposal/+/master/design/47781-parameterized-go-ast.md">
+        Additions to go/ast and go/token to support parameterized functions and types
+      </a>.
+    </p>
+  </dd>
+</dl>
+
+<dl id="go/types"><dt><a href="/pkg/go/types/">go/types</a></dt>
+  <dd>
+    <p><!-- https://golang.org/issue/46648 -->
+      The new <a href="/pkg/go/types/#Config.GoVersion"><code>Config.GoVersion</code></a>
+      field sets the accepted Go language version.
+    </p>
+
+    <p><!-- https://golang.org/issue/47916 -->
+      Per the proposal
+      <a href="https://go.googlesource.com/proposal/+/master/design/47916-parameterized-go-types.md">
+        Additions to go/types to support type parameters
+      </a>
+      the following additions are made to the <a href="/pkg/go/types"><code>go/types</code></a> package:
+    </p>
+    <ul>
+      <li>
+        The new type
+        <a href="/pkg/go/types/#TypeParam"><code>TypeParam</code></a>, factory function
+        <a href="/pkg/go/types/#NewTypeParam"><code>NewTypeParam</code></a>,
+        and associated methods are added to represent a type parameter.
+      </li>
+      <li>
+        The new type
+        <a href="/pkg/go/types/#TypeParamList"><code>TypeParamList</code></a> holds a list of
+        type parameters.
+      </li>
+      <li>
+        The new type
+        <a href="/pkg/go/types/#TypeList"><code>TypeList</code></a> holds a list of types.
+      </li>
+      <li>
+        The new factory function
+        <a href="/pkg/go/types/#NewSignatureType"><code>NewSignatureType</code></a> allocates a
+        <a href="/pkg/go/types/#Signature"><code>Signature</code></a> with
+        (receiver or function) type parameters.
+        To access those type parameters, the <code>Signature</code> type has two new methods
+        <a href="/pkg/go/types/#Signature.RecvTypeParams"><code>Signature.RecvTypeParams</code></a> and
+        <a href="/pkg/go/types/#Signature.TypeParams"><code>Signature.TypeParams</code></a>.
+      </li>
+      <li>
+        <a href="/pkg/go/types/#Named"><code>Named</code></a> types have four new methods:
+        <a href="/pkg/go/types/#Named.Origin"><code>Named.Origin</code></a> to get the original
+        parameterized types of instantiated types,
+        <a href="/pkg/go/types/#Named.TypeArgs"><code>Named.TypeArgs</code></a> and
+        <a href="/pkg/go/types/#Named.TypeParams"><code>Named.TypeParams</code></a> to get the
+        type arguments or type parameters of an instantiated or parameterized type, and
+        <a href="/pkg/go/types/#Named.TypeParams"><code>Named.SetTypeParams</code></a> to set the
+        type parameters (for instance, when importing a named type where allocation of the named
+        type and setting of type parameters cannot be done simultaneously due to possible cycles).
+      </li>
+      <li>
+        The <a href="/pkg/go/types/#Interface"><code>Interface</code></a> type has four new methods:
+        <a href="/pkg/go/types/#Interface.IsComparable"><code>Interface.IsComparable</code></a> and
+        <a href="/pkg/go/types/#Interface.IsMethodSet"><code>Interface.IsMethodSet</code></a> to
+        query properties of the type set defined by the interface, and
+        <a href="/pkg/go/types/#Interface.MarkImplicit"><code>Interface.MarkImplicit</code></a> and
+        <a href="/pkg/go/types/#Interface.IsImplicit"><code>Interface.IsImplicit</code></a> to set
+        and test whether the interface is an implicit interface around a type constraint literal.
+      </li>
+      <li>
+        The new types
+        <a href="/pkg/go/types/#Union"><code>Union</code></a> and
+        <a href="/pkg/go/types/#Term"><code>Term</code></a>, factory functions
+        <a href="/pkg/go/types/#NewUnion"><code>NewUnion</code></a> and
+        <a href="/pkg/go/types/#NewTerm"><code>NewTerm</code></a>, and associated
+        methods are added to represent type sets in interfaces.
+      </li>
+      <li>
+        The new function
+        <a href="/pkg/go/types/#Instantiate"><code>Instantiate</code></a>
+        instantiates a parameterized type.
+      </li>
+      <li>
+        The new <a href="/pkg/go/types/#Info.Instances"><code>Info.Instances</code></a>
+        map records function and type instantiations through the new
+        <a href="/pkg/go/types/#Instance"><code>Instance</code></a> type.
+      </li>
+      <li><!-- CL 342671 -->
+        The new type <a href="/pkg/go/types/#ArgumentError"><code>ArgumentError</code></a>
+        and associated methods are added to represent an error related to a type argument.
+      </li>
+      <li><!-- CL 353089 -->
+        The new type <a href="/pkg/go/types/#Context"><code>Context</code></a> and factory function
+        <a href="/pkg/go/types/#NewContext"><code>NewContext</code></a>
+        are added to facilitate sharing of identical type instances
+        across type-checked packages, via the new
+        <a href="/pkg/go/types/#Config.Context"><code>Config.Context</code></a>
+        field.
+      </li>
+    </ul>
+    <p>
+      The predicates
+      <a href="/pkg/go/types/#AssignableTo"><code>AssignableTo</code></a>,
+      <a href="/pkg/go/types/#ConvertibleTo"><code>ConvertibleTo</code></a>,
+      <a href="/pkg/go/types/#Implements"><code>Implements</code></a>,
+      <a href="/pkg/go/types/#Identical"><code>Identical</code></a>,
+      <a href="/pkg/go/types/#IdenticalIgnoreTags"><code>IdenticalIgnoreTags</code></a>, and
+      <a href="/pkg/go/types/#AssertableTo"><code>AssertableTo</code></a>
+      now also work with arguments that are or contain generalized interfaces, i.e. interfaces
+      that may only be used as type constraints in Go code.
+      Note that the behavior of <code>AssertableTo</code> is undefined if the first argument
+      is a generalized interface.
+    </p>
+  </dd>
+</dl>
+
+<dl id="html/template"><dt><a href="/pkg/html/template/">html/template</a></dt>
+  <dd>
+    <p><!-- CL 321491 -->
+      Within a <code>range</code> pipeline the new
+      <code>{{break}}</code> command will end the loop early and the
+      new <code>{{continue}}</code> command will immediately start the
+      next loop iteration.
+    </p>
+
+    <p><!-- CL 321490 -->
+      The <code>and</code> function no longer always evaluates all arguments; it
+      stops evaluating arguments after the first argument that evaluates to
+      false.  Similarly, the <code>or</code> function now stops evaluating
+      arguments after the first argument that evaluates to true. This makes a
+      difference if any of the arguments is a function call.
+    </p>
+  </dd>
+</dl><!-- html/template -->
+
+<dl id="image/draw"><dt><a href="/pkg/image/draw/">image/draw</a></dt>
+  <dd>
+    <p><!-- CL 340049 -->
+      The <code>Draw</code> and <code>DrawMask</code> fallback implementations
+      (used when the arguments are not the most common image types) are now
+      faster when those arguments implement the optional
+      <a href="/pkg/image/draw/#RGBA64Image"><code>draw.RGBA64Image</code></a>
+      and <a href="/pkg/image/#RGBA64Image"><code>image.RGBA64Image</code></a>
+      interfaces that were added in Go 1.17.
+    </p>
+  </dd>
+</dl><!-- image/draw -->
+
+<dl id="net"><dt><a href="/pkg/net/">net</a></dt>
+  <dd>
+    <p><!-- CL 340261 -->
+      <a href="/pkg/net#Error"><code>net.Error.Temporary</code></a> has been deprecated.
+    </p>
+  </dd>
+</dl><!-- net -->
+
+<dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
+  <dd>
+    <p><!-- CL 330852 -->
+      On WebAssembly targets, the <code>Dial</code>, <code>DialContext</code>,
+      <code>DialTLS</code> and <code>DialTLSContext</code> method fields in
+      <a href="/pkg/net/http/#Transport"><code>Transport</code></a>
+      will now be correctly used, if specified, for making HTTP requests.
+    </p>
+
+    <p><!-- CL 338590 -->
+      The new
+      <a href="/pkg/net/http#Cookie.Valid"><code>Cookie.Valid</code></a>
+      method reports whether the cookie is valid.
+    </p>
+
+    <p><!-- CL 346569 -->
+      The new
+      <a href="/pkg/net/http#MaxBytesHandler"><code>MaxBytesHandler</code></a>
+      function creates a <code>Handler</code> that wraps its
+      <code>ResponseWriter</code> and <code>Request.Body</code> with a
+      <a href="/pkg/net/http#MaxBytesReader"><code>MaxBytesReader</code></a>.
+    </p>
+  </dd>
+</dl><!-- net/http -->
+
+<dl id="os/user"><dt><a href="/pkg/os/user/">os/user</a></dt>
+  <dd>
+    <p><!-- CL 330753 -->
+      <a href="/pkg/os/user#User.GroupIds"><code>User.GroupIds</code></a>
+      now uses a Go native implementation when cgo is not available.
+    </p>
+  </dd>
+</dl><!-- os/user -->
+
+<dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
+  <dd>
+    <p><!-- CL 356049, CL 320929 -->
+      The new
+      <a href="/pkg/reflect/#Value.SetIterKey"><code>Value.SetIterKey</code></a>
+      and <a href="/pkg/reflect/#Value.SetIterValue"><code>Value.SetIterValue</code></a>
+      methods set a Value using a map iterator as the source. They are equivalent to
+      <code>Value.Set(iter.Key())</code> and <code>Value.Set(iter.Value())</code>, but
+      do fewer allocations.
+    </p>
+
+    <p><!-- CL 350691 -->
+      The new
+      <a href="/pkg/reflect/#Value.UnsafePointer"><code>Value.UnsafePointer</code></a>
+      method returns the Value's value as an <a href="/pkg/unsafe/#Pointer"><code>unsafe.Pointer</code></a>.
+      This allows callers to migrate from <a href="/pkg/reflect/#Value.UnsafeAddr"><code>Value.UnsafeAddr</code></a>
+      and <a href="/pkg/reflect/#Value.Pointer"><code>Value.Pointer</code></a>
+      to eliminate the need to perform uintptr to unsafe.Pointer conversions at the callsite (as unsafe.Pointer rules require).
+    </p>
+
+    <p><!-- CL 321891 -->
+      The new
+      <a href="/pkg/reflect/#MapIter.Reset"><code>MapIter.Reset</code></a>
+      method changes its receiver to iterate over a
+      different map. The use of
+      <a href="/pkg/reflect/#MapIter.Reset"><code>MapIter.Reset</code></a>
+      allows allocation-free iteration
+      over many maps.
+    </p>
+
+    <p><!-- CL 352131 -->
+      A number of methods (
+      <a href="/pkg/reflect#Value.CanInt"><code>Value.CanInt</code></a>,
+      <a href="/pkg/reflect#Value.CanUint"><code>Value.CanUint</code></a>,
+      <a href="/pkg/reflect#Value.CanFloat"><code>Value.CanFloat</code></a>,
+      <a href="/pkg/reflect#Value.CanComplex"><code>Value.CanComplex</code></a>
+      )
+      have been added to
+      <a href="/pkg/reflect#Value"><code>Value</code></a>
+      to test if a conversion is safe.
+    </p>
+
+    <p><!-- CL 357962 -->
+      <a href="/pkg/reflect#Value.FieldByIndexErr"><code>Value.FieldByIndexErr</code></a>
+      has been added to avoid the panic that occurs in
+      <a href="/pkg/reflect#Value.FieldByIndex"><code>Value.FieldByIndex</code></a>
+      when stepping through a nil pointer to an embedded struct.
+    </p>
+
+    <p><!-- CL 341333 -->
+      <a href="/pkg/reflect#Ptr"><code>reflect.Ptr</code></a> and
+      <a href="/pkg/reflect#PtrTo"><code>reflect.PtrTo</code></a>
+      have been renamed to
+      <a href="/pkg/reflect#Pointer"><code>reflect.Pointer</code></a> and
+      <a href="/pkg/reflect#PointerTo"><code>reflect.PointerTo</code></a>,
+      respectively, for consistency with the rest of the reflect package.
+      The old names will continue to work, but will be deprecated in a
+      future Go release.
+    </p>
+  </dd><!-- CL 321889 and CL 345486 are optimizations, no need to mention. -->
+</dl><!-- reflect -->
+
+<dl id="regexp"><dt><a href="/pkg/regexp/">regexp</a></dt>
+  <dd>
+    <p><!-- CL 354569 -->
+      <a href="/pkg/regexp/"><code>regexp</code></a>
+      now treats each invalid byte of a UTF-8 string as <code>U+FFFD</code>.
+    </p>
+  </dd>
+</dl><!-- regexp -->
+
+<dl id="runtime/debug"><dt><a href="/pkg/runtime/debug/">runtime/debug</a></dt>
+  <dd>
+    <p><!-- CL 354569 -->
+      The <a href="/pkg/runtime/debug#BuildInfo"><code>BuildInfo</code></a>
+      struct has two new fields, containing additional information
+      about how the binary was built:
+      <ul>
+	<li><a href="/pkg/runtime/debug#BuildInfo.GoVersion"><code>GoVersion</code></a>
+	  holds the version of Go used to build the binary.
+	</li>
+	<li>
+	  <a href="/pkg/runtime/debug#BuildInfo.Settings"><code>Settings</code></a>
+	  is a slice of
+	  <a href="/pkg/runtime/debug#BuildSettings"><code>BuildSettings</code></a>
+	  structs holding key/value pairs describing the build.
+	</li>
+      </ul>
+    </p>
+  </dd>
+</dl><!-- runtime/debug -->
+
+<dl id="runtime/pprof"><dt><a href="/pkg/runtime/pprof/">runtime/pprof</a></dt>
+  <dd>
+    <p><!-- CL 324129 -->
+      The CPU profiler now uses per-thread timers on Linux. This increases the
+      maximum CPU usage that a profile can observe, and reduces some forms of
+      bias.
+    </p>
+  </dd>
+</dl><!-- runtime/pprof -->
+
+<dl id="strconv"><dt><a href="/pkg/strconv/">strconv</a></dt>
+  <dd>
+    <p><!-- CL 343877 -->
+      <a href="/pkg/strconv/#strconv.Unquote"><code>strconv.Unquote</code></a>
+      now rejects Unicode surrogate halves.
+    </p>
+  </dd>
+</dl><!-- strconv -->
+
+<dl id="strings"><dt><a href="/pkg/strings/">strings</a></dt>
+  <dd>
+    <p><!-- CL 351710 -->
+      The new <a href="/pkg/strings/#Cut"><code>Cut</code></a> function
+      slices a <code>string</code> around a separator. It can replace
+      and simplify many common uses of
+      <a href="/pkg/strings/#Index"><code>Index</code></a>,
+      <a href="/pkg/strings/#IndexByte"><code>IndexByte</code></a>,
+      <a href="/pkg/strings/#IndexRune"><code>IndexRune</code></a>,
+      and <a href="/pkg/strings/#SplitN"><code>SplitN</code></a>.
+    </p>
+
+    <p><!-- CL 345849 -->
+      The new <a href="/pkg/strings/#Clone"><code>Clone</code></a> function copies the input
+      <code>string</code> without the returned cloned <code>string</code> referencing
+      the input string's memory.
+    </p>
+
+    <p><!-- CL 323318, CL 332771 -->
+      <a href="/pkg/strings/#Trim"><code>Trim</code></a>, <a href="/pkg/strings/#TrimLeft"><code>TrimLeft</code></a>,
+      and <a href="/pkg/strings/#TrimRight"><code>TrimRight</code></a> are now allocation free and, especially for
+      small ASCII cutsets, up to 10 times faster.
+    </p>
+
+    <p><!-- CL 359485 -->
+      The <a href="/pkg/strings/#Title"><code>Title</code></a> function is now deprecated. It doesn't
+      handle Unicode punctuation and language-specific capitalization rules, and is superseded by the
+      <a href="https://golang.org/x/text/cases">golang.org/x/text/cases</a> package.
+    </p>
+  </dd>
+</dl><!-- strings -->
+
+<dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
+  <dd>
+    <p><!-- CL 319769 -->
+      The new methods
+      <a href="/pkg/sync#Mutex.TryLock"><code>Mutex.TryLock</code></a>,
+      <a href="/pkg/sync#RWMutex.TryLock"><code>RWMutex.TryLock</code></a>, and
+      <a href="/pkg/sync#RWMutex.TryRLock"><code>RWMutex.TryRLock</code></a>,
+      will acquire the lock if it is not currently held.
+    </p>
+  </dd>
+</dl><!-- sync -->
+
+<dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
+  <dd>
+    <p><!-- CL 336550 -->
+      The new function <a href="/pkg/syscall/?GOOS=windows#SyscallN"><code>SyscallN</code></a>
+      has been introduced for Windows, allowing for calls with arbitrary number
+      of arguments. As a result,
+      <a href="/pkg/syscall/?GOOS=windows#Syscall"><code>Syscall</code></a>,
+      <a href="/pkg/syscall/?GOOS=windows#Syscall6"><code>Syscall6</code></a>,
+      <a href="/pkg/syscall/?GOOS=windows#Syscall9"><code>Syscall9</code></a>,
+      <a href="/pkg/syscall/?GOOS=windows#Syscall12"><code>Syscall12</code></a>,
+      <a href="/pkg/syscall/?GOOS=windows#Syscall15"><code>Syscall15</code></a>, and
+      <a href="/pkg/syscall/?GOOS=windows#Syscall18"><code>Syscall18</code></a> are
+      deprecated in favor of <a href="/pkg/syscall/?GOOS=windows#SyscallN"><code>SyscallN</code></a>.
+    </p>
+
+    <p><!-- CL 355570 -->
+      <a href="/pkg/syscall/?GOOS=freebsd#SysProcAttr.Pdeathsig"><code>SysProcAttr.Pdeathsig</code></a>
+      is now supported in FreeBSD.
+    </p>
+  </dd>
+</dl><!-- syscall -->
+
+<dl id="syscall/js"><dt><a href="/pkg/syscall/js/">syscall/js</a></dt>
+  <dd>
+    <p><!-- CL 356430 -->
+      The <code>Wrapper</code> interface has been removed.
+    </p>
+  </dd>
+</dl><!-- syscall/js -->
+
+<dl id="testing"><dt><a href="/pkg/testing/">testing</a></dt>
+  <dd>
+    <p><!-- CL 343883 -->
+      The precedence of <code>/</code> in the argument for <code>-run</code> and
+      <code>-bench</code> has been increased. <code>A/B|C/D</code> used to be
+      treated as <code>A/(B|C)/D</code> and is now treated as
+      <code>(A/B)|(C/D)</code>.
+    </p>
+
+    <p><!-- CL 356669 -->
+      If the <code>-run</code> option does not select any tests, the
+      <code>-count</code> option is ignored. This could change the behavior of
+      existing tests in the unlikely case that a test changes the set of subtests
+      that are run each time the test function itself is run.
+    </p>
+
+    <p><!-- CL 251441 -->
+      The new <a href="/pkg/testing#F"><code>testing.F</code></a> type
+      is used by the new <a href="#fuzzing">fuzzing support described
+      above</a>. Tests also now support the command line
+      options <code>-test.fuzz</code>, <code>-test.fuzztime</code>, and
+      <code>-test.fuzzminimizetime</code>.
+    </p>
+  </dd>
+</dl><!-- testing -->
+
+<dl id="text/template"><dt><a href="/pkg/text/template/">text/template</a></dt>
+  <dd>
+    <p><!-- CL 321491 -->
+      Within a <code>range</code> pipeline the new
+      <code>{{break}}</code> command will end the loop early and the
+      new <code>{{continue}}</code> command will immediately start the
+      next loop iteration.
+    </p>
+
+    <p><!-- CL 321490 -->
+      The <code>and</code> function no longer always evaluates all arguments; it
+      stops evaluating arguments after the first argument that evaluates to
+      false.  Similarly, the <code>or</code> function now stops evaluating
+      arguments after the first argument that evaluates to true. This makes a
+      difference if any of the arguments is a function call.
+    </p>
+  </dd>
+</dl><!-- text/template -->
+
+<dl id="text/template/parse"><dt><a href="/pkg/text/template/parse/">text/template/parse</a></dt>
+  <dd>
+    <p><!-- CL 321491 -->
+      The package supports the new
+      <a href="/pkg/text/template/">text/template</a> and
+      <a href="/pkg/html/template/">html/template</a>
+      <code>{{break}}</code> command via the new constant
+      <a href="/pkg/text/template/parse#NodeBreak"><code>NodeBreak</code></a>
+      and the new type
+      <a href="/pkg/text/template/parse#BreakNode"><code>BreakNode</code></a>,
+      and similarly supports the new <code>{{continue}}</code> command
+      via the new constant
+      <a href="/pkg/text/template/parse#NodeContinue"><code>NodeContinue</code></a>
+      and the new type
+      <a href="/pkg/text/template/parse#ContinueNode"><code>ContinueNode</code></a>.
+    </p>
+  </dd>
+</dl><!-- text/template -->
+
+<dl id="unicode/utf8"><dt><a href="/pkg/unicode/utf8/">unicode/utf8</a></dt>
+  <dd>
+    <p><!-- CL 345571 -->
+      The new <a href="/pkg/unicode/utf8/#AppendRune"><code>AppendRune</code></a> function appends the UTF-8
+      encoding of a <code>rune</code> to a <code>[]byte</code>.
+    </p>
+  </dd>
+</dl><!-- unicode/utf8 -->