go/doc/go1.17.html

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

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

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

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

<p><!-- CL 216424 -->
  TODO: <a href="https://golang.org/cl/216424">https://golang.org/cl/216424</a>: allow conversion from slice to array ptr
</p>

<p><!-- CL 312212 -->
  TODO: <a href="https://golang.org/cl/312212">https://golang.org/cl/312212</a>: add unsafe.Add and unsafe.Slice
</p>

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

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

<p><!-- golang.org/issue/23011 -->
  As <a href="go1.16#darwin">announced</a> in the Go 1.16 release
  notes, Go 1.17 requires macOS 10.13 High Sierra or later; support
  for previous versions has been discontinued.
</p>

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

<p><!-- golang.org/issue/36439 -->
  Go 1.17 adds support of 64-bit ARM architecture on Windows (the
  <code>windows/arm64</code> port). This port supports cgo.
</p>

<p>
  TODO: complete the Ports section
</p>

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

<p>
  TODO: complete the Tools section
</p>

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

<h4 id="lazy-loading">Lazy module loading</h4>

<p><!-- golang.org/issue/36460 -->
  If a module specifies <code>go</code> <code>1.17</code> or higher in its
  <code>go.mod</code> file, its transitive requirements are now loaded lazily,
  avoiding the need to download or read <code>go.mod</code> files for
  otherwise-irrelevant dependencies. To support lazy loading, in Go 1.17 modules
  the <code>go</code> command maintains <em>explicit</em> requirements in
  the <code>go.mod</code> file for every dependency that provides any package
  transitively imported by any package or test within the module.
  See <a href="https://golang.org/design/36460-lazy-module-loading">the design
  document</a> for more detail.
  <!-- TODO(bcmills): replace the design-doc link with proper documentation. -->
</p>

<p><!-- golang.org/issue/45094 --> To facilitate the upgrade to lazy loading,
  the <code>go</code> <code>mod</code> <code>tidy</code> subcommand now supports
  a <code>-go</code> flag to set or change the <code>go</code> version in
  the <code>go.mod</code> file. To enable lazy loading for an existing module
  without changing the selected versions of its dependencies, run:
</p>

<pre>
  go mod tidy -go=1.17
</pre>

<h4 id="module-deprecation-comments">Module deprecation comments</h4>

<p><!-- golang.org/issue/40357 -->
  Module authors may deprecate a module by adding a
  <a href="/ref/mod#go-mod-file-module-deprecation"><code>// Deprecated:</code>
  comment</a> to <code>go.mod</code>, then tagging a new version.
  <code>go</code> <code>get</code> now prints a warning if a module needed to
  build packages named on the command line is deprecated. <code>go</code>
  <code>list</code> <code>-m</code> <code>-u</code> prints deprecations for all
  dependencies (use <code>-f</code> or <code>-json</code> to show the full
  message). The <code>go</code> command considers different major versions to
  be distinct modules, so this mechanism may be used, for example, to provide
  users with migration instructions for a new major version.
</p>

<h4 id="go-get"><code>go</code> <code>get</code></h4>

<p><!-- golang.org/issue/37519 -->
  The <code>go</code> <code>get</code> <code>-insecure</code> flag is
  deprecated and has been removed. To permit the use of insecure schemes
  when fetching dependencies, please use the <code>GOINSECURE</code>
  environment variable. The <code>-insecure</code> flag also bypassed module
  sum validation, use <code>GOPRIVATE</code> or <code>GONOSUMDB</code> if
  you need that functionality. See <code>go</code> <code>help</code>
  <code>environment</code> for details.
</p>

<h4 id="missing-go-directive"><code>go.mod</code> files missing <code>go</code> directives</h4>

<p><!-- golang.org/issue/44976 -->
  If the main module's <code>go.mod</code> file does not contain
  a <a href="/doc/modules/gomod-ref#go"><code>go</code> directive</a> and
  the <code>go</code> command cannot update the <code>go.mod</code> file, the
  <code>go</code> command now assumes <code>go 1.11</code> instead of the
  current release. (<code>go</code> <code>mod</code> <code>init</code> has added
  <code>go</code> directives automatically <a href="/doc/go1.12#modules">since
  Go 1.12</a>.)
</p>

