doc/go1.21: update crypto release notes

[gostls13.git] / doc / go1.21.html

<!--{
        "Title": "Go 1.21 Release Notes",
        "Path":  "/doc/go1.21"
}-->

<!--
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.21</h2>

<p>
  <strong>
    Go 1.21 is not yet released. These are work-in-progress
    release notes. Go 1.21 is expected to be released in August 2023.
  </strong>
</p>

<p>
  The latest Go release, version 1.21, arrives six months after <a href="/doc/go1.20">Go 1.20</a>.
  Most of its changes are in the implementation of the toolchain, runtime, and libraries.
  As always, the release maintains the Go 1 <a href="/doc/go1compat">promise of compatibility</a>;
  in fact, Go 1.21 <a href="#godebug">improves upon that promise</a>.
  We expect almost all Go programs to continue to compile and run as before.
</p>

<p><!-- https://go.dev/issue/57631 -->
  Go 1.21 introduces a small change to the numbering of releases.
  In the past, we used Go 1.<i>N</i> to refer to both the overall Go language version and release family
  as well as the first release in that family.
  Starting in Go 1.21, the first release is now Go 1.<i>N</i>.0.
  Today we are releasing both the Go 1.21 language and its initial implementation, the Go 1.21.0 release.
  These notes refer to “Go 1.21”; tools like <code>go</code> <code>version</code> will report “<code>go1.21.0</code>”
  (until you upgrade to Go 1.21.1).
  See “<a href="/doc/toolchain#versions">Go versions</a>” in the “Go Toolchains” documentation for details
  about the new version numbering.
</p>

<h2 id="language">Changes to the language</h2>

<p>
  Go 1.21 adds three new built-ins to the language.

  <ul>
    <li><!-- https://go.dev/issue/59488 -->
      The new functions <code>min</code> and <code>max</code> compute the
      smallest (or largest, for <code>max</code>) value of a fixed number
      of given arguments.
      See the language spec for
      <a href="https://tip.golang.org/ref/spec#Min_and_max">details</a>.
    </li>
    <li><!-- https://go.dev/issue/56351 -->
      The new function <code>clear</code> deletes all elements from a
      map or zeroes all elements of a slice.
      See the language spec for
      <a href="https://tip.golang.org/ref/spec#Clear">details</a>.
    </li>
  </ul>
</p>

<p><!-- https://go.dev/issue/57411 -->
  Package initialization order is now specified more precisely. The
  new algorithm is:
  <ul>
    <li>
      Sort all packages by import path.
    </li>
    <li>Repeat until the list of packages is empty:
      <ul>
        <li>
          Find the first package in the list for which all imports are
          already initialized.
        </li>
        <li>
          Initialize that package and remove it from the list.
        </li>
      </ul>
    </li>
  </ul>
  This may change the behavior of some programs that rely on a
  specific initialization ordering that was not expressed by explicit
  imports. The behavior of such programs was not well defined by the
  spec in past releases. The new rule provides an unambiguous definition.
</p>

<p>
  Multiple improvements that increase the power and precision of type inference have been made.
</p>
<ul>
  <li><!-- https://go.dev/issue/59338 -->
    A (possibly partially instantiated generic) function may now be called with arguments that are
    themselves (possibly partially instantiated) generic functions.
    The compiler will attempt to infer the missing type arguments of the callee (as before) and,
    for each argument that is a generic function that is not fully instantiated,
    its missing type arguments (new).
    Typical use cases are calls to generic functions operating on containers
    (such as <a href="/pkg/slices#IndexFunc">slices.IndexFunc</a>) where a function argument
    may also be generic, and where the type argument of the called function and its arguments
    are inferred from the container type.
    More generally, a generic function may now be used without explicit instantiation when
    it is assigned to a variable or returned as a result value if the type arguments can
    be inferred from the assignment.
  </li>
  <li><!-- https://go.dev/issue/60353, https://go.dev/issue/57192, https://go.dev/issue/52397, https://go.dev/issue/41176 -->
    Type inference now also considers methods when a value is assigned to an interface:
    type arguments for type parameters used in method signatures may be inferred from
    the corresponding parameter types of matching methods.
  </li>
  <li><!-- https://go.dev/issue/51593 https://go.dev/issue/39661 -->
    Similarly, since a type argument must implement all the methods of its corresponding constraint,
    the methods of the type argument and constraint are matched which may lead to the inference of
    additional type arguments.
  </li>
  <li><!-- https://go.dev/issue/58671 -->
    If multiple untyped constant arguments of different kinds (such as an untyped int and
    an untyped floating-point constant) are passed to parameters with the same (not otherwise
    specified) type parameter type, instead of an error, now type inference determines the
    type using the same approach as an operator with untyped constant operands.
    This change brings the types inferred from untyped constant arguments in line with the
    types of constant expressions.
  </li>
  <li><!-- https://go.dev/issue/59750 -->
    Type inference is now precise when matching corresponding types in assignments:
    component types (such as the elements of slices, or the parameter types in function signatures)
    must be identical (given suitable type arguments) to match, otherwise inference fails.
    This change produces more accurate error messages:
    where in the past type inference may have succeeded incorrectly and lead to an invalid assignment,
    the compiler now reports an inference error if two types can't possibly match.
  </li>
</ul>

<p><!-- https://go.dev/issue/58650 -->
  More generally, the description of
  <a href="https://tip.golang.org/ref/spec#Type_inference">type inference</a>
  in the language spec has been clarified.
  Together, all these changes make type inference more powerful and inference failures less surprising.
</p>

<!-- https://go.dev/issue/57969 -->
<p>
  Go 1.21 includes a preview of a language change we are considering for a future version of Go:
  making for loop variables per-iteration instead of per-loop, to avoid accidental sharing bugs.
  For details about how to try that language change, see <a href="https://go.dev/wiki/LoopvarExperiment">the LoopvarExperiment wiki page</a>.
</p>

<h2 id="tools">Tools</h2>
<p>
  Go 1.21 adds improved support for backwards compatibility and forwards compatibility
  in the Go toolchain.
</p>

<p><!-- https://go.dev/issue/56986 -->
  To improve backwards compatibility, Go 1.21 formalizes
  Go's use of the GODEBUG environment variable to control
  the default behavior for changes that are non-breaking according to the
  <a href="/doc/go1compat">compatibility policy</a>
  but nonetheless may cause existing programs to break.
  (For example, programs that depend on buggy behavior may break
  when a bug is fixed, but bug fixes are not considered breaking changes.)
  When Go must make this kind of behavior change,
  it now chooses between the old and new behavior based on the
  <code>go</code> line in the workspace's <code>go.work</code> file
  or else the main module's <code>go.mod</code> file.
  Upgrading to a new Go toolchain but leaving the <code>go</code> line
  set to its original (older) Go version preserves the behavior of the older
  toolchain.
  With this compatibility support, the latest Go toolchain should always
  be the best, most secure, implementation of an older version of Go.
  See “<a href="/doc/godebug">Go, Backwards Compatibility, and GODEBUG</a>” for details.
</p>

