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>
  TODO: complete this section
</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>

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

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

<p>
  TODO: complete this section, or delete if not needed
</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,
  avoding 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>

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

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

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

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

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

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

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

<p>
  TODO: complete this 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>

<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="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
  <p>
    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>
</dl><!-- net/http -->

<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>
  </dd>
</dl><!-- time -->
<p>
  TODO: complete this section
</p>