go/doc/go1.22.html

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

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

<p>
  <strong>
    Go 1.22 is not yet released. These are work-in-progress
    release notes. Go 1.22 is expected to be released in February 2024.
  </strong>
</p>

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

<p>
<!-- loop variable scope --><!-- range over int -->
Go 1.22 makes two changes to "for" loops.
<ul>
  <li>
    Previously, the variables declared by a "for" loop were created once and updated by each iteration. In Go 1.22, each iteration of the loop creates new variables, to avoid accidental sharing bugs.
    The <a href="https://go.dev/wiki/LoopvarExperiment#my-test-fails-with-the-change-how-can-i-debug-it">transition support tooling</a>
    described in the proposal continues to work in the same way it did in Go 1.21.
  </li>
  <li>
    "For" loops may now range over integers.
    For <a href="https://go.dev/play/p/ky02zZxgk_r?v=gotip">example</a>:
<pre>
package main

import "fmt"

func main() {
  for i := range 10 {
    fmt.Println(10 - i)
  }
  fmt.Println("go1.22 has lift-off!")
}
</pre>
    See the spec for <a href="/ref/spec#For_range">details</a>.
  </li>
</ul>

<!-- range over func GOEXPERIMENT; https://go.dev/issue/61405, https://go.dev/issue/61897, CLs 510541,539277,540263,543319 -->
</p>
<p>
  Go 1.22 includes a preview of a language change we are considering
  for a future version of Go: <a href="https://go.dev/wiki/RangefuncExperiment">range-over-function iterators</a>.
  Building with <code>GOEXPERIMENT=rangefunc</code> enables this feature.
</p>

<h2 id="tools">Tools</h2>

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

<!-- https://go.dev/issue/60056 -->
<p>
  Commands in <a href="https://go.dev/ref/mod#workspaces">workspaces</a> can now
  use a <code>vendor</code> directory containing the dependencies of the
  workspace. The directory is created by
  <a href="/pkg/cmd/go#hdr-Make_vendored_copy_of_dependencies"><code>go</code> <code>work</code> <code>vendor</code></a>,
  and used by build commands when the <code>-mod</code> flag is set to
	<code>vendor</code>, which is the default when a workspace <code>vendor</code>
  directory is present.
</p>
<p>
  Note that the <code>vendor</code> directory's contents for a workspace are different
  from those of a single module: if the directory at the root of a workspace also
  contains one of the modules in the workspace, its <code>vendor</code> directory
  can contain the dependencies of either the workspace or of the module,
  but not both.
</p>

<!-- CL 518775, https://go.dev/issue/60915 -->
<p>
  <code>go</code> <code>get</code> is no longer supported outside of a module in the
  legacy <code>GOPATH</code> mode (that is, with <code>GO111MODULE=off</code>).
  Other build commands, such as <code>go</code> <code>build</code> and
  <code>go</code> <code>test</code>, will continue to work indefinitely
  for legacy <code>GOPATH</code> programs.
</p>

<!-- CL 518776 -->
<p>
  <code>go</code> <code>mod</code> <code>init</code> no longer attempts to import
  module requirements from configuration files for other vendoring tools
  (such as <code>Gopkg.lock</code>).
</p>

<!-- CL 495447 -->
<p>
<code>go</code> <code>test</code> <code>-cover</code> now prints coverage summaries for covered
packages that do not have their own test files. Prior to Go 1.22 a
<code>go</code> <code>test</code> <code>-cover</code> run for such a package would report
</p>

<p>
  <code>?     mymod/mypack    [no test files]</code>
</p>

<p>
  and now with Go 1.22, functions in the package are treated as uncovered:
</p>

<p>
  <code>mymod/mypack    coverage: 0.0% of statements</code>
</p>

<h3 id="trace">Trace</h3>

<!-- https://go.dev/issue/63960 -->
<p>
  The <code>trace</code> tool's web UI has been gently refreshed as part of the
  work to support the new tracer, resolving several issues and improving the
  readability of various sub-pages.
  The web UI now supports exploring traces in a thread-oriented view.
  The trace viewer also now displays the full duration of all system calls.
  <br />
  These improvements only apply for viewing traces produced by programs built with
  Go 1.22 or newer.
  A future release will bring some of these improvements to traces produced by older
  version of Go.
</p>

<h3 id="vet">Vet</h3>

<h4 id="vet-loopclosure">References to loop variables</h4>

<p><!-- CL 539016, https://go.dev/issue/63888: cmd/vet: do not report variable capture for loop variables with the new lifetime rules -->
  The behavior of the <code>vet</code> tool has changed to match
  the new semantics (see above) of loop variables in Go 1.22.
  When analyzing a file that requires Go 1.22 or newer
  (due to its go.mod file or a per-file build constraint),
  <code>vet</code>code> no longer reports references to
  loop variables from within a function literal that
  might outlive the iteration of the loop.
  In Go 1.22, loop variables are created anew for each iteration,
  so such references are no longer at risk of using a variable
  after it has been updated by the loop.
</p>

<h4 id="vet-appends">New warnings for missing values after append</h4>

<p><!-- CL 498416, https://go.dev/issue/60448: add a new analyzer for check missing values after append -->
  The <code>vet</code> tool now reports calls to
  <a href="/pkg/builtin/#append"><code>append</code></a> that pass
  no values to be appended to the slice, such as <code>slice = append(slice)</code>.
  Such a statement has no effect, and experience has shown that is nearly always a mistake.
</p>

<h4 id="vet-defers">New warnings for deferring <code>time.Since</code></h4>

<p><!-- CL 527095, https://go.dev/issue/60048: time.Since should not be used in defer statement -->
  The vet tool now reports a non-deferred call to
  <a href="/pkg/time/#Since"><code>time.Since(t)</code></a> within a <code>defer</code> statement.
  This is equivalent to calling <code>time.Now().Sub(t)</code> before the <code>defer</code> statement,
  not when the deferred function is called. In nearly all cases, the correct code
  requires deferring the <code>time.Since</code> call. For example:
</p>

<pre>
t := time.Now()
defer log.Println(time.Since(t)) // non-deferred call to time.Since
tmp := time.Since(t); defer log.Println(tmp) // equivalent to the previous defer

defer func() {
  log.Println(time.Since(t)) // a correctly deferred call to time.Since
}()
</pre>

<h4 id="vet-slog">New warnings for mismatched key-value pairs in <code>log/slog</code> calls</h4>

<p><!-- CL 496156, https://go.dev/issue/59407: log/slog: add vet checks for variadic ...any inputs -->
  The vet tool now reports invalid arguments in calls to functions and methods
  in the structured logging package, <a href="/pkg/log/slog"><code>log/slog</code></a>,
  that accept alternating key/value pairs.
  It reports calls where an argument in a key position is neither a
  <code>string</code> nor a <code>slog.Attr</code>, and where a final key is missing its value.
</p>

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

<p><!-- CL 543255 -->
  The runtime now keeps type-based garbage collection metadata nearer to each
  heap object, improving the CPU performance (latency or throughput) of Go programs
  by 1&ndash;3%.
  This change also reduces the memory overhead of the majority Go programs by
  approximately 1% by deduplicating redundant metadata.
  Some programs may see a smaller improvement because this change adjusts the size
  class boundaries of the memory allocator, so some objects may be moved up a size
  class.
</p>
<p>
  A consequence of this change is that some objects' addresses that were previously
  always aligned to a 16 byte (or higher) boundary will now only be aligned to an 8
  byte boundary.
  Some programs that use assembly instructions that require memory addresses to be
  more than 8-byte aligned and rely on the memory allocator's previous alignment behavior
  may break, but we expect such programs to be rare.
  Such programs may be built with <code>GOEXPERIMENT=noallocheaders</code> to revert
  to the old metadata layout and restore the previous alignment behavior, but package
  owners should update their assembly code to avoid the alignment assumption, as this
  workaround will be removed in a future release.
</p>

<p><!-- CL 525475 -->
  On the <code>windows/amd64 port</code>, programs linking or loading Go libraries built with
  <code>-buildmode=c-archive</code> or <code>-buildmode=c-shared</code> can now use
  the <code>SetUnhandledExceptionFilter</code> Win32 function to catch exceptions not handled
  by the Go runtime. Note that this was already supported on the <code>windows/386</code> port.
</p>

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

<p><!-- https://go.dev/issue/61577 -->
  <a href="https://go.dev/doc/pgo">Profile-guided Optimization (PGO)</a> builds
  can now devirtualize a higher proportion of calls than previously possible.
  Most programs from a representative set of Go programs now see between 2 and
  14% improvement from enabling PGO.
</p>

<p><!-- https://go.dev/cl/528321 -->
  The compiler now interleaves devirtualization and inlining, so interface
  method calls are better optimized.
</p>

<p><!-- https://go.dev/issue/61502 -->
  Go 1.22 also includes a preview of an enhanced implementation of the compiler's inlining phase that uses heuristics to boost inlinability at call sites deemed "important" (for example, in loops) and discourage inlining at call sites deemed "unimportant" (for example, on panic paths).
  Building with <code>GOEXPERIMENT=newinliner</code> enables the new call-site
  heuristics; see <a href="https://go.dev/issue/61502">issue #61502</a> for
  more info and to provide feedback.
</p>

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

<p><!-- CL 493136 -->
  The linker's <code>-s</code> and <code>-w</code> flags are now behave more
  consistently across all platforms.
  The <code>-w</code> flag suppresses DWARF debug information generation.
  The <code>-s</code> flag suppresses symbol table generation.
  The <code>-s</code> flag also implies the <code>-w</code> flag, which can be
  negated with <code>-w=0</code>.
  That is, <code>-s</code> <code>-w=0</code> will generate a binary with DWARF
  debug information generation but without the symbol table.
</p>

<p><!-- CL 511475 -->
  On ELF platforms, the <code>-B</code> linker flag now accepts a special form:
  with <code>-B</code> <code>gobuildid</code>, the linker will generate a GNU
  build ID (the ELF <code>NT_GNU_BUILD_ID</code> note) derived from the Go
  build ID.
</p>

<p><!-- CL 534555 -->
  On Windows, when building with <code>-linkmode=internal</code>, the linker now
  preserves SEH information from C object files by copying the <code>.pdata</code>
  and <code>.xdata</code> sections into the final binary.
  This helps with debugging and profiling binaries using native tools, such as WinDbg.
  Note that until now, C functions' SEH exception handlers were not being honored,
  so this change may cause some programs to behave differently.
  <code>-linkmode=external</code> is not affected by this change, as external linkers
  already preserve SEH information.
</p>

<h2 id="bootstrap">Bootstrap</h2>

<p>
  As mentioned in the <a href="/doc/go1.20#bootstrap">Go 1.20 release notes</a>, Go 1.22 now requires
  the final point release of Go 1.20 or later for bootstrap.
  We expect that Go 1.24 will require the final point release of Go 1.22 or later for bootstrap.
</p>

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

<h3 id="math_rand_v2">New math/rand/v2 package</h3>

<!-- CL 502495 -->
<!-- CL 502497 -->
<!-- CL 502498 -->
<!-- CL 502499 -->
<!-- CL 502500 -->
<!-- CL 502505 -->
<!-- CL 502506 -->
<!-- CL 516857 -->
<!-- CL 516859 -->

<p>
  Go 1.22 includes the first “v2” package in the standard library,
  <a href="/pkg/math/rand/v2/"><code>math/rand/v2</code></a>.
  The changes compared to <a href="/pkg/math/rand/"><code>math/rand</code></a> are
  detailed in <a href="/issue/61716">proposal #61716</a>. The most important changes are:
</p>

<ul>
<li>The <code>Read</code> method, deprecated in <code>math/rand</code>,
was not carried forward for <code>math/rand/v2</code>.
(It remains available in <code>math/rand</code>.)
The vast majority of calls to <code>Read</code> should use
<a href="/pkg/crypto/rand/#Read"><code>crypto/rand</code>’s <code>Read</code></a> instead.
Otherwise a custom <code>Read</code> can be constructed using the <code>Uint64</code> method.

<li>The global generator accessed by top-level functions is unconditionally randomly seeded.
Because the API guarantees no fixed sequence of results,
optimizations like per-thread random generator states are now possible.

<li>The <a href="/pkg/math/rand/v2/#Source"><code>Source</code></a>
interface now has a single <code>Uint64</code> method;
there is no <code>Source64</code> interface.

<li>Many methods now use faster algorithms that were not possible to adopt in <code>math/rand</code>
because they changed the output streams.

<li>The
<code>Intn</code>,
<code>Int31</code>,
<code>Int31n</code>,
<code>Int63</code>,
and
<code>Int64n</code>
top-level functions and methods from <code>math/rand</code>
are spelled more idiomatically in <code>math/rand/v2</code>:
<code>IntN</code>,
<code>Int32</code>,
<code>Int32N</code>,
<code>Int64</code>,
and
<code>Int64N</code>.
There are also new top-level functions and methods
<code>Uint32</code>,
<code>Uint32N</code>,
<code>Uint64</code>,
<code>Uint64N</code>,
<code>Uint</code>,
and
<code>UintN</code>.

<li>The
new generic function <a href="/pkg/math/rand/v2/#N"><code>N</code></a>
is like
<a href="/pkg/math/rand/v2/#Int64N"><code>Int64N</code></a> or
<a href="/pkg/math/rand/v2/#Uint64N"><code>Uint64N</code></a>
but works for any integer type.
For example a random duration from 0 up to 5 minutes is
<code>rand.N(5*time.Minute)</code>.

<li>The Mitchell & Reeds LFSR generator provided by
<a href="/pkg/math/rand/#Source"><code>math/rand</code>’s <code>Source</code></a>
has been replaced by two more modern pseudo-random generator sources:
<a href="/pkg/math/rand/v2/#ChaCha8"><code>ChaCha8</code></a>
<a href="/pkg/math/rand/v2/#PCG"><code>PCG</code></a>.
ChaCha8 is a new, cryptographically strong random number generator
roughly similar to PCG in efficiency.
ChaCha8 is the algorithm used for the top-level functions in <code>math/rand/v2</code>.
As of Go 1.22, <code>math/rand</code>'s top-level functions (when not explicitly seeded)
and the Go runtime also use ChaCha8 for randomness.
</ul>

<p>
We plan to include an API migration tool in a future release, likely Go 1.23.
</p>

<h3 id="enhanced_routing_patterns">Enhanced routing patterns</h3>

<p><!-- https://go.dev/issue/61410 -->
  HTTP routing in the standard library is now more expressive.
  The patterns used by <a href="/pkg/net/http#ServeMux"><code>net/http.ServeMux</code></a> have been enhanced to accept methods and wildcards.
</p>

<p>
  Registering a handler with a method, like <code>"POST /items/create"</code>, restricts
  invocations of the handler to requests with the given method. A pattern with a method takes precedence over a matching pattern without one.
  As a special case, registering a handler with <code> "GET"</code> also registers it with <code>"HEAD"</code>.
</p>

<p>
  Wildcards in patterns, like <code>/items/{id}</code>, match segments of the URL path.
  The actual segment value may be accessed by calling the <a href="/pkg/net/http#Request.PathValue"><code>Request.PathValue</code></a> method.
  A wildcard ending in "...", like <code>/files/{path...}</code>, must occur at the end of a pattern and matches all the remaining segments.
</p>

<p>
  A pattern that ends in "/" matches all paths that have it as a prefix, as always.
  To match the exact pattern including the trailing slash, end it with <code>{$}</code>,
  as in <code>/exact/match/{$}</code>.
</p>

<p>
  If two patterns overlap in the requests that they match, then the more specific pattern takes precedence.
  If neither is more specific, the patterns conflict.
  This rule generalizes the original precedence rules and maintains the property that the order in which
  patterns are registered does not matter.
</p>

<p>
  This change breaks backwards compatibility in small ways, some obvious&mdash;patterns with "{" and "}" behave differently&mdash;
  and some less so&mdash;treatment of escaped paths has been improved.
  The change is controlled by a <a href="/doc/godebug"><code>GODEBUG</code></a> field named <code>httpmuxgo121</code>.
  Set <code>httpmuxgo121=1</code> to restore the old behavior.
</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>

<!-- <p> -->
<!--   TODO: complete this section -->
<!-- </p> -->

<dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/58000, CL 513316 -->
      The new method <a href="/pkg/archive/tar#Writer.AddFS"><code>Writer.AddFS</code></a> adds all of the files from an <a href="/pkg/io/fs#FS"><code>fs.FS</code></a> to the archive.
    </p>

    <p><!-- https://go.dev/issue/50102, CL 514235 -->
      If the argument to <a href="/pkg/archive/tar#FileInfoHeader"><code>FileInfoHeader</code></a> implements the new <a href="/pkg/archive/tar#FileInfoNames"><code>FileInfoNames</code></a> interface, then the interface methods will be used to set the UID/GID of the file header. This allows applications to override the default UID/GID resolution.
    </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/54898, CL 513438 -->
      The new method <a href="/pkg/archive/zip#Writer.AddFS"><code>Writer.AddFS</code></a> adds all of the files from an <a href="/pkg/io/fs#FS"><code>fs.FS</code></a> to the archive.
    </p>
  </dd>