<p><!-- https://go.dev/issue/57001 -->
  To improve forwards compatibility, Go 1.21 now reads the <code>go</code> line
  in a <code>go.work</code> or <code>go.mod</code> file as a strict
  minimum requirement: <code>go</code> <code>1.21.0</code> means
  that the workspace or module cannot be used with Go 1.20 or with Go 1.21rc1.
  This allows projects that depend on fixes made in later versions of Go
  to ensure that they are not used with earlier versions.
  It also gives better error reporting for projects that make use of new Go features:
  when the problem is that a newer Go version is needed,
  that problem is reported clearly, instead of attempting to build the code
  and instead printing errors about unresolved imports or syntax errors.
</p>

<p>
  To make these new stricter version requirements easier to manage,
  the <code>go</code> command can now invoke not just the toolchain
  bundled in its own release but also other Go toolchain versions found in the PATH
  or downloaded on demand.
  If a <code>go.mod</code> or <code>go.work</code> <code>go</code> line
  declares a minimum requirement on a newer version of Go, the <code>go</code>
  command will find and run that version automatically.
  The new <code>toolchain</code> directive sets a suggested minimum toolchain to use,
  which may be newer than the strict <code>go</code> minimum.
  See “<a href="/doc/toolchain">Go Toolchains</a>” for details.
</p>

<h3 id="go-command">Go command</h3>

<p><!-- https://go.dev/issue/58099, CL 474236 -->
  The <code>-pgo</code> build flag now defaults to <code>-pgo=auto</code>,
  and the restriction of specifying a single main package on the command
  line is now removed. If a file named <code>default.pgo</code> is present
  in the main package's directory, the <code>go</code> command will use
  it to enable profile-guided optimization for building the corresponding
  program.
</p>

<p>
  The <code>-C</code> <code>dir</code> flag must now be the first
  flag on the command-line when used.
</p>

<p><!-- https://go.dev/issue/37708, CL 463837 -->
  The new <code>go</code> <code>test</code> option
  <code>-fullpath</code> prints full path names in test log messages,
  rather than just base names.
</p>

<p><!-- https://go.dev/issue/15513, CL 466397 -->
  The <code>go</code> <code>test</code> <code>-c</code> flag now
  supports writing test binaries for multiple packages, each to
  <code>pkg.test</code> where <code>pkg</code> is the package name.
  It is an error if more than one test package being compiled has a given package name.]
</p>

<p><!-- https://go.dev/issue/15513, CL 466397 -->
  The <code>go</code> <code>test</code> <code>-o</code> flag now
  accepts a directory argument, in which case test binaries are written to that
  directory instead of the current directory.
</p>

<h3 id="cgo">Cgo</h3>

<p><!-- CL 490819 -->
  In files that <code>import "C"</code>, the Go toolchain now
  correctly reports errors for attempts to declare Go methods on C types.
</p>

<h2 id="runtime-changes">Runtime</h2>

<p><!-- https://go.dev/issue/7181 -->
  When printing very deep stacks, the runtime now prints the first 50
  (innermost) frames followed by the bottom 50 (outermost) frames,
  rather than just printing the first 100 frames. This makes it easier
  to see how deeply recursive stacks started, and is especially
  valuable for debugging stack overflows.
</p>

<p><!-- https://go.dev/issue/59960 -->
  On Linux platforms that support transparent huge pages, the Go runtime
  now manages which parts of the heap may be backed by huge pages more
  explicitly. This leads to better utilization of memory: small heaps
  should see less memory used (up to 50% in pathological cases) while
  large heaps should see fewer broken huge pages for dense parts of the
  heap, improving CPU usage and latency by up to 1%.
</p>

<p><!-- https://go.dev/issue/57069, https://go.dev/issue/56966 -->
  As a result of runtime-internal garbage collection tuning,
  applications may see up to a 40% reduction in application tail latency
  and a small decrease in memory use. Some applications may also observe
  a small loss in throughput.

  The memory use decrease should be proportional to the loss in
  throughput, such that the previous release's throughput/memory
  tradeoff may be recovered (with little change to latency) by
  increasing <code>GOGC</code> and/or <code>GOMEMLIMIT</code> slightly.
</p>

<p><!-- https://go.dev/issue/51676 -->
  Calls from C to Go on threads created in C require some setup to prepare for
  Go execution. On Unix platforms, this setup is now preserved across multiple
  calls from the same thread. This significantly reduces the overhead of
  subsequent C to Go calls from ~1-3 microseconds per call to ~100-200
  nanoseconds per call.
</p>

<h2 id="compiler">Compiler</h2>

<p>
  Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready
  for general use. PGO enables additional optimizations on code identified as
  hot by profiles of production workloads. As mentioned in the
  <a href="#go-command">Go command section</a>, PGO is enabled by default for
  binaries that contain a <code>default.pgo</code> profile in the main
  package directory. Performance improvements vary depending on application
  behavior, with most programs from a representative set of Go programs seeing
  between 2 and 7% improvement from enabling PGO. See the
  <a href="/doc/pgo">PGO user guide</a> for detailed documentation.
</p>

<!-- https://go.dev/issue/59959 -->
<p>
  PGO builds can now devirtualize some interface method calls, adding a
  concrete call to the most common callee. This enables further optimization,
  such as inlining the callee.
</p>

<!-- CL 497455 -->
<p>
  Go 1.21 improves build speed by up to 6%, largely thanks to building the
  compiler itself with PGO.
</p>

<h2 id="assembler">Assembler</h2>

<!-- https://go.dev/issue/58378 -->
<p>
  On amd64, frameless nosplit assembly functions are no longer automatically marked as <code>NOFRAME</code>.
  Instead, the <code>NOFRAME</code> attribute must be explicitly specified if desired,
  which is already the behavior on other architectures supporting frame pointers.
  With this, the runtime now maintains the frame pointers for stack transitions.
</p>

<!-- CL 476295 -->
<p>
  The verifier that checks for incorrect uses of <code>R15</code> when dynamic linking on amd64 has been improved.
</p>

<h2 id="linker">Linker</h2>

<p><!-- https://go.dev/issue/57302, CL 461749, CL 457455 -->
  On windows/amd64, the linker (with help from the compiler) now emits
  SEH unwinding data by default, which improves the integration
  of Go applications with Windows debuggers and other tools.
</p>

<!-- CL 463395, CL 461315 -->
<p>
  In Go 1.21 the linker (with help from the compiler) is now capable of
  deleting dead (unreferenced) global map variables, if the number of
  entries in the variable initializer is sufficiently large, and if the
  initializer expressions are side-effect free.
</p>

<h2 id="library">Core library</h2>

<h3 id="slog">New log/slog package</h3>

<p><!-- https://go.dev/issue/59060, https://go.dev/issue/59141, https://go.dev/issue/59204, https://go.dev/issue/59280,
        https://go.dev/issue/59282, https://go.dev/issue/59339, https://go.dev/issue/59345, https://go.dev/issue/61200,
        CL 477295, CL 484096, CL 486376, CL 486415, CL 487855, CL 508195 -->
  The new <a href="/pkg/log/slog">log/slog</a> package provides structured logging with levels.
  Structured logging emits key-value pairs
  to enable fast, accurate processing of large amounts of log data.
  The package supports integration with popular log analysis tools and services.
</p>

<h3 id="slogtest">New testing/slogtest package</h3>