<p><!-- golang.org/issue/44976 -->
  If a module dependency lacks an explicit <code>go.mod</code> file, or
  its <code>go.mod</code> file does not contain
  a <a href="/doc/modules/gomod-ref#go"><code>go</code> directive</a>,
  the <code>go</code> command now assumes <code>go 1.16</code> for that
  dependency instead of the current release. (Dependencies developed in GOPATH
  mode may lack a <code>go.mod</code> file, and
  the <code>vendor/modules.txt</code> has to date never recorded
  the <code>go</code> versions indicated by dependencies' <code>go.mod</code>
  files.)
</p>

<h4 id="vendor"><code>vendor</code> contents</h4>

<p><!-- golang.org/issue/36876 -->
  If the main module specifies <code>go</code> <code>1.17</code> or higher,
  <code>go</code> <code>mod</code> <code>vendor</code> now annotates
  <code>vendor/modules.txt</code> with the <code>go</code> version indicated by
  each vendored module in its own <code>go.mod</code> file. The annotated
  version is used when building the module's packages from vendored source code.
</p>

<p><!-- golang.org/issue/42970 -->
  If the main module specifies <code>go</code> <code>1.17</code> or higher,
  <code>go</code> <code>mod</code> <code>vendor</code> now omits <code>go.mod</code>
  and <code>go.sum</code> files for vendored dependencies, which can otherwise
  interfere with the ability of the <code>go</code> command to identify the correct
  module root when invoked within the <code>vendor</code> tree.
</p>

<h4 id="password-prompts">Password prompts</h4>

<p><!-- golang.org/issue/44904 -->
  The <code>go</code> command by default now suppresses SSH password prompts and
  Git Credential Manager prompts when fetching Git repositories using SSH, as it
  already did previously for other Git password prompts. Users authenticating to
  private Git repos with password-protected SSH may configure
  an <code>ssh-agent</code> to enable the <code>go</code> command to use
  password-protected SSH keys.
</p>

<p><!-- CL 249759 -->
  TODO: <a href="https://golang.org/cl/249759">https://golang.org/cl/249759</a>: cmd/cover: replace code using optimized golang.org/x/tools/cover
</p>

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

<p><!-- CL 299532 -->
  TODO: <a href="https://golang.org/cl/299532">https://golang.org/cl/299532</a>: cmd/vet: bring in sigchanyzer to report unbuffered channels to signal.Notify
</p>

<p>
  TODO: complete the Vet section
</p>

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

<p><!-- CL 304470 -->
  TODO: <a href="https://golang.org/cl/304470">https://golang.org/cl/304470</a>: cmd/compile, runtime: add metadata for argument printing in traceback
</p>

<p>
  TODO: complete the Runtime section
</p>

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

<p>
  TODO: complete the Compiler section, or delete if not needed
</p>

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

<p>
  TODO: complete the Linker section, or delete if not needed
</p>

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

<p>
  TODO: complete the Core library section
</p>

<h3 id="crypto/tls"><a href="/pkg/crypto/tls">crypto/tls</a></h3>

<p><!-- CL 295370 -->
  <a href="/pkg/crypto/tls#Conn.HandshakeContext">(*Conn).HandshakeContext</a> was added to
  allow the user to control cancellation of an in-progress TLS Handshake.
  The context provided is propagated into the
  <a href="/pkg/crypto/tls#ClientHelloInfo">ClientHelloInfo</a>
  and <a href="/pkg/crypto/tls#CertificateRequestInfo">CertificateRequestInfo</a>
  structs and accessible through the new
  <a href="/pkg/crypto/tls#ClientHelloInfo.Context">(*ClientHelloInfo).Context</a>
  and
  <a href="/pkg/crypto/tls#CertificateRequestInfo.Context">
      (*CertificateRequestInfo).Context
  </a> methods respectively. Canceling the context after the handshake has finished
  has no effect.
</p>

<p><!-- CL 289209 -->
  When <a href="/pkg/crypto/tls#Config">Config.NextProtos</a> is set, servers now
  enforce that there is an overlap between the configured protocols and the protocols
  advertised by the client, if any. If there is no overlap the connection is closed
  with the <code>no_application_protocol</code> alert, as required by RFC 7301.
</p>

<h3 id="runtime/cgo"><a href="/pkg/runtime/cgo">Cgo</a></h3>

<p>
  The <a href="/pkg/runtime/cgo">runtime/cgo</a> package now provides a
  new facility that allows to turn any Go values to a safe representation
  that can be used to pass values between C and Go safely. See
  <a href="/pkg/runtime/cgo#Handle">runtime/cgo.Handle</a> for more information.
</p>

<h3 id="minor_library_changes">Minor changes to the library</h3>