</dl><!-- archive/zip -->

<dl id="bufio"><dt><a href="/pkg/bufio/">bufio</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56381, CL 498117 -->
      When a <a href="/pkg/bufio#SplitFunc"><code>SplitFunc</code></a> returns <a href="/pkg/bufio#ErrFinalToken"><code>ErrFinalToken</code></a> with a <code>nil</code> token, <a href="/pkg/bufio#Scanner"><code>Scanner</code></a> will now stop immediately.
      Previously, it would report a final empty token before stopping, which was usually not desired.
      Callers that do want to report a final empty token can do so by returning <code>[]byte{}</code> rather than <code>nil</code>.
    </p>
  </dd>
</dl><!-- bufio -->

<dl id="cmp"><dt><a href="/pkg/cmp/">cmp</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/60204 --><!-- CL 504883 -->
      The new function <code>Or</code> returns the first in a sequence of values that is not the zero value.
    </p>
  </dd>
</dl><!-- cmp -->

<dl id="crypto/tls"><dt><a href="/pkg/crypto/tls/">crypto/tls</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/43922, CL 544155 -->
      <a href="/pkg/crypto/tls#ConnectionState.ExportKeyingMaterial"><code>ConnectionState.ExportKeyingMaterial</code></a> will now
      return an error unless TLS 1.3 is in use, or the <code>extended_master_secret</code> extension is supported by both the server and
      client. <code>crypto/tls</code> has supported this extension since Go 1.20. This can be disabled with the
      <code>tlsunsafeekm=1</code> GODEBUG setting.
    </p>

    <p><!-- https://go.dev/issue/62459, CL 541516 -->
      By default, the minimum version offered by <code>crypto/tls</code> servers is now TLS 1.2 if not specified with
      <a href="/pkg/crypto/tls#Config.MinimumVersion"><code>config.MinimumVersion</code></a>, matching the behavior of <code>crypto/tls</code>
      clients. This change can be reverted with the <code>tls10server=1</code> GODEBUG setting.
    </p>

    <p><!-- https://go.dev/issue/63413, CL 541517 -->
      By default, cipher suites without ECDHE support are no longer offered by either clients or servers during pre-TLS 1.3
      handshakes. This change can be reverted with the <code>tlsrsakex=1</code> GODEBUG setting.
    </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/57178 -->
      The new <a href="/pkg/crypto/x509#CertPool.AddCertWithConstraint"><code>CertPool.AddCertWithConstraint</code></a>
      method can be used to add customized constraints to root certificates to be applied during chain building.
    </p>

    <p><!-- https://go.dev/issue/58922, CL 519315-->
      On Android, root certificates will now be loaded from <code>/data/misc/keychain/certs-added</code> as well as <code>/system/etc/security/cacerts</code>.
    </p>

    <p><!-- https://go.dev/issue/60665, CL 520535 -->
      A new type, <a href="/pkg/crypto/x509#OID"><code>OID</code></a>, supports ASN.1 Object Identifiers with individual
      components larger than 31 bits. A new field which uses this type, <a href="/pkg/crypto/x509#Certificate.Policies"><code>Policies</code></a>,
      is added to the <code>Certificate</code> struct, and is now populated during parsing. Any OIDs which cannot be represented
      using a <a href="/pkg/encoding/asn1#ObjectIdentifier"><code>asn1.ObjectIdentifier</code></a> will appear in <code>Policies</code>,
      but not in the old <code>PolicyIdentifiers</code> field.

      When calling <a href="/pkg/crypto/x509#CreateCertificate"><code>CreateCertificate</code></a>, the <code>Policies</code> field is ignored, and
      policies are taken from the <code>PolicyIdentifiers</code> field. Using the <code>x509usepolicies=1</code> GODEBUG setting inverts this,
      populating certificate policies from the <code>Policies</code> field, and ignoring the <code>PolicyIdentifiers</code> field. We may change the
      default value of <code>x509usepolicies</code> in Go 1.23, making <code>Policies</code> the default field for marshaling.
    </p>
  </dd>
</dl><!-- crypto/x509 -->

<dl id="database/sql"><dt><a href="/pkg/database/sql/">database/sql</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/60370, CL 501700 -->
      The new <a href="/pkg/database/sql/#Null"><code>Null[T]</code></a> type
      provide a way to scan nullable columns for any column types.
    </p>
  </dd>
</dl><!-- database/sql -->

<dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/61974, CL 469395 -->
      Constant <code>R_MIPS_PC32</code> is defined for use with MIPS64 systems.
    </p>
  </dd>
  <dd>
    <p><!-- https://go.dev/issue/63725, CL 537615 -->
      Additional <code>R_LARCH_*</code> constants are defined for use with LoongArch systems.
    </p>
  </dd>
</dl><!-- debug/elf -->

<dl id="encoding"><dt><a href="/pkg/encoding/">encoding</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/53693, https://go.dev/cl/504884 -->
      The new methods <code>AppendEncode</code> and <code>AppendDecode</code> added to
      each of the <code>Encoding</code> types in the packages
      <a href="/pkg/encoding/base32"><code>encoding/base32</code></a>,
      <a href="/pkg/encoding/base64"><code>encoding/base64</code></a>, and
      <a href="/pkg/encoding/hex"><code>encoding/hex</code></a>
      simplify encoding and decoding from and to byte slices by taking care of byte slice buffer management.
    </p>

    <p><!-- https://go.dev/cl/505236 -->
      The methods
      <a href="/pkg/encoding/base32#Encoding.WithPadding"><code>base32.Encoding.WithPadding</code></a> and
      <a href="/pkg/encoding/base64#Encoding.WithPadding"><code>base64.Encoding.WithPadding</code></a>
      now panic if the <code>padding</code> argument is a negative value other than
      <code>NoPadding</code>.
    </p>
  </dd>
</dl><!-- encoding -->