<p><!-- CL 487895 -->
  The new <a href="/pkg/testing/slogtest">testing/slogtest</a> package can help
  to validate <a href="/pkg/log/slog#Handler">slog.Handler</a> implementations.
</p>

<h3 id="slices">New slices package</h3>

<p>
  <!-- https://go.dev/issue/45955, https://go.dev/issue/54768 -->
  <!-- https://go.dev/issue/57348, https://go.dev/issue/57433 -->
  <!-- https://go.dev/issue/58565, https://go.dev/issue/60091 -->
  <!-- https://go.dev/issue/60546 -->
  <!-- CL 467417, CL 468855, CL 483175, CL 496078, CL 498175, CL 502955 -->
  The new <a href="/pkg/slices">slices</a> package provides many common
  operations on slices, using generic functions that work with slices
  of any element type.
</p>

<h3 id="maps">New maps package</h3>

<p><!-- https://go.dev/issue/57436, CL 464343 -->
  The new <a href="/pkg/maps/">maps</a> package provides several
  common operations on maps, using generic functions that work with
  maps of any key or element type.
</p>

<h3 id="cmp">New cmp package</h3>

<p><!-- https://go.dev/issue/59488, CL 496356 -->
  The new <a href="/pkg/cmp/">cmp</a> package defines the type
  constraint <a href="/pkg/cmp/#Ordered"><code>Ordered</code></a> and
  two new generic functions
  <a href="/pkg/cmp/#Less"><code>Less</code></a>
  and <a href="/pkg/cmp/#Compare"><code>Compare</code></a> that are
  useful with <a href="/ref/spec/#Comparison_operators">ordered
  types</a>.
</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.
  There are also various performance improvements, not enumerated here.
</p>

<dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/54451, CL 491175 -->
      The implementation of the
      <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
      interface returned by
      <a href="/pkg/archive/tar/#Header.FileInfo"><code>Header.FileInfo</code></a>
      now implements a <code>String</code> method that calls
      <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
    </p>
  </dd>
</dl><!-- archive/tar -->

<dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/54451, CL 491175 -->
      The implementation of the
      <a href="/pkg/io/fs/#FileInfo"><code>io/fs.FileInfo</code></a>
      interface returned by
      <a href="/pkg/archive/zip/#FileHeader.FileInfo"><code>FileHeader.FileInfo</code></a>
      now implements a <code>String</code> method that calls
      <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
    </p>

    <p><!-- https://go.dev/issue/54451, CL 491175 -->
      The implementation of the
      <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
      interface returned by the
      <a href="/pkg/io/fs/#ReadDirFile.ReadDir"><code>io/fs.ReadDirFile.ReadDir</code></a>
      method of the
      <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
      returned by
      <a href="/pkg/archive/zip/#Reader.Open"><code>Reader.Open</code></a>
      now implements a <code>String</code> method that calls
      <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
    </p>
  </dd>
</dl><!-- archive/zip -->

<dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/53685, CL 474635 -->
      The <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
      has two new methods:
      <a href="/pkg/bytes/#Buffer.Available"><code>Available</code></a>
      and <a href="/pkg/bytes/#AvailableBuffer"><code>AvailableBuffer</code></a>.
      These may be used along with the
      <a href="/pkg/bytes/#Buffer.Write"><code>Write</code></a>
      method to append directly to the <code>Buffer</code>.
    </p>
  </dd>
</dl><!-- bytes -->

<dl id="context"><dt><a href="/pkg/context/">context</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/40221, CL 479918 -->
      The new <a href="/pkg/context/#WithoutCancel"><code>WithoutCancel</code></a>
      function returns a copy of a context that is not canceled when the original
      context is canceled.
    </p>
    <p><!-- https://go.dev/issue/56661, CL 449318 -->
      The new <a href="/pkg/context/#WithDeadlineCause"><code>WithDeadlineCause</code></a>
      and <a href="/pkg/context/#WithTimeoutCause"><code>WithTimeoutCause</code></a>
      functions provide a way to set a context cancellation cause when a deadline or
      timer expires. The cause may be retrieved with the
      <a href="/pkg/context/#Cause"><code>Cause</code></a> function.
    </p>
    <p><!-- https://go.dev/issue/57928, CL 482695 -->
      The new <a href="/pkg/context/#AfterFunc"><code>AfterFunc</code></a>
      function registers a function to run after a context has been cancelled.
    </p>

    <p><!-- CL 455455 -->
      An optimization means that the results of calling
      <a href="/pkg/context/#Background"><code>Background</code></a>
      and <a href="/pkg/context/#TODO"><code>TODO</code></a> and
      converting them to a shared type can be considered equal.
      In previous releases they were always different.  Comparing
      <a href="/pkg/context/#Context"><code>Context</code></a> values
      for equality has never been well-defined, so this is not
      considered to be an incompatible change.
    </p>
  </dd>
</dl>


<dl id="crypto/ecdsa"><dt><a href="/pkg/crypto/ecdsa/">crypto/ecdsa</a></dt>
  <dd>
    <p><!-- CL 492955 -->
      <a href="/pkg/crypto/ecdsa/#PublicKey.Equal"><code>PublicKey.Equal</code></a> and
      <a href="/pkg/crypto/ecdsa/#PrivateKey.Equal"><code>PrivateKey.Equal</code></a>
      now execute in constant time.
    </p>
  </dd>
</dl><!-- crypto/ecdsa -->

<dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
  <dd>
    <p><!-- CL 459977 -->
      All of the <a href="/pkg/crypto/elliptic/#Curve"><code>Curve</code></a> methods have been deprecated, along with <a href="/pkg/crypto/elliptic/#GenerateKey"><code>GenerateKey</code></a>, <a href="/pkg/crypto/elliptic/#Marshal"><code>Marshal</code></a>, and <a href="/pkg/crypto/elliptic/#Unmarshal"><code>Unmarshal</code></a>. For ECDH operations, the new <a href="/pkg/crypto/ecdh/"><code>crypto/ecdh</code></a> package should be used instead. For lower-level operations, use third-party modules such as <a href="https://pkg.go.dev/filippo.io/nistec">filippo.io/nistec</a>.
    </p>
  </dd>
</dl><!-- crypto/elliptic -->

<dl id="crypto/rand"><dt><a href="/pkg/crypto/rand/">crypto/rand</a></dt>
  <dd>
    <p><!-- CL 463123 -->
      The <a href="/pkg/crypto/rand/"><code>crypto/rand</code></a> package now uses the <code>getrandom</code> system call on NetBSD 10.0 and later.
    </p>
  </dd>
</dl><!-- crypto/rand -->