<p>
  As always, there are various minor changes and updates to the library,
  made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
  in mind.
</p>

<dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>
  <dd>
    <p><!-- CL 312310 -->
      TODO: <a href="https://golang.org/cl/312310">https://golang.org/cl/312310</a>: add File.OpenRaw, Writer.CreateRaw, Writer.Copy
    </p>
  </dd>
</dl><!-- archive/zip -->

<dl id="bufio"><dt><a href="/pkg/bufio/">bufio</a></dt>
  <dd>
    <p><!-- CL 280492 -->
      The <a href="/pkg/bufio/#Writer.WriteRune"><code>Writer.WriteRune</code></a> method
      now writes the replacement character U+FFFD for negative rune values,
      as it does for other invalid runes.
    </p>
  </dd>
</dl><!-- bufio -->

<dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
  <dd>
    <p><!-- CL 280492 -->
      The <a href="/pkg/bytes/#Buffer.WriteRune"><code>Buffer.WriteRune</code></a> method
      now writes the replacement character U+FFFD for negative rune values,
      as it does for other invalid runes.
    </p>
  </dd>
</dl><!-- bytes -->

<dl id="compress/lzw"><dt><a href="/pkg/compress/lzw/">compress/lzw</a></dt>
  <dd>
    <p><!-- CL 273667 -->
      The new
      <a href="/pkg/compress/lzw/#Reader.Reset"><code>Reader.Reset</code></a>
      and
      <a href="/pkg/compress/lzw/#Writer.Reset"><code>Writer.Reset</code></a>
      methods allow reuse of a <code>Reader</code> or <code>Writer</code>.
    </p>
  </dd>
</dl><!-- compress/lzw -->

<dl id="crypto/rsa"><dt><a href="/pkg/crypto/rsa/">crypto/rsa</a></dt>
  <dd>
    <p><!-- CL 302230 -->
      TODO: <a href="https://golang.org/cl/302230">https://golang.org/cl/302230</a>: fix salt length calculation with PSSSaltLengthAuto
    </p>
  </dd>
</dl><!-- crypto/rsa -->

<dl id="database/sql"><dt><a href="/pkg/database/sql/">database/sql</a></dt>
  <dd>
    <p><!-- CL 258360 -->
      TODO: <a href="https://golang.org/cl/258360">https://golang.org/cl/258360</a>: close driver.Connector if it implements io.Closer
    </p>

    <p><!-- CL 311572 -->
      TODO: <a href="https://golang.org/cl/311572">https://golang.org/cl/311572</a>: add NullInt16 and NullByte
    </p>
  </dd>
</dl><!-- database/sql -->

<dl id="encoding/binary"><dt><a href="/pkg/encoding/binary/">encoding/binary</a></dt>
  <dd>
    <p><!-- CL 299531 -->
      <code>binary.Uvarint</code> will stop reading after <code>10 bytes</code> to avoid
      wasted computations. If more than <code>10 bytes</code> are needed, the byte count returned is <code>-11</code>.
      <br />
      Previous Go versions could return larger negative counts when reading incorrectly encoded varints.
    </p>
  </dd>
</dl><!-- encoding/binary -->

<dl id="flag"><dt><a href="/pkg/flag/">flag</a></dt>
  <dd>
    <p><!-- CL 271788 -->
      TODO: <a href="https://golang.org/cl/271788">https://golang.org/cl/271788</a>: panic if flag name begins with - or contains =
    </p>
  </dd>
</dl><!-- flag -->

<dl id="io/fs"><dt><a href="/pkg/io/fs/">io/fs</a></dt>
  <dd>
    <p><!-- CL 293649 -->
      TODO: <a href="https://golang.org/cl/293649">https://golang.org/cl/293649</a>: implement FileInfoToDirEntry
    </p>
  </dd>
</dl><!-- io/fs -->

<dl id="math"><dt><a href="/pkg/math/">math</a></dt>
  <dd>
    <p><!-- CL 247058 -->
      The math package now defines three more constants: <code>MaxUint</code>, <code>MaxInt</code> and <code>MinInt</code>.
      For 32-bit systems their values are <code>2^32 - 1</code>, <code>2^31 - 1</code> and <code>-2^31</code>, respectively.
      For 64-bit systems their values are <code>2^64 - 1</code>, <code>2^63 - 1</code> and <code>-2^63</code>, respectively.
    </p>
  </dd>
</dl><!-- math -->