<dl id="encoding/json"><dt><a href="/pkg/encoding/json/">encoding/json</a></dt>
  <dd>
    <p><!-- https://go.dev/cl/521675 -->
      Marshaling and encoding functionality now escapes
      <code>'\b'</code> and <code>'\f'</code> characters as
      <code>\b</code> and <code>\f</code> instead of
      <code>\u0008</code> and <code>\u000c</code>.
    </p>
  </dd>
</dl><!-- encoding/json -->

<dl id="go/ast"><dt><a href="/pkg/go/ast/">go/ast</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/52463, https://go/dev/cl/504915 -->
      The following declarations related to
      <a href='https://pkg.go.dev/go/ast#Object'>syntactic identifier resolution</a>
      are now <a href="https://go.dev/issue/52463">deprecated</a>:
      <code>Ident.Obj</code>,
      <code>Object</code>,
      <code>Scope</code>,
      <code>File.Scope</code>,
      <code>File.Unresolved</code>,
      <code>Importer</code>,
      <code>Package</code>,
      <code>NewPackage</code>.

      In general, identifiers cannot be accurately resolved without type information.
      Consider, for example, the identifier <code>K</code>
      in <code>T{K: ""}</code>: it could be the name of a local variable
      if T is a map type, or the name of a field if T is a struct type.

      New programs should use the <a href='/pkg/go/types'>go/types</a>
      package to resolve identifiers; see
      <a href='https://pkg.go.dev/go/types#Object'><code>Object</code></a>,
      <a href='https://pkg.go.dev/go/types#Info.Uses'><code>Info.Uses</code></a>, and
      <a href='https://pkg.go.dev/go/types#Info.Defs'><code>Info.Defs</code></a> for details.
    </p>

    <p><!-- https://go.dev/issue/60061 -->
      The new <a href='https://pkg.go.dev/go/ast#Unparen'><code>ast.Unparen</code></a>
      function removes any enclosing
      <a href='https://pkg.go.dev/go/ast#ParenExpr'>parentheses</a> from
      an <a href='https://pkg.go.dev/go/ast#Expr'>expression</a>.
    </p>
  </dd>
</dl><!-- go/ast -->

<dl id="go/types"><dt><a href="/pkg/go/types/">go/types</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/63223, CL 521956, CL 541737 -->
      The new <a href="/pkg/go/types#Alias"><code>Alias</code></a> type represents type aliases.
      Previously, type aliases were not represented explicitly, so a reference to a type alias was equivalent
      to spelling out the aliased type, and the name of the alias was lost.
      The new representation retains the intermediate <code>Alias</code>.
      This enables improved error reporting (the name of a type alias can be reported), and allows for better handling
      of cyclic type declarations involving type aliases.
      In a future release, <code>Alias</code> types will also carry <a href="https://go.dev/issue/46477">type parameter information</a>.
      The new function <a href="/pkg/go/types#Unalias"><code>Unalias</code></a> returns the actual type denoted by an
      <code>Alias</code> type (or any other <a href="/pkg/go/types#Type"><code>Type</code></a> for that matter).
    </p>
    <p>
      Because <code>Alias</code> types may break existing type switches that do not know to check for them,
      this functionality is controlled by a <a href="/doc/godebug"><code>GODEBUG</code></a> field named <code>gotypesalias</code>.
      With <code>gotypesalias=0</code>, everything behaves as before, and <code>Alias</code> types are never created.
      With <code>gotypesalias=1</code>, <code>Alias</code> types are created and clients must expect them.
      The default is <code>gotypesalias=0</code>.
      In a future release, the default will be changed to <code>gotypesalias=1</code>.
      <em>Clients of <a href="/pkg/go/types"><code>go/types</code></a> are urged to adjust their code as soon as possible
      to work with <code>gotypesalias=1</code> to eliminate problems early.</em>
    </p>

    <p><!-- https://go.dev/issue/62605, CL 540056 -->
      The <a href="/pkg/go/types#Info"><code>Info</code></a> struct now exports the
      <a href="/pkg/go/types#Info.FileVersions"><code>FileVersions</code></a> map
      which provides per-file Go version information.
    </p>

    <p><!-- https://go.dev/issue/62037, CL 541575 -->
      The new helper method <a href="/pkg/go/types#Info.PkgNameOf"><code>PkgNameOf</code></a> returns the local package name
      for the given import declaration.
    </p>

    <p><!-- https://go.dev/issue/61035, multiple CLs, see issue for details -->
      The implementation of <a href="/pkg/go/types#SizesFor"><code>SizesFor</code></a> has been adjusted to compute
      the same type sizes as the compiler when the compiler argument for <code>SizesFor</code> is <code>"gc"</code>.
      The default <a href="/pkg/go/types#Sizes"><code>Sizes</code></a> implementation used by the type checker is now
      <code>types.SizesFor("gc", "amd64")</code>.
    </p>

    <p><!-- https://go.dev/issue/64295, CL 544035 -->
      The start position (<a href="/pkg/go/types#Scope.Pos"><code>Pos</code></a>)
      of the lexical environment block (<a href="/pkg/go/types#Scope"><code>Scope</code></a>)
      that represents a function body has changed:
      it used to start at the opening curly brace of the function body,
      but now starts at the function's <code>func</code> token.
    </p>
  </dd>
</dl>

<dl id="go/version"><dt><a href="/pkg/go/version/">go/version</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/62039, https://go.dev/cl/538895 -->
      The new <a href="/pkg/go/version/"><code>go/version</code></a> package implements functions
      for validating and comparing Go version strings.
    </p>
  </dd>
</dl><!-- go/version -->

<dl id="html/template"><dt><a href="/pkg/html/template/">html/template</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/61619, CL 507995 -->
      Javascript template literals may now contain Go template actions, and parsing a template containing one will
      no longer return <code>ErrJSTemplate</code>. Similarly the GODEBUG setting <code>jstmpllitinterp</code> no
      longer has any effect.
    </p>
  </dd>