<dl id="crypto/rsa"><dt><a href="/pkg/crypto/rsa/">crypto/rsa</a></dt>
  <dd>
    <p><!-- CL 471259, CL 492935 -->
      The performance of private RSA operations (decryption and signing) is now better than Go 1.19 for <code>GOARCH=amd64</code> and <code>GOARCH=arm64</code>. It had regressed in Go 1.20.
    </p>
    <p>
      Due to the addition of private fields to <a href="/pkg/crypto/rsa/#PrecomputedValues"><code>PrecomputedValues</code></a>, <a href="/pkg/crypto/rsa/#PrivateKey.Precompute"><code>PrivateKey.Precompute</code></a> must be called for optimal performance even if deserializing (for example from JSON) a previously-precomputed private key.
    </p>
    <p><!-- CL 492955 -->
      <a href="/pkg/crypto/rsa/#PublicKey.Equal"><code>PublicKey.Equal</code></a> and
      <a href="/pkg/crypto/rsa/#PrivateKey.Equal"><code>PrivateKey.Equal</code></a>
      now execute in constant time.
    </p>
    <p><!-- https://go.dev/issue/56921, CL 459976 -->
      The <a href="/pkg/crypto/rsa/#GenerateMultiPrimeKey"><code>GenerateMultiPrimeKey</code></a> function and the <a href="/pkg/crypto/rsa/#PrecomputedValues.CRTValues"><code>PrecomputedValues.CRTValues</code></a> field have been deprecated. <a href="/pkg/crypto/rsa/#PrecomputedValues.CRTValues"><code>PrecomputedValues.CRTValues</code></a> will still be populated when <a href="/pkg/crypto/rsa/#PrivateKey.Precompute"><code>PrivateKey.Precompute</code></a> is called, but the values will not be used during decryption operations.
    </p>
  </dd>
</dl><!-- crypto/rsa -->

<!-- CL 483815 reverted -->

<dl id="crypto/sha256"><dt><a href="/pkg/crypto/sha256/">crypto/sha256</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/50543, CL 408795 -->
      SHA-224 and SHA-256 operations now use native instructions when available when <code>GOARCH=amd64</code>, providing a performance improvement on the order of 3-4x.
    </p>
  </dd>
</dl><!-- crypto/sha256 -->

<!-- CL 481478 reverted -->
<!-- CL 483816 reverted -->

<dl id="crypto/tls"><dt><a href="/pkg/crypto/tls/">crypto/tls</a></dt>
  <dd>
    <p><!-- CL 497895 -->
      Servers now skip verifying client certificates (including not running
      <a href="/pkg/crypto/tls/#Config.VerifyPeerCertificate"><code>Config.VerifyPeerCertificate</code></a>)
      for resumed connections, besides checking the expiration time. This makes
      session tickets larger when client certificates are in use. Clients were
      already skipping verification on resumption, but now check the expiration
      time even if <a href="/pkg/crypto/tls/#Config.InsecureSkipVerify"><code>Config.InsecureSkipVerify</code></a>
      is set.
    </p>

    <p><!-- https://go.dev/issue/60105, CL 496818, CL 496820, CL 496822, CL 496821, CL 501675 -->
      Applications can now control the content of session tickets.
      <ul>
        <li>
          The new <a href="/pkg/crypto/tls/#SessionState"><code>SessionState</code></a> type
          describes a resumable session.
        </li>
        <li>
          The <a href="/pkg/crypto/tls/#SessionState.Bytes"><code>SessionState.Bytes</code></a>
          method and <a href="/pkg/crypto/tls/#ParseSessionState"><code>ParseSessionState</code></a>
          function serialize and deserialize a <code>SessionState</code>.
        </li>
        <li>
          The <a href="/pkg/crypto/tls/#Config.WrapSession"><code>Config.WrapSession</code></a> and
          <a href="/pkg/crypto/tls/#Config.UnwrapSession"><code>Config.UnwrapSession</code></a>
          hooks convert a <code>SessionState</code> to and from a ticket on the server side.
        </li>
        <li>
          The <a href="/pkg/crypto/tls/#Config.EncryptTicket"><code>Config.EncryptTicket</code></a>
          and <a href="/pkg/crypto/tls/#Config.DecryptTicket"><code>Config.DecryptTicket</code></a>
          methods provide a default implementation of <code>WrapSession</code> and
          <code>UnwrapSession</code>.
        </li>
        <li>
          The <a href="/pkg/crypto/tls/#ClientSessionState.ResumptionState"><code>ClientSessionState.ResumptionState</code></a> method and
          <a href="/pkg/crypto/tls/#NewResumptionState"><code>NewResumptionState</code></a> function
          may be used by a <code>ClientSessionCache</code> implementation to store and
          resume sessions on the client side.
        </li>
      </ul>
    </p>

    <p><!-- CL 496817 -->
      To reduce the potential for session tickets to be used as a tracking
      mechanism across connections, the server now issues new tickets on every
      resumption (if they are supported and not disabled) and tickets don't bear
      an identifier for the key that encrypted them anymore. If passing a large
      number of keys to <a href="/pkg/crypto/tls/#Conn.SetSessionTicketKeys"><code>Conn.SetSessionTicketKeys</code></a>,
      this might lead to a noticeable performance cost.
    </p>

    <p><!-- CL 497376 -->
      Both clients and servers now implement the Extended Master Secret extension (RFC 7627).
      The deprecation of <a href="/pkg/crypto/tls/#ConnectionState.TLSUnique"><code>ConnectionState.TLSUnique</code></a>
      has been reverted, and is now set for resumed connections that support Extended Master Secret.
    </p>

    <p><!-- https://go.dev/issue/44886, https://go.dev/issue/60107, CL 493655, CL 496995 -->
      The new <a href="/pkg/crypto/tls/#QUICConn"><code>QUICConn</code></a> type
      provides support for QUIC implementations, including 0-RTT support. Note
      that this is not itself a QUIC implementation, and 0-RTT is still not
      supported in TLS.
    </p>

    <p><!-- https://go.dev/issue/46308, CL 497377 -->
      The new <a href="/pkg/crypto/tls/#VersionName"><code>VersionName</code></a> function
      returns the name for a TLS version number.
    </p>

    <p><!-- https://go.dev/issue/52113, CL 410496 -->
      The TLS alert codes sent from the server for client authentication failures have
      been improved. Previously, these failures always resulted in a "bad certificate" alert.
      Now, certain failures will result in more appropriate alert codes,
      as defined by RFC 5246 and RFC 8446:
      <ul>
        <li>
          For TLS 1.3 connections, if the server is configured to require client authentication using
          <a href="/pkg/crypto/tls/#RequireAnyClientCert"></code>RequireAnyClientCert</code></a> or
          <a href="/pkg/crypto/tls/#RequireAndVerifyClientCert"></code>RequireAndVerifyClientCert</code></a>,
          and the client does not provide any certificate, the server will now return the "certificate required" alert.
        </li>
        <li>
          If the client provides a certificate that is not signed by the set of trusted certificate authorities
          configured on the server, the server will return the "unknown certificate authority" alert.
        </li>
        <li>
          If the client provides a certificate that is either expired or not yet valid,
          the server will return the "expired certificate" alert.
        </li>
        <li>
          In all other scenarios related to client authentication failures, the server still returns "bad certificate".
        </li>
      </ul>
    </p>
  </dd>
</dl><!-- crypto/tls -->

<dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/53573, CL 468875 -->
      <a href="/pkg/crypto/x509/#RevocationList.RevokedCertificates"><code>RevocationList.RevokedCertificates</code></a> has been deprecated and replaced with the new <a href="/pkg/crypto/x509/#RevocationList.RevokedCertificateEntries"><code>RevokedCertificateEntries</code></a> field, which is a slice of <a href="/pkg/crypto/x509/#RevocationListEntry"><code>RevocationListEntry</code></a>. <a href="/pkg/crypto/x509/#RevocationListEntry"><code>RevocationListEntry</code></a> contains all of the fields in <a href="/pkg/crypto/x509/pkix#RevokedCertificate"><code>pkix.RevokedCertificate</code></a>, as well as the revocation reason code.
    </p>

    <p><!-- CL 478216 -->
      Name constraints are now correctly enforced on non-leaf certificates, and
      not on the certificates where they are expressed.
    </p>
  </dd>