<dl id="mime"><dt><a href="/pkg/mime/">mime</a></dt>
  <dd>
    <p><!-- CL 305230 -->
      TODO: <a href="https://golang.org/cl/305230">https://golang.org/cl/305230</a>: support reading shared mime-info database on unix systems
    </p>
  </dd>
</dl><!-- mime -->

<dl id="net"><dt><a href="/pkg/net/">net</a></dt>
  <dd>
    <p><!-- CL 272668 -->
      TODO: <a href="https://golang.org/cl/272668">https://golang.org/cl/272668</a>: add IP.IsPrivate
    </p>

    <p><!-- CL 301709 -->
      TODO: <a href="https://golang.org/cl/301709">https://golang.org/cl/301709</a>: make go resolver aware of network parameter
    </p>

    <p><!-- CL 307030 -->
      TODO: <a href="https://golang.org/cl/307030">https://golang.org/cl/307030</a>: make ErrClosed and ParseError implement net.Error
    </p>
  </dd>
</dl><!-- net -->

<dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
  <dd>
    <p><!-- CL 295370 -->
      The <a href="/pkg/net/http/"><code>net/http</code></a> package now uses the new
      <a href="/pkg/crypto/tls#Conn.HandshakeContext"><code>(*tls.Conn).HandshakeContext</code></a>
      with the <a href="/pkg/net/http/#Request"><code>Request</code></a> context
      when performing TLS handshakes in the client or server.
    </p>

    <p><!-- CL 235437 -->
      TODO: <a href="https://golang.org/cl/235437">https://golang.org/cl/235437</a>: add to deadlines only when positive
    </p>

    <p><!-- CL 308952 -->
      TODO: <a href="https://golang.org/cl/308952">https://golang.org/cl/308952</a>: make ReadRequest return an error when requests have multiple Host headers
    </p>
  </dd>
</dl><!-- net/http -->

<dl id="net/http/httptest"><dt><a href="/pkg/net/http/httptest/">net/http/httptest</a></dt>
  <dd>
    <p><!-- CL 308950 -->
      TODO: <a href="https://golang.org/cl/308950">https://golang.org/cl/308950</a>: panic on non-3 digit (XXX) status code in Recorder.WriteHeader
    </p>
  </dd>
</dl><!-- net/http/httptest -->

<dl id="net/url"><dt><a href="/pkg/net/url/">net/url</a></dt>
  <dd>
    <p><!-- CL 314850 -->
      TODO: <a href="https://golang.org/cl/314850">https://golang.org/cl/314850</a>: add Values.Has
    </p>
  </dd>
</dl><!-- net/url -->

<dl id="os"><dt><a href="/pkg/os/">os</a></dt>
  <dd>
    <p><!-- CL 268020 -->
      TODO: <a href="https://golang.org/cl/268020">https://golang.org/cl/268020</a>: avoid allocation in File.WriteString
    </p>
  </dd>
</dl><!-- os -->

<dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
  <dd>
    <p><!-- CL 266197 -->
      The new
      <a href="/pkg/reflect/#StructField.IsExported"><code>StructField.IsExported</code></a>
      and
      <a href="/pkg/reflect/#Method.IsExported"><code>Method.IsExported</code></a>
      methods report whether a struct field or type method is exported.
      They provide a more readable alternative to checking whether <code>PkgPath</code>
      is empty.
    </p>

    <p><!-- CL 281233 -->
      TODO: <a href="https://golang.org/cl/281233">https://golang.org/cl/281233</a>: add VisibleFields function
    </p>

    <p><!-- CL 284136 -->
      TODO: <a href="https://golang.org/cl/284136">https://golang.org/cl/284136</a>: panic if ArrayOf is called with negative length
    </p>
  </dd>
</dl><!-- reflect -->

<dl id="strconv"><dt><a href="/pkg/strconv/">strconv</a></dt>
  <dd>
    <p><!-- CL 170079 -->
      TODO: <a href="https://golang.org/cl/170079">https://golang.org/cl/170079</a>: implement Ryū-like algorithm for fixed precision ftoa
    </p>

    <p><!-- CL 170080 -->
      TODO: <a href="https://golang.org/cl/170080">https://golang.org/cl/170080</a>: Implement Ryū algorithm for ftoa shortest mode
    </p>

    <p><!-- CL 314775 -->
      The new <a href="/pkg/strconv/#QuotedPrefix"><code>QuotedPrefix</code></a> function
      returns the quoted string (as understood by
      <a href="/pkg/strconv/#Unquote"><code>Unquote</code></a>)
      at the start of input.
    </p>
  </dd>
