_content/doc/go1.18.html

<!--{
	"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">Introduction to Go 1.18</h2>

<p>
  The latest Go release, version 1.18,
  is a significant release, including changes to the language,
  implementation of the toolchain, runtime, and libraries.
  Go 1.18 arrives seven months after <a href="/doc/go1.17">Go 1.17</a>.
  As always, the release maintains the Go 1 <a href="/doc/go1compat">promise of compatibility</a>.
  We expect almost all Go programs to continue to compile and run as before.
</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>
  While we believe that the new language features are well designed
  and clearly specified, it is possible that we have made mistakes.
  We want to stress that the <a href="/doc/go1compat">Go 1
  compatibility guarantee</a> says "If it becomes necessary to address
  an inconsistency or incompleteness in the specification, resolving
  the issue could affect the meaning or legality of existing
  programs. We reserve the right to address such issues, including
  updating the implementations." It also says "If a compiler or
  library has a bug that violates the specification, a program that
  depends on the buggy behavior may break if the bug is fixed. We
  reserve the right to fix such bugs." In other words, it is possible
  that there will be code using generics that will work with the 1.18
  release but break in later releases. We do not plan or expect to
  make any such change. However, breaking 1.18 programs in future
  releases may become necessary for reasons that we cannot today
  foresee. We will minimize any such breakage as much as possible, but
  we can't guarantee that the breakage will be zero.
</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_parameter_declarations">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 known limitations:
  <ul>
    <li><!-- https://golang.org/issue/47631 -->
      The Go compiler cannot handle type declarations inside generic functions
      or methods. We hope to provide support for this feature in a
      future release.
    </li>
    <li><!-- https://golang.org/issue/50937 -->
      The Go compiler 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 a future release.
    </li>
    <li><!-- https://golang.org/issue/51183 -->
      The Go compiler 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 a future
      release.
    </li>
    <li><!-- https://golang.org/issue/51576 -->
      The Go compiler does not support accessing a struct field <code>x.f</code>
      where <code>x</code> is of type parameter type even if all types in the
      type parameter's type set have a field <code>f</code>.
      We may remove this restriction in a future release.
    </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>

<p>
  Generics also represent a large change for the Go ecosystem. While we have
  updated several core tools with generics support, there is much more to do.
  It will take time for remaining tools, documentation, and libraries to catch
  up with these language changes.
</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/security/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.18</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>

<p><!-- CL 347917 -->
  The built-in function <code>append</code> now uses a slightly different formula
  when deciding how much to grow a slice when it must allocate a new underlying array.
  The new formula is less prone to sudden transitions in allocation behavior.
</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 future releases.
</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 a future release.
</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>

    <p>
      Support for signing certificates using signature algorithms that depend on the
      MD5 hash (<code>MD5WithRSA</code>) may be removed in Go 1.19.
    </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="embed"><dt><a href="/pkg/embed/">embed</a></dt>
  <dd>
    <p><!-- CL 359413 -->
      A <a href="/pkg/embed#hdr-Directives"><code>go:embed</code></a>
      directive may now start with <code>all:</code> to include files
      whose names start with dot or underscore.
    </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>AssignableTo</code>,
      <code>ConvertibleTo</code>, <code>Implements</code>, and
      <code>AssertableTo</code> is undefined with arguments that are
      uninstantiated generic types, and <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>

    <p><!-- CL 359634, CL 360381, CL 362735 -->
      When looking up a domain name containing non-ASCII characters,
      the Unicode-to-ASCII conversion is now done in accordance with
      Nontransitional Processing as defined in the
      <a href="https://unicode.org/reports/tr46/">Unicode IDNA
      Compatibility Processing</a> standard (UTS #46). The
      interpretation of four distinct runes are changed: ß, ς,
      zero-width joiner U+200D, and zero-width non-joiner
      U+200C. Nontransitional Processing is consistent with most
      applications and web browsers.
    </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 -->