</dl><!-- crypto/x509 -->

<dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56892, CL 452617 -->
      The new
      <a href="/pkg/debug/elf/#File.DynValue"><code>File.DynValue</code></a>
      method may be used to retrieve the numeric values listed with a
      given dynamic tag.
    </p>

    <p><!-- https://go.dev/issue/56887, CL 452496 -->
      The constant flags permitted in a <code>DT_FLAGS_1</code>
      dynamic tag are now defined with type
      <a href="/pkg/debug/elf/#DynFlag1"><code>DynFlag1</code></a>. These
      tags have names starting with <code>DF_1</code>.
    </p>

    <p><!-- CL 473256 -->
      The package now defines the constant
      <a href="/pkg/debug/elf/#COMPRESS_ZSTD"><code>COMPRESS_ZSTD</code></a>.
    </p>

    <p><!-- https://go.dev/issue/60348, CL 496918 -->
      The package now defines the constant
      <a href="/pkg/debug/elf/#R_PPC64_REL24_P9NOTOC"><code>R_PPC64_REL24_P9NOTOC</code></a>.
    </p>
  </dd>
</dl><!-- debug/elf -->

<dl id="debug/pe"><dt><a href="/pkg/debug/pe/">debug/pe</a></dt>
  <dd>
    <p><!-- CL 488475 -->
      Attempts to read from a section containing uninitialized data
      using
      <a href="/pkg/debug/pe/#Section.Data"><code>Section.Data</code></a>
      or the reader returned by <a href="/pkg/debug/pe/#Section.Open"><code>Section.Open</code></a>
      now return an error.
    </p>
  </dd>
</dl><!-- debug/pe -->

<dl id="embed"><dt><a href="/pkg/embed/">embed</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/57803, CL 483235 -->
      The <a href="/pkg/io/fs/#File"><code>io/fs.File</code></a>
      returned by
      <a href="/pkg/embed/#FS.Open"><code>FS.Open</code></a> now
      has a <code>ReadAt</code> method that
      implements <a href="/pkg/io/#ReaderAt"><code>io.ReaderAt</code></a>.
    </p>

    <p><!-- https://go.dev/issue/54451, CL 491175 -->
      Calling <code><a href="/pkg/embed/FS.Open">FS.Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
      will return a type that now implements a <code>String</code>
      method that calls
      <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
    </p>
  </dd>
</dl><!-- embed -->

<dl id="errors"><dt><a href="/pkg/errors/">errors</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/41198, CL 473935 -->
      The new
      <a href="/pkg/errors/#ErrUnsupported"><code>ErrUnsupported</code></a>
      error provides a standardized way to indicate that a requested
      operation may not be performed because it is unsupported.
      For example, a call to
      <a href="/pkg/os/#Link"><code>os.Link</code></a> when using a
      file system that does not support hard links.
    </p>
  </dd>
</dl><!-- errors -->

<dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/53747, CL 476015 -->
      The new <a href="/pkg/flag/#BoolFunc"><code>BoolFunc</code></a>
      function and
      <a href="/pkg/flag/#FlagSet.BoolFunc"><code>FlagSet.BoolFunc</code></a>
      method define a flag that does not require an argument and calls
      a function when the flag is used. This is similar to
      <a href="/pkg/flag/#Func"><code>Func</code></a> but for a
      boolean flag.
    </p>

    <p><!-- CL 480215 -->
      A flag definition
      (via <a href="/pkg/flag/#Bool"><code>Bool</code></a>,
      <a href="/pkg/flag/#BoolVar"><code>BoolVar</code></a>,
      <a href="/pkg/flag/#Int"><code>Int</code></a>,
      <a href="/pkg/flag/#IntVar"><code>IntVar</code></a>, etc.)
      will panic if <a href="/pkg/flag/#Set"><code>Set</code></a> has
      already been called on a flag with the same name. This change is
      intended to detect cases where <a href="#language">changes in
      initialization order</a> cause flag operations to occur in a
      different order than expected. In many cases the fix to this
      problem is to introduce a explicit package dependence to
      correctly order the definition before any
      <a href="/pkg/flag/#Set"><code>Set</code></a> operations.
    </p>
  </dd>
</dl><!-- flag -->

<dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/28089, CL 487935 -->
      The new <a href="/pkg/go/ast/#IsGenerated"><code>IsGenerated</code></a> predicate
      reports whether a file syntax tree contains the
      <a href="https://go.dev/s/generatedcode">special comment</a>
      that conventionally indicates that the file was generated by a tool.
    </p>
  </dd>

  <dd>
    <p><!-- https://go.dev/issue/59033, CL 476276 -->
      The new
      <a href="/pkg/go/ast/#File.GoVersion"><code>File.GoVersion</code></a>
      field records the minimum Go version required by
      any <code>//go:build</code> or <code>// +build</code>
      directives.
    </p>
  </dd>
</dl><!-- go/ast -->

<dl id="go/build"><dt><a href="/pkg/go/build/">go/build</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56986, CL 453603 -->
      The package now parses build directives (comments that start
      with <code>//go:</code>) in file headers (before
      the <code>package</code> declaration). These directives are
      available in the new
      <a href="/pkg/go/build#Package"><code>Package</code></a> fields
      <a href="/pkg/go/build#Package.Directives"><code>Directives</code></a>,
      <a href="/pkg/go/build#Package.TestDirectives"><code>TestDirectives</code></a>,
      and
      <a href="/pkg/go/build#Package.XTestDirectives"><code>XTestDirectives</code></a>.
    </p>
  </dd>
</dl><!-- go/build -->

<dl id="go/build/constraint"><dt><a href="/pkg/go/build/constraint/">go/build/constraint</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/59033, CL 476275 -->
      The new
      <a href="/pkg/go/build/constraint/#GoVersion"><code>GoVersion</code></a>
      function returns the minimum Go version implied by a build
      expression.
    </p>
  </dd>
</dl><!-- go/build/constraint -->

<dl id="go/token"><dt><a href="/pkg/go/token/">go/token</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/57708, CL 464515 -->
      The new <a href="/pkg/go/token/#File.Lines"><code>File.Lines</code></a> method
      returns the file's line-number table in the same form as accepted by
      <code>File.SetLines</code>.
    </p>
  </dd>
</dl><!-- go/token -->

<dl id="go/types"><dt><a href="/pkg/go/types/">go/types</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/61175, CL 507975 -->
      The new <a href="/pkg/go/types/#Package.GoVersion"><code>Package.GoVersion</code></a>
      method returns the Go language version used to check the package.
    </p>
  </dd>
</dl><!-- go/types -->

<dl id="hash/maphash"><dt><a href="/pkg/hash/maphash/">hash/maphash</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/47342, CL 468795 -->
      The <code>hash/maphash</code> package now has a pure Go implementation, selectable with the <code>purego</code> build tag.
    </p>
  </dd>