</dl><!-- strconv -->

<dl id="strings"><dt><a href="/pkg/strings/">strings</a></dt>
  <dd>
    <p><!-- CL 280492 -->
      The <a href="/pkg/strings/#Builder.WriteRune"><code>Builder.WriteRune</code></a> method
      now writes the replacement character U+FFFD for negative rune values,
      as it does for other invalid runes.
    </p>
  </dd>
</dl><!-- strings -->

<dl id="sync/atomic"><dt><a href="/pkg/sync/atomic/">sync/atomic</a></dt>
  <dd>
    <p><!-- CL 241678 -->
      TODO: <a href="https://golang.org/cl/241678">https://golang.org/cl/241678</a>: add (*Value).Swap and (*Value).CompareAndSwap
    </p>
  </dd>
</dl><!-- sync/atomic -->

<dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
  <dd>
    <p><!-- CL 295371 -->
      TODO: <a href="https://golang.org/cl/295371">https://golang.org/cl/295371</a>: do not overflow key memory in GetQueuedCompletionStatus
    </p>

    <p><!-- CL 313653 -->
      TODO: <a href="https://golang.org/cl/313653">https://golang.org/cl/313653</a>: restore signal mask after setting foreground process group
    </p>
  </dd>
</dl><!-- syscall -->

<dl id="testing"><dt><a href="/pkg/testing/">testing</a></dt>
  <dd>
    <p><!-- CL 310033 -->
      TODO: <a href="https://golang.org/cl/310033">https://golang.org/cl/310033</a>: add -shuffle=off|on|N to alter the execution order of tests and benchmarks
    </p>
  </dd>
</dl><!-- testing -->

<dl id="text/template/parse"><dt><a href="/pkg/text/template/parse/">text/template/parse</a></dt>
  <dd>
    <p><!-- CL 301493 -->
      TODO: <a href="https://golang.org/cl/301493">https://golang.org/cl/301493</a>: add a mode to skip func-check on parsing
    </p>
  </dd>
</dl><!-- text/template/parse -->

<dl id="time"><dt><a href="/pkg/time/">time</a></dt>
  <dd>
    <p><!-- CL 260858 -->
      time.Time now has a <a href="/pkg/time/#Time.GoString">GoString</a>
      method that will return a more useful value for times when printed with
      the <code>"%#v"</code> format specifier in the fmt package.
    </p>

    <p><!-- CL 264077 -->
      TODO: <a href="https://golang.org/cl/264077">https://golang.org/cl/264077</a>: add Time.IsDST() to check if its Location is in Daylight Savings Time
    </p>

    <p><!-- CL 293349 -->
      TODO: <a href="https://golang.org/cl/293349">https://golang.org/cl/293349</a>: add Time.Unix{Milli,Micro} and to-Time helpers UnixMicro, UnixMilli
    </p>

    <p><!-- CL 300996 -->
      TODO: <a href="https://golang.org/cl/300996">https://golang.org/cl/300996</a>: support &#34;,&#34; as separator for fractional seconds
    </p>
  </dd>
</dl><!-- time -->

<dl id="unicode"><dt><a href="/pkg/unicode/">unicode</a></dt>
  <dd>
    <p><!-- CL 280493 -->
      The <a href="/pkg/unicode/#Is"><code>Is</code></a>,
      <a href="/pkg/unicode/#IsGraphic"><code>IsGraphic</code></a>,
      <a href="/pkg/unicode/#IsLetter"><code>IsLetter</code></a>,
      <a href="/pkg/unicode/#IsLower"><code>IsLower</code></a>,
      <a href="/pkg/unicode/#IsMark"><code>IsMark</code></a>,
      <a href="/pkg/unicode/#IsNumber"><code>IsNumber</code></a>,
      <a href="/pkg/unicode/#IsPrint"><code>IsPrint</code></a>,
      <a href="/pkg/unicode/#IsPunct"><code>IsPunct</code></a>,
      <a href="/pkg/unicode/#IsSpace"><code>IsSpace</code></a>,
      <a href="/pkg/unicode/#IsSymbol"><code>IsSymbol</code></a>, and
      <a href="/pkg/unicode/#IsUpper"><code>IsUpper</code></a> functions
      now return <code>false</code> on negative rune values, as they do for other invalid runes.
    </p>
  </dd>
</dl><!-- unicode -->