</dl><!-- html/template -->

<dl id="io"><dt><a href="/pkg/io/">io</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/61870, CL 526855 -->
      The new <a href="/pkg/io#SectionReader.Outer"><code>SectionReader.Outer</code></a> method returns the <a href="/pkg/io#ReaderAt"><code>ReaderAt</code></a>, offset, and size passed to <a href="/pkg/io#NewSectionReader"><code>NewSectionReader</code></a>.
    </p>
  </dd>
</dl><!-- io -->

<dl id="log/slog"><dt><a href="/pkg/log/slog/">log/slog</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/62418 -->
      The new <a href="/pkg/log/slog#SetLogLoggerLevel"><code>SetLogLoggerLevel</code></a> function
      controls the level for the bridge between the `slog` and `log` packages. It sets the minimum level
      for calls to the top-level `slog` logging functions, and it sets the level for calls to `log.Logger`
      that go through `slog`.
    </p>
  </dd>
</dl>

<dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/50489, CL 539299 -->
      The new method <a href="/pkg/math/big#Rat.FloatPrec"><code>Rat.FloatPrec</code></a> computes the number of fractional decimal digits
      required to represent a rational number accurately as a floating-point number, and whether accurate decimal representation
      is possible in the first place.
    </p>
  </dd>
</dl><!-- math/big -->

<dl id="net"><dt><a href="/pkg/net/">net</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/58808 -->
      When <a href="/pkg/io#Copy"><code>io.Copy</code></a> copies
      from a <code>TCPConn</code> to a <code>UnixConn</code>,
      it will now use Linux's <code>splice(2)</code> system call if possible,
      using the new method <a href="/pkg/net#TCPConn.WriteTo"><code>TCPConn.WriteTo</code></a>.
    </p>

    <p><!-- CL 467335 -->
      The Go DNS Resolver, used when building with "-tags=netgo",
      now searches for a matching name in the Windows hosts file,
      located at <code>%SystemRoot%\System32\drivers\etc\hosts</code>,
      before making a DNS query.
    </p>
  </dd>
</dl><!-- net -->

<dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/51971 -->
      The new functions
      <a href="/pkg/net/http#ServeFileFS"><code>ServeFileFS</code></a>,
      <a href="/pkg/net/http#FileServerFS"><code>FileServerFS</code></a>, and
      <a href="/pkg/net/http#NewFileTransportFS"><code>NewFileTransportFS</code></a>
      are versions of the existing
      <code>ServeFile</code>, <code>FileServer</code>, and <code>NewFileTransport</code>,
      operating on an <code>fs.FS</code>.
    </p>

    <p><!-- https://go.dev/issue/61679 -->
      The HTTP server and client now reject requests and responses containing
      an invalid empty <code>Content-Length</code> header.
      The previous behavior may be restored by setting
      <a href="/doc/godebug"><code>GODEBUG</code></a> field <code>httplaxcontentlength=1</code>.
    </p>

    <p><!-- https://go.dev/issue/61410, CL 528355 -->
      The new method
      <a href="/pkg/net/http#Request.PathValue"><code>Request.PathValue</code></a>
      returns path wildcard values from a request
      and the new method
      <a href="/pkg/net/http#Request.SetPathValue"><code>Request.SetPathValue</code></a>
      sets path wildcard values on a request.
    </p>
  </dd>
</dl><!-- net/http -->

<!-- <dl id="net/http/cgi"><dt><a href="/pkg/net/http/cgi/">net/http/cgi</a></dt> -->
<!--   <dd> -->
<!--     <p><\!-- CL 539615 -\-> -->
<!--       TODO: <a href="https://go.dev/cl/539615">https://go.dev/cl/539615</a>: net/http/cgi: the PATH_INFO should be empty or start with a slash -->
<!--     </p> -->
<!--   </dd> -->
<!-- </dl><\!-- net/http/cgi -\-> -->

<!-- <dl id="net/netip"><dt><a href="/pkg/net/netip/">net/netip</a></dt> -->
<!--   <dd> -->
<!--     <p><\!-- https://go.dev/issue/61642 -\-> -->
<!--       TODO: <a href="https://go.dev/issue/61642">https://go.dev/issue/61642</a>: add Prefix.Compare and AddrPort.Compare -->
<!--     </p> -->

<!--     <p><\!-- CL 524616 -\-> -->
<!--       TODO: <a href="https://go.dev/cl/524616">https://go.dev/cl/524616</a>: net/netip: add AddrPort.Compare and Prefix.Compare; modified api/next/61642.txt -->
<!--     </p> -->
<!--   </dd> -->
<!-- </dl><\!-- net/netip -\-> -->

<dl id="os"><dt><a href="/pkg/os/">os</a></dt>
  <dd>
    <p><!-- CL 516555 -->
      On Windows, the <a href="/pkg/os#Stat"><code>Stat</code></a> function now follows all reparse points
      that link to another named entity in the system.
      It was previously only following <code>IO_REPARSE_TAG_SYMLINK</code> and
      <code>IO_REPARSE_TAG_MOUNT_POINT</code> reparse points.
    </p>

    <p><!-- CL 541015 -->
      On Windows, passing <a href="/pkg/os#O_SYNC"><code>O_SYNC</code></a> to <a href="/pkg/os#OpenFile"><code>OpenFile</code></a> now causes write operations to go directly to disk, equivalent to <code>O_SYNC</code> on Unix platforms.
    </p>

    <p><!-- CL 452995 -->
      On Windows, the <a href="/pkg/os#ReadDir"><code>ReadDir</code></a>,
      <a href="/pkg/os#File.ReadDir"><code>File.ReadDir</code></a>,
      <a href="/pkg/os#File.Readdir"><code>File.Readdir</code></a>,
      and <a href="/pkg/os#File.Readdirnames"><code>File.Readdirnames</code></a> functions
      now read directory entries in batches to reduce the number of system calls,
      improving performance up to 30%.
    </p>

    <p><!-- https://go.dev/issue/58808 -->
      When <a href="/pkg/io#Copy"><code>io.Copy</code></a> copies
      from a <code>File</code> to a <code>net.UnixConn</code>,
      it will now use Linux's <code>sendfile(2)</code> system call if possible,
      using the new method <a href="/pkg/os#File.WriteTo"><code>File.WriteTo</code></a>.
    </p>
  </dd>
</dl><!-- os -->

<dl id="os/exec"><dt><a href="/pkg/os/exec/">os/exec</a></dt>
  <dd>
    <p><!-- CL 528037 -->
      On Windows, <a href="/pkg/os/exec#LookPath"><code>LookPath</code></a> now
      ignores empty entries in <code>%PATH%</code>, and returns
      <code>ErrNotFound</code> (instead of <code>ErrNotExist</code>) if
      no executable file extension is found to resolve an otherwise-unambiguous
      name.
    </p>

    <p><!-- CL 528038, CL 527820 -->
      On Windows, <a href="/pkg/os/exec#Command"><code>Command</code></a> and
      <a href="/pkg/os/exec#Cmd.Start"><code>Cmd.Start</code></a> no
      longer call <code>LookPath</code> if the path to the executable is already
      absolute and has an executable file extension. In addition,
      <code>Cmd.Start</code> no longer writes the resolved extension back to
      the <a href="/pkg/os/exec#Cmd.Path"><code>Path</code></a> field,
      so it is now safe to call the <code>String</code> method concurrently
      with a call to <code>Start</code>.
    </p>
  </dd>
</dl><!-- os/exec -->

<dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/61827, CL 517777 -->
      The <a href="/pkg/reflect/#Value.IsZero"><code>Value.IsZero</code></a>
      method will now return true for a floating-point or complex
      negative zero, and will return true for a struct value if a
      blank field (a field named <code>_</code>) somehow has a
      non-zero value.
      These changes make <code>IsZero</code> consistent with comparing
      a value to zero using the language <code>==</code> operator.
    </p>

    <p><!-- https://go.dev/issue/59599, CL 511035 -->
      The <a href="/pkg/reflect/#PtrTo"><code>PtrTo</code></a> function is deprecated,
      in favor of <a href="/pkg/reflect/#PointerTo"><code>PointerTo</code></a>.
    </p>

    <p><!-- https://go.dev/issue/60088, CL 513478 -->
      The new function <a href="/pkg/reflect/#TypeFor"><code>TypeFor</code></a>
      returns the <a href="/pkg/reflect/#Type"><code>Type</code></a> that represents
      the type argument T.
      Previously, to get the <code>reflect.Type</code> value for a type, one had to use
      <code>reflect.TypeOf((*T)(nil)).Elem()</code>.
      This may now be written as <code>reflect.TypeFor[T]()</code>.
    </p>
  </dd>
</dl><!-- reflect -->

<dl id="runtime/metrics"><dt><a href="/pkg/runtime/metrics/">runtime/metrics</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/63340 -->
      Four new histogram metrics
      <code>/sched/pauses/stopping/gc:seconds</code>,
      <code>/sched/pauses/stopping/other:seconds</code>,
      <code>/sched/pauses/total/gc:seconds</code>, and
      <code>/sched/pauses/total/other:seconds</code> provide additional details
      about stop-the-world pauses.
      The "stopping" metrics report the time taken from deciding to stop the
      world until all goroutines are stopped.
      The "total" metrics report the time taken from deciding to stop the world
      until it is started again.
    </p>

    <p><!-- https://go.dev/issue/63340 -->
      The <code>/gc/pauses:seconds</code> metric is deprecated, as it is
      equivalent to the new <code>/sched/pauses/total/gc:seconds</code> metric.
    </p>

    <p><!-- https://go.dev/issue/57071 -->
      <code>/sync/mutex/wait/total:seconds</code> now includes contention on
      runtime-internal locks in addition to
      <a href="/pkg/sync#Mutex"><code>sync.Mutex</code></a> and
      <a href="/pkg/sync#RWMutex"><code>sync.RWMutex</code></a>.
    </p>
  </dd>
</dl><!-- runtime/metrics -->

<dl id="runtime/pprof"><dt><a href="/pkg/runtime/pprof/">runtime/pprof</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/61015 -->
      Mutex profiles now scale contention by the number of goroutines blocked on the mutex.
      This provides a more accurate representation of the degree to which a mutex is a bottleneck in
      a Go program.
      For instance, if 100 goroutines are blocked on a mutex for 10 milliseconds, a mutex profile will
      now record 1 second of delay instead of 10 milliseconds of delay.
    </p>

    <p><!-- https://go.dev/issue/57071 -->
      Mutex profiles also now include contention on runtime-internal locks in addition to
      <a href="/pkg/sync#Mutex"><code>sync.Mutex</code></a> and
      <a href="/pkg/sync#RWMutex"><code>sync.RWMutex</code></a>.
      Contention on runtime-internal locks is always reported at <code>runtime._LostContendedRuntimeLock</code>.
      A future release will add complete stack traces in these cases.
    </p>

    <p><!-- https://go.dev/issue/50891 -->
      CPU profiles on Darwin platforms now contain the process's memory map, enabling the disassembly
      view in the pprof tool.
    </p>
  </dd>
</dl><!-- runtime/pprof -->

<dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/60773 -->
      The execution tracer has been completely overhauled in this release, resolving several long-standing
      issues and paving the way for new use-cases for execution traces.
    </p>
    <p>
      Execution traces now use the operating system's clock on most platforms (Windows excluded) so
      it is possible to correlate them with traces produced by lower-level components.
      Execution traces no longer depend on the reliability of the platform's clock to produce a correct trace.
      Execution traces are now partitioned regularly on-the-fly and as a result may be processed in a
      streamable way.
      Execution traces now contain complete durations for all system calls.
      Execution traces now contain information about the operating system threads that goroutines executed on.
      The latency impact of starting and stopping execution traces has been dramatically reduced.
      Execution traces may now begin or end during the garbage collection mark phase.
    </p>
    <p>
      To allow Go developers to take advantage of these improvements, an experimental
      trace reading package is available at <a href="/pkg/golang.org/x/exp/trace">golang.org/x/exp/trace</a>.
      Note that this package only works on traces produced by programs built with Go 1.22 at the moment.
      Please try out the package and provide feedback on
      <a href="https://github.com/golang/go/issues/62627">the corresponding proposal issue</a>.
    </p>
    <p>
      If you experience any issues with the new execution tracer implementation, you may switch back to the
      old implementation by building your Go program with <code>GOEXPERIMENT=noexectracer2</code>.
      If you do, please file an issue, otherwise this option will be removed in a future release.
    </p>
  </dd>
</dl><!-- runtime/trace -->

<dl id="slices"><dt><a href="/pkg/slices/">slices</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/56353 --><!-- CL 504882 -->
      The new function <code>Concat</code> concatenates multiple slices.
    </p>

    <p><!-- https://go.dev/issue/63393 --><!-- CL 543335 -->
      Functions that shrink the size of a slice (<code>Delete</code>, <code>DeleteFunc</code>, <code>Compact</code>, <code>CompactFunc</code>, and <code>Replace</code>) now zero the elements between the new length and the old length.
    </p>

    <p><!-- https://go.dev/issue/63913 --><!-- CL 540155 -->
      <code>Insert</code> now always panics if the argument <code>i</code> is out of range. Previously it did not panic in this situation if there were no elements to be inserted.
    </p>
  </dd>
</dl><!-- slices -->

<dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/60797 -->
      The <code>syscall</code> package has been <a href="https://golang.org/s/go1.4-syscall">frozen</a> since Go 1.4 and was marked as deprecated in Go 1.11, causing many editors to warn about any use of the package.
      However, some non-deprecated functionality requires use of the <code>syscall</code> package, such as the <a href="/pkg/os/exec#Cmd"><code>os/exec.Cmd.SysProcAttr</code></a> field.
      To avoid unnecessary complaints on such code, the <code>syscall</code> package is no longer marked as deprecated.
      The package remains frozen to most new functionality, and new code remains encouraged to use <a href="/pkg/golang.org/x/sys/unix"><code>golang.org/x/sys/unix</code></a> or <a href="/pkg/golang.org/x/sys/windows"><code>golang.org/x/sys/windows</code></a> where possible.
    </p>

    <p><!-- https://go.dev/issue/51246, CL 520266 -->
      On Linux, the new <a href="/pkg/syscall#SysProcAttr"><code>SysProcAttr.PidFD</code></a> field allows obtaining a PID FD when starting a child process via <a href="/pkg/syscall#StartProcess"><code>StartProcess</code></a> or <a href="/pkg/os/exec"><code>os/exec</code></a>.
    </p>

    <p><!-- CL 541015 -->
      On Windows, passing <a href="/pkg/syscall#O_SYNC"><code>O_SYNC</code></a> to <a href="/pkg/syscall#Open"><code>Open</code></a> now causes write operations to go directly to disk, equivalent to <code>O_SYNC</code> on Unix platforms.
    </p>
  </dd>
</dl><!-- syscall -->

<dl id="testing/slogtest"><dt><a href="/pkg/testing/slogtest/">testing/slogtest</a></dt>
  <dd>
    <p><!-- https://go.dev/issue/61758 -->
      The new <a href="/pkg/testing/slogtest#Run"><code>Run</code></a> function uses sub-tests to run test cases,
      providing finer-grained control.
    </p>
  </dd>
</dl><!-- testing/slogtest -->

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

<h3 id="darwin">Darwin</h3>
<p><!-- CL 461697 -->
  On macOS on 64-bit x86 architecture (the <code>darwin/amd64</code> port),
  the Go toolchain now generates position-independent executables (PIE) by default.
  Non-PIE binaries can be generated by specifying the <code>-buildmode=exe</code>
  build flag.
  On 64-bit ARM-based macOS (the <code>darwin/arm64</code> port),
  the Go toolchain already generates PIE by default.
</p>
<p><!-- go.dev/issue/64207 -->
  Go 1.22 is the last release that will run on macOS 10.15 Catalina. Go 1.23 will require macOS 11 Big Sur or later.
</p>

<h3 id="arm">Arm</h3>
<p><!-- CL 514907 -->
  The <code>GOARM</code> environment variable now allows you to select whether to use software or hardware floating point.
  Previously, valid <code>GOARM</code> values were <code>5</code>, <code>6</code>, or <code>7</code>. Now those same values can
  be optionally followed by <code>,softfloat</code> or <code>,hardfloat</code> to select the floating-point implementation.
</p>
<p>
  This new option defaults to <code>softfloat</code> for version <code>5</code> and <code>hardfloat</code> for versions
  <code>6</code> and <code>7</code>.
</p>

<h3 id="loong64">Loong64</h3>
<p><!-- CL 481315 -->
  The <code>loong64</code> port now supports passing function arguments and results using registers.
</p>
<p><!-- CL 481315,537615,480878 -->
  The <code>linux/loong64</code> port now supports the address sanitizer, memory sanitizer, new-style linker relocations, and the <code>plugin</code> build mode.
</p>

<h3 id="openbsd">OpenBSD</h3>
<p><!-- CL 517935 -->
  Go 1.22 adds an experimental port to OpenBSD on big-endian 64-bit PowerPC
  (<code>openbsd/ppc64</code>).
</p>