</dl><!-- hash/maphash -->

<dl id="html/template"><dt><a href="/pkg/html/template/">html/template</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/59584, CL 496395 -->
      The new error
      <a href="/pkg/html/template/#ErrJSTemplate"><code>ErrJSTemplate</code></a>
      is returned when an action appears in a JavaScript template
      literal. Previously an unexported error was returned.
    </p>
  </dd>
</dl><!-- html/template -->

<dl id="io/fs"><dt><a href="/pkg/io/fs/">io/fs</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/54451, CL 489555 -->
      The new
      <a href="/pkg/io/fs/#FormatFileInfo"><code>FormatFileInfo</code></a>
      function returns a formatted version of a
      <a href="/pkg/io/fs/#FileInfo"><code>FileInfo</code></a>.
      The new
      <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>
      function returns a formatted version of a
      <a href="/pkg/io/fs/#FileInfo"><code>DirEntry</code></a>.
      The implementation of
      <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
      returned by
      <a href="/pkg/io/fs/#ReadDir"><code>ReadDir</code></a> now
      implements a <code>String</code> method that calls
      <a href="/pkg/io/fs/#FormatDirEntry"><code>FormatDirEntry</code></a>,
      and the same is true for
      the <a href="/pkg/io/fs/#DirEntry"><code>DirEntry</code></a>
      value passed to
      <a href="/pkg/io/fs/#WalkDirFunc"><code>WalkDirFunc</code></a>.
    </p>
  </dd>
</dl><!-- io/fs -->

<!-- https://go.dev/issue/56491 rolled back by https://go.dev/issue/60519 -->
<!-- CL 459435 reverted by CL 467255 -->
<!-- CL 467515 reverted by CL 499416 -->

<dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56984, CL 453115, CL 500116 -->
      The new <a href="/pkg/math/big/#Int.Float64"><code>Int.Float64</code></a>
      method returns the nearest floating-point value to a
      multi-precision integer, along with an indication of any
      rounding that occurred.
    </p>
  </dd>
</dl><!-- math/big -->

<dl id="net"><dt><a href="/pkg/net/">net</a></dt>
  <dd>
    <p>
      <!-- https://go.dev/issue/59166, https://go.dev/issue/56539 -->
      <!-- CL 471136, CL 471137, CL 471140 -->
      On Linux, the <a href="/pkg/net/">net</a> package can now use
      Multipath TCP when the kernel supports it. It is not used by
      default. To use Multipath TCP when available on a client, call
      the
      <a href="/pkg/net/#Dialer.SetMultipathTCP"><code>Dialer.SetMultipathTCP</code></a>
      method before calling the
      <a href="/pkg/net/#Dialer.Dial"><code>Dialer.Dial</code></a> or
      <a href="/pkg/net/#Dialer.DialContext"><code>Dialer.DialContext</code></a>
      methods. To use Multipath TCP when available on a server, call
      the
      <a href="/pkg/net/#ListenConfig.SetMultipathTCP"><code>ListenConfig.SetMultipathTCP</code></a>
      method before calling the
      <a href="/pkg/net/#ListenConfig.Listen"><code>ListenConfig.Listen</code></a>
      method. Specify the network as <code>"tcp"</code> or
      <code>"tcp4"</code> or <code>"tcp6"</code> as usual. If
      Multipath TCP is not supported by the kernel or the remote host,
      the connection will silently fall back to TCP. To test whether a
      particular connection is using Multipath TCP, use the
      <a href="/pkg/net/#TCPConn.MultipathTCP"><code>TCPConn.MultipathTCP</code></a>
      method.
    </p>
    <p>
      In a future Go release we may enable Multipath TCP by default on
      systems that support it.
    </p>
  </dd>
</dl><!-- net -->

<dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
  <dd>
    <p><!-- CL 472636 -->
      The new <a href="/pkg/net/http#ResponseController.EnableFullDuplex"><code>ResponseController.EnableFullDuplex</code></a>
      method allows server handlers to concurrently read from an HTTP/1
      request body while writing the response. Normally, the HTTP/1 server
      automatically consumes any remaining request body before starting to
      write the response, to avoid deadlocking clients which attempt to
      write a complete request before reading the response. The
      <code>EnableFullDuplex</code> method disables this behavior.
    </p>

    <p><!-- https://go.dev/issue/44855, CL 382117 -->
      The new <a href="/pkg/net/http/#ErrSchemeMismatch"><code>ErrSchemeMismatch</code></a> error is returned by <a href="/pkg/net/http/#Client"><code>Client</code></a> and <a href="/pkg/net/http/#Transport"><code>Transport</code></a> when the server responds to an HTTPS request with an HTTP response.
    </p>

    <p><!-- CL 494122 -->
      The <a href="/pkg/net/http/">net/http</a> package now supports
      <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
      in that the expression
      <code>errors.Is(http.ErrNotSupported, errors.ErrUnsupported)</code>
      will return true.
    </p>
  </dd>
</dl><!-- net/http -->

<dl id="os"><dt><a href="/pkg/os/">os</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/32558, CL 219638 -->
      Programs may now pass an empty <code>time.Time</code> value to
      the <a href="/pkg/os/#Chtimes"><code>Chtimes</code></a> function
      to leave either the access time or the modification time unchanged.
    </p>

    <p><!-- CL 480135 -->
      On Windows the
      <a href="/pkg/os#File.Chdir"><code>File.Chdir</code></a> method
      now changes the current directory to the file, rather than
      always returning an error.
    </p>

    <p><!-- CL 495079 -->
      On Unix systems, if a non-blocking descriptor is passed
      to <a href="/pkg/os/#NewFile"><code>NewFile</code></a>, calling
      the <a href="/pkg/os/#File.Fd"><code>File.Fd</code></a> method
      will now return a non-blocking descriptor. Previously the
      descriptor was converted to blocking mode.
    </p>

    <p><!-- CL 477215 -->
      On Windows calling
      <a href="/pkg/os/#Truncate"><code>Truncate</code></a> on a
      non-existent file used to create an empty file. It now returns
      an error indicating that the file does not exist.
    </p>

    <p><!-- https://go.dev/issue/56899, CL 463219 -->
      On Windows calling
      <a href="/pkg/os/#TempDir"><code>TempDir</code></a> now uses
      GetTempPath2W when available, instead of GetTempPathW. The
      new behavior is a security hardening measure that prevents
      temporary files created by processes running as SYSTEM to
      be accessed by non-SYSTEM processes.
    </p>

    <p><!-- CL 493036 -->
      On Windows the os package now supports working with files whose
      names, stored as UTF-16, can't be represented as valid UTF-8.
    </p>

    <p><!-- CL 463177 -->
      On Windows <a href="/pkg/os/#Lstat"><code>Lstat</code></a> now resolves
      symbolic links for paths ending with a path separator, consistent with its
      behavior on POSIX platforms.
    </p>

    <p><!-- https://go.dev/issue/54451, CL 491175 -->
      The implementation of the
      <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
      interface returned by the
      <a href="/pkg/os/#ReadDir"><code>ReadDir</code></a> function and
      the <a href="/pkg/os/#File.ReadDir"><code>File.ReadDir</code></a>
      method now implements a <code>String</code> method that calls
      <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
    </p>

    <p><!-- https://go.dev/issue/53761, CL 416775, CL 498015-->
    The implementation of the
    <a href="/pkg/io/fs/#FS"><code>io/fs.FS</code></a> interface returned by
    the <a href="/pkg/os/#DirFS"><code>DirFS</code></a> function now implements
    the <a href="/pkg/io/fs/#ReadFileFS"><code>io/fs.ReadFileFS</code></a> and
    the <a href="/pkg/io/fs/#ReadDirFS"><code>io/fs.ReadDirFS</code></a>
    interfaces.
    </p>
  </dd>
</dl><!-- os -->

<dl id="path/filepath"><dt><a href="/pkg/path/filepath/">path/filepath</a></dt>
  <dd>
    <p>
      The implementation of the
      <a href="/pkg/io/fs/#DirEntry"><code>io/fs.DirEntry</code></a>
      interface passed to the function argument of
      <a href="/pkg/path/filepath/#WalkDir"><code>WalkDir</code></a>
      now implements a <code>String</code> method that calls
      <a href="/pkg/io/fs/#FormatDirEntry"><code>io/fs.FormatDirEntry</code></a>.
    </p>
  </dd>
</dl><!-- path/filepath -->

<!-- CL 459455 reverted -->

<dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
  <dd>
    <p><!-- CL 408826, CL 413474 -->
      In Go 1.21, <a href="/pkg/reflect/#ValueOf"><code>ValueOf</code></a>
      no longer forces its argument to be allocated on the heap, allowing
      a <code>Value</code>'s content to be allocated on the stack. Most
      operations on a <code>Value</code> also allow the underlying value
      to be stack allocated.
    </p>

    <p><!-- https://go.dev/issue/55002 -->
      The new <a href="/pkg/reflect/#Value"><code>Value</code></a>
      method <a href="/pkg/reflect/#Value.Clear"><code>Value.Clear</code></a>
      clears the contents of a map or zeros the contents of a slice.
      This corresponds to the new <code>clear</code> built-in
      <a href="#language">added to the language</a>.
    </p>

    <p><!-- https://go.dev/issue/56906, CL 452762 -->
      The <a href="/pkg/reflect/#SliceHeader"><code>SliceHeader</code></a>
      and <a href="/pkg/reflect/#StringHeader"><code>StringHeader</code></a>
      types are now deprecated. In new code
      prefer <a href="/pkg/unsafe/#Slice"><code>unsafe.Slice</code></a>,
      <a href="/pkg/unsafe/#SliceData"><code>unsafe.SliceData</code></a>,
      <a href="/pkg/unsafe/#String"><code>unsafe.String</code></a>,
      or <a href="/pkg/unsafe/#StringData"><code>unsafe.StringData</code></a>.
    </p>
  </dd>
</dl><!-- reflect -->

<dl id="regexp"><dt><a href="/pkg/regexp/">regexp</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/46159, CL 479401 -->
      <a href="/pkg/regexp#Regexp"><code>Regexp</code></a> now defines
      <a href="/pkg/regexp#Regexp.MarshalText"><code>MarshalText</code></a>
      and <a href="/pkg/regexp#Regexp.UnmarshalText"><code>UnmarshalText</code></a>
      methods. These implement
      <a href="/pkg/encoding#TextMarshaler"><code>encoding.TextMarshaler</code></a>
      and
      <a href="/pkg/encoding#TextUnmarshaler"><code>encoding.TextUnmarshaler</code></a>
      and will be used by packages such as
      <a href="/pkg/encoding/json">encoding/json</a>.
    </p>
  </dd>
</dl><!-- regexp -->

<dl id="runtime"><dt><a href="/pkg/runtime/">runtime</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/38651, CL 435337 -->
      Textual stack traces produced by Go programs, such as those
      produced when crashing, calling <code>runtime.Stack</code>, or
      collecting a goroutine profile with <code>debug=2</code>, now
      include the IDs of the goroutines that created each goroutine in
      the stack trace.
    </p>

    <p><!-- https://go.dev/issue/57441, CL 474915 -->
      Crashing Go applications can now opt-in to Windows Error Reporting (WER) by setting the environment variable
      <code>GOTRACEBACK=wer</code> or calling <a href="/pkg/runtime/debug/#SetTraceback"><code>debug.SetTraceback("wer")</code></a>
      before the crash. Other than enabling WER, the runtime will behave as with <code>GOTRACEBACK=crash</code>.
      On non-Windows systems, <code>GOTRACEBACK=wer</code> is ignored.
    </p>

    <p><!-- CL 447778 -->
      <code>GODEBUG=cgocheck=2</code>, a thorough checker of cgo pointer passing rules,
      is no longer available as a <a href="/pkg/runtime#hdr-Environment_Variables">debug option</a>.
      Instead, it is available as an experiment using <code>GOEXPERIMENT=cgocheck2</code>.
      In particular this means that this mode has to be selected at build time instead of startup time.
    </p>

    <p>
      <code>GODEBUG=cgocheck=1</code> is still available (and is still the default).
    </p>

    <p><!-- https://go.dev/issue/46787, CL 367296 -->
      A new type <code>Pinner</code> has been added to the runtime
      package. <code>Pinner</code>s may be used to "pin" Go memory
      such that it may be used more freely by non-Go code. For instance,
      passing Go values that reference pinned Go memory to C code is
      now allowed. Previously, passing any such nested reference was
      disallowed by the
      <a href="https://pkg.go.dev/cmd/cgo#hdr-Passing_pointers">cgo pointer passing rules.</a>

      See <a href="/pkg/runtime#Pinner">the docs</a> for more details.
    </p>

    <!-- CL 472195 no release note needed -->
  </dd>
</dl><!-- runtime -->

<dl id="runtime/metrics"><dt><a href="/pkg/runtime/metrics/">runtime/metrics</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56857, CL 497315 -->
      A few previously-internal GC metrics, such as live heap size, are
      now available.

      <code>GOGC</code> and <code>GOMEMLIMIT</code> are also now
      available as metrics.
    </p>
  </dd>
</dl><!-- runtime/metrics -->

<dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/16638 -->
      Collecting traces on amd64 and arm64 now incurs a substantially
      smaller CPU cost: up to a 10x improvement over the previous release.
    </p>

    <p><!-- CL 494495 -->
      Traces now contain explicit stop-the-world events for every reason
      the Go runtime might stop-the-world, not just garbage collection.
    </p>
  </dd>
</dl><!-- runtime/trace -->

<dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56102, CL 451356 -->
      The new <a href="/pkg/sync/#OnceFunc"><code>OnceFunc</code></a>,
      <a href="/pkg/sync/#OnceValue"><code>OnceValue</code></a>, and
      <a href="/pkg/sync/#OnceValues"><code>OnceValues</code></a>
      functions capture a common use of <a href="/pkg/sync/#Once">Once</a> to
      lazily initialize a value on first use.
    </p>
  </dd>
</dl>

<dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
  <dd>
    <p><!-- CL 480135 -->
      On Windows the
      <a href="/pkg/syscall#Fchdir"><code>Fchdir</code></a> function
      now changes the current directory to its argument, rather than
      always returning an error.
    </p>

    <p><!-- https://go.dev/issue/46259, CL 458335 -->
      On FreeBSD
      <a href="/pkg/syscall#SysProcAttr"><code>SysProcAttr</code></a>
      has a new field <code>Jail</code> that may be used to put the
      newly created process in a jailed environment.
    </p>

    <p><!-- CL 493036 -->
      On Windows the syscall package now supports working with files whose
      names, stored as UTF-16, can't be represented as valid UTF-8.
      The <a href="/pkg/syscall#UTF16ToString"><code>UTF16ToString</code></a>
      and <a href="/pkg/syscall#UTF16FromString"><code>UTF16FromString</code></a>
      functions now convert between UTF-16 data and
      <a href="https://simonsapin.github.io/wtf-8/">WTF-8</a> strings.
      This is backward compatible as WTF-8 is a superset of the UTF-8
      format that was used in earlier releases.
    </p>

    <p><!-- CL 476578, CL 476875, CL 476916 -->
      Several error values match the new
      <a href="/pkg/errors/#ErrUnsupported"><code>errors.ErrUnsupported</code></a>,
      such that <code>errors.Is(err, errors.ErrUnsupported)</code>
      returns true.
      <ul>
        <li><code>ENOSYS</code></li>
        <li><code>ENOTSUP</code></li>
        <li><code>EOPNOTSUPP</code></li>
        <li><code>EPLAN9</code> (Plan 9 only)</li>
        <li><code>ERROR_CALL_NOT_IMPLEMENTED</code> (Windows only)</li>
        <li><code>ERROR_NOT_SUPPORTED</code> (Windows only)</li>
        <li><code>EWINDOWS</code> (Windows only)</li>
      </ul>
    </p>
  </dd>
</dl><!-- syscall -->

<dl id="testing"><dt><a href="/pkg/testing/">testing</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/37708, CL 463837 -->
      The new <code>-test.fullpath</code> option will print full path
      names in test log messages, rather than just base names.
    </p>

    <p><!-- https://go.dev/issue/52600, CL 475496 -->
      The new <a href="/pkg/testing/#Testing"><code>Testing</code></a> function reports whether the program is a test created by <code>go</code> <code>test</code>.
    </p>
  </dd>
</dl><!-- testing -->

<dl id="testing/fstest"><dt><a href="/pkg/testing/fstest/">testing/fstest</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/54451, CL 491175 -->
      Calling <code><a href="/pkg/testing/fstest/MapFS.Open">Open</a>.<a href="/pkg/io/fs/#File.Stat">Stat</a></code>
      will return a type that now implements a <code>String</code>
      method that calls
      <a href="/pkg/io/fs/#FormatFileInfo"><code>io/fs.FormatFileInfo</code></a>.
    </p>
  </dd>
</dl><!-- testing/fstest -->

<dl id="unicode"><dt><a href="/pkg/unicode/">unicode</a></dt>
  <dd>
    <p><!-- CL 456837 -->
      The <a href="/pkg/unicode/"><code>unicode</code></a> package and
      associated support throughout the system has been upgraded to
      <a href="https://www.unicode.org/versions/Unicode15.0.0/">Unicode 15.0.0</a>.
    </p>
  </dd>
</dl><!-- unicode -->

<h2 id="ports">Ports</h2>

<h3 id="darwin">Darwin</h3>

<p><!-- https://go.dev/issue/57125 -->
  As <a href="go1.20#darwin">announced</a> in the Go 1.20 release notes,
  Go 1.21 requires macOS 10.15 Catalina or later;
  support for previous versions has been discontinued.
</p>

<h3 id="windows">Windows</h3>

<p><!-- https://go.dev/issue/57003, https://go.dev/issue/57004 -->
  As <a href="go1.20#windows">announced</a> in the Go 1.20 release notes,
  Go 1.21 requires at least Windows 10 or Windows Server 2016;
  support for previous versions has been discontinued.
</p>

<!-- CL 470695 -->
<p>
  <!-- cmd/dist: default to GOARM=7 on all non-arm systems -->
</p>

<h3 id="wasm">WebAssembly</h3>

<p><!-- https://go.dev/issue/38248, https://go.dev/issue/59149, CL 489255 -->
  The new <code>go:wasmimport</code> directive can now be used in Go programs
  to import functions from the WebAssembly host.
</p>

<!-- https://go.dev/issue/56100 -->
<p>
  The Go scheduler now interacts much more efficiently with the
  JavaScript event loop, especially in applications that block
  frequently on asynchronous events.
</p>


<h3 id="wasip1">WebAssembly System Interface</h3>

<p><!-- https://go.dev/issue/58141 -->
  Go 1.21 adds an experimental port to the <a href="https://wasi.dev/">
  WebAssembly System Interface (WASI)</a>, Preview 1
  (<code>GOOS=wasip1</code>, <code>GOARCH=wasm</code>).
</p>

<p>
  As a result of the addition of the new <code>GOOS</code> value
  "<code>wasip1</code>", Go files named <code>*_wasip1.go</code>
  will now be <a href="/pkg/go/build/#hdr-Build_Constraints">ignored
  by Go tools</a> except when that <code>GOOS</code> value is being
  used.
  If you have existing filenames matching that pattern, you will
  need to rename them.
</p>

<h3 id="PPC64">ppc64/ppc64le</h3>

<p><!-- go.dev/issue/44549 -->
  On Linux, <code>GOPPC64=power10</code> now generates PC-relative instructions, prefixed
  instructions, and other new Power10 instructions. On AIX, <code>GOPPC64=power10</code>
  generates Power10 instructions, but does not generate PC-relative instructions.
</p>

<p>
  When building position-independent binaries for <code>GOPPC64=power10</code>
  <code>GOOS=linux</code> <code>GOARCH=ppc64le</code>, users can expect reduced binary
  sizes in most cases, in some cases 3.5%. Position-independent binaries are built for
  ppc64le with the following <code>-buildmode</code> values:
  <code>c-archive</code>, <code>c-shared</code>, <code>shared</code>, <code>pie</code>, <code>plugin</code>.
</p>

<h3 id="loong64">loong64</h3>

<p><!-- go.dev/issue/53301, CL 455075, CL 425474, CL 425476, CL 425478, CL 489576 -->
  The <code>linux/loong64</code> port now supports <code>-buildmode=c-archive</code>,
  <code>-buildmode=c-shared</code> and <code>-buildmode=pie</code>.
</p>

<!-- proposals for x repos that don't need to be mentioned here but
     are picked up by the relnote tool. -->
<!-- https://go.dev/issue/54232 -->
<!-- https://go.dev/issue/57051 -->
<!-- https://go.dev/issue/57792 -->
<!-- https://go.dev/issue/57906 -->
<!-- https://go.dev/issue/58668 -->
<!-- https://go.dev/issue/59016 -->
<!-- https://go.dev/issue/59676 -->
<!-- https://go.dev/issue/60409 -->
<!-- https://go.dev/issue/61176 -->

<!-- changes to cmd/api that don't need release notes. -->
<!-- CL 469115, CL 469135, CL 499981 -->

<!-- proposals that don't need release notes. -->
<!-- https://go.dev/issue/10275 -->
<!-- https://go.dev/issue/59719 -->