From c586630d993f6136d3166837669b26f4210a79d5 Mon Sep 17 00:00:00 2001 From: Joe Tsai Date: Thu, 8 Dec 2016 23:21:48 -0800 Subject: [PATCH] doc: update go1.8.html Made many minor changes so that the document is consistent with itself. Some more noticeable changes: * CL/34141: Revert "testing: add T.Context method" * CL/33630: net/http: document restrictions on ETag as expected by ServeContent Change-Id: I39ae5e55c56e374895c115e6852998c940beae35 Reviewed-on: https://go-review.googlesource.com/34243 Reviewed-by: Brad Fitzpatrick --- doc/go1.8.html | 260 ++++++++++++++++++++++++------------------------- 1 file changed, 125 insertions(+), 135 deletions(-) diff --git a/doc/go1.8.html b/doc/go1.8.html index d1ee69305b..c090103bb9 100644 --- a/doc/go1.8.html +++ b/doc/go1.8.html @@ -101,8 +101,9 @@ and cancelation.

Go 1.8 will be the last release to support Linux on ARMv5E and ARMv6 processors: Go 1.9 will likely require the ARMv6K (as found in the Raspberry Pi 1) or later. - To identify whether a Linux system is ARMv6K or later, run go tool dist -check-armv6k - (to facilitate testing, it is also possible to just copy the dist command to the + To identify whether a Linux system is ARMv6K or later, run + “go tool dist -check-armv6k” + (to facilitate testing, it is also possible to just copy the dist command to the system without installing a full copy of Go 1.8) and if the program terminates with output "ARMv6K supported." then the system implements ARMv6K or later. @@ -133,8 +134,9 @@ For 64-bit x86 systems, the following instructions have been added: MOVSHDUP, MOVSLDUP, VMOVDDUP, -VMOVSHDUP, -and VMOVSLDUP.

+VMOVSHDUP, and +VMOVSLDUP. +

For 64-bit PPC systems, the common vector scalar instructions have been @@ -216,7 +218,7 @@ added: XXSEL, XXSI, XXSLDWI, -XXSPLT, and +XXSPLT, and XXSPLTW.

@@ -224,8 +226,8 @@ added:

The yacc tool (previously available by running -“go tool yacc”) -has been removed. As of Go 1.7 it was no longer used by the Go compiler. +“go tool yacc”) has been removed. +As of Go 1.7 it was no longer used by the Go compiler. It has moved to the “tools” repository and is now available at golang.org/x/tools/cmd/goyacc.

@@ -242,7 +244,7 @@ It has moved to the “tools” repository and is now available at

The pprof tool can now profile TLS servers - and skip certificate validation by using the "https+insecure" + and skip certificate validation by using the “https+insecure” URL scheme.

@@ -269,13 +271,13 @@ It has moved to the “tools” repository and is now available at

Vet is stricter in some ways and looser where it previously caused false positives.

-

Vet now checks copying an array of locks, +

Vet now checks for copying an array of locks, duplicate JSON and XML struct field tags, non-space-separated struct tags, deferred calls to HTTP Response.Body.Close - before checking errors, - indexed arguments in Printf, - and improves existing checks.

+ before checking errors, and + indexed arguments in Printf. + It also improves existing checks.

Compiler Toolchain

@@ -323,7 +325,7 @@ see improvements closer to the 32-bit ARM numbers.

The environment variable PKG_CONFIG may now be used to -set the program to run to handle #cgo pkg-config +set the program to run to handle #cgo pkg-config directives. The default is pkg-config, the program always used by earlier releases. This is intended to make it easier to cross-compile @@ -377,8 +379,8 @@ version of gccgo.

The new - “go - bug” command starts a bug report on GitHub, prefilled + “go bug” + command starts a bug report on GitHub, prefilled with information about the current system.

@@ -386,9 +388,8 @@ version of gccgo.

The - “go - doc” command - now groups constants and variables with their type, + “go doc” + command now groups constants and variables with their type, following the behavior of godoc.

@@ -460,7 +461,7 @@ and give more detail.

MemStats Documentation

- The runtime's MemStats + The runtime.MemStats type has been more thoroughly documented.

@@ -498,7 +499,7 @@ There have been optimizations to implementations in the strings, syscall, text/template, and -unicode/utf8, +unicode/utf8 packages.

@@ -590,9 +591,6 @@ now implements the new takes a context argument.
  • There have been significant additions to the database/sql package with context support.
    • -
  • The new T.Context - method in the testing package now returns a context for - the active test or benchmark.
  • All nine of the new Lookup methods on the new net.Resolver now take a context.
    • @@ -606,7 +604,7 @@ now implements the new

    Most users will want to use the new -mutexprofile - flag with go test, + flag with “go test”, and then use pprof on the resultant file.

    @@ -622,8 +620,8 @@ now implements the new

    As always, there are various minor changes and updates to the library, made with the Go 1 promise of compatibility -in mind. The follow sections list the user visible changes and additions. -Optimizations and bug fixes are not listed. +in mind. The following sections list the user visible changes and additions. +Optimizations and minor bug fixes are not listed.

    archive/tar
    @@ -664,11 +662,11 @@ Optimizations and bug fixes are not listed. There have been some minor fixes to the encoder to improve the compression ratio in certain situations. As a result, the exact encoded output of DEFLATE may be different from Go 1.7. Since - DEFLATE is the underlying compression of gzip, png, zlib, and zip, + DEFLATE is the underlying compression of gzip, png, zlib, and zip, those formats may have changed outputs.

    -

    +

    The encoder, when operating in NoCompression mode, now produces a consistent output that is not dependent on @@ -789,7 +787,7 @@ Optimizations and bug fixes are not listed. AES-128-CBC cipher suites with SHA-256 are also now supported.

    - +
    @@ -830,69 +828,69 @@ crypto/x509: return error for missing SerialNumber (CL 27238) at /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem on Linux, to support RHEL and CentOS.

    - + - +
    database/sql

    - The package now supports context.Context. There are new methods - ending in Context such as - DB.QueryContext and - DB.PrepareContext - that take context arguments. Using the new Context methods ensures that - connections are closed and returned to the connection pool when the - request is done; enables canceling in-progress queries - should the driver support that; and allows the database - pool to cancel waiting for the next available connection. + The package now supports context.Context. There are new methods + ending in Context such as + DB.QueryContext and + DB.PrepareContext + that take context arguments. Using the new Context methods ensures that + connections are closed and returned to the connection pool when the + request is done; enables canceling in-progress queries + should the driver support that; and allows the database + pool to cancel waiting for the next available connection.

    The IsolationLevel - can now be set when starting a transaction by setting the isolation level - on the Context then passing that Context to - DB.BeginContext. - An error will be returned if an isolation level is selected that the driver - does not support. A read-only attribute may also be set on the transaction - with ReadOnlyContext. -

    -

    - Queries now expose the SQL column type information for drivers that support it. - Rows can return ColumnTypes - which can include SQL type information, column type lengths, and the Go type. + can now be set when starting a transaction by setting the isolation level + on the Context then passing that Context to + DB.BeginContext. + An error will be returned if an isolation level is selected that the driver + does not support. A read-only attribute may also be set on the transaction + with ReadOnlyContext.

    -

    - A Rows - can now represent multiple result sets. After - Rows.Next returns false, - Rows.NextResultSet - may be called to advance to the next result set. The existing Rows - should continue to be used after it advances to the next result set. -

    -

    - NamedArg may be used - as query arguments. The new function Named - helps create a NamedArg - more succinctly. -

    - If a driver supports the new - Pinger - interface, the DB's - DB.Ping - and - DB.PingContext - methods will use that interface to check whether a - database connection is still valid. -

    - The new Context query methods work for all drivers, but - Context cancelation is not responsive unless the driver has been - updated to use them. The other features require driver support in - database/sql/driver. - Driver authors should review the new interfaces. Users of existing - driver should review the driver documentation to see what - it supports and any system specific documentation on each feature. -

    + Queries now expose the SQL column type information for drivers that support it. + Rows can return ColumnTypes + which can include SQL type information, column type lengths, and the Go type. +

    +

    + A Rows + can now represent multiple result sets. After + Rows.Next returns false, + Rows.NextResultSet + may be called to advance to the next result set. The existing Rows + should continue to be used after it advances to the next result set. +

    +

    + NamedArg may be used + as query arguments. The new function Named + helps create a NamedArg + more succinctly. +

    + If a driver supports the new + Pinger + interface, the + DB.Ping + and + DB.PingContext + methods will use that interface to check whether a + database connection is still valid. +

    +

    + The new Context query methods work for all drivers, but + Context cancelation is not responsive unless the driver has been + updated to use them. The other features require driver support in + database/sql/driver. + Driver authors should review the new interfaces. Users of existing + driver should review the driver documentation to see what + it supports and any system specific documentation on each feature. +

    @@ -906,11 +904,9 @@ crypto/x509: return error for missing SerialNumber (CL 27238) StringTable, the method COFFSymbol.FullName, - and - File - fields - COFFSymbols and - StringTable. + and the fields + File.COFFSymbols and + File.StringTable.

    @@ -964,7 +960,6 @@ crypto/x509: return error for missing SerialNumber (CL 27238)

    - In previous versions of Go, unmarshaling a JSON null into an Unmarshaler was considered a no-op; now the Unmarshaler's @@ -1096,7 +1091,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238) Int.ModInverse now supports negative numbers.

    - + @@ -1123,9 +1118,9 @@ crypto/x509: return error for missing SerialNumber (CL 27238) ParseMediaType now preserves unnecessary backslash escapes as literals, in order to support MSIE. - When MSIE sends a full file path (in "intranet mode"), it does not - escape backslashes: "C:\dev\go\foo.txt", not - "C:\\dev\\go\\foo.txt". + When MSIE sends a full file path (in “intranet mode”), it does not + escape backslashes: “C:\dev\go\foo.txt”, not + “C:\\dev\\go\\foo.txt”. If we see an unnecessary backslash escape, we now assume it is from MSIE and intended as a literal backslash. No known MIME generators emit unnecessary backslash escapes @@ -1157,7 +1152,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238)
    net
    - +

    The Conn documentation has been updated to clarify expectations of an interface @@ -1178,8 +1173,8 @@ crypto/x509: return error for missing SerialNumber (CL 27238)

    - The new Buffers types permits - more efficiently writing to the network from multiple discontiguous buffers + The new Buffers type permits + writing to the network more efficiently from multiple discontiguous buffers in memory. On certain machines, for certain types of connections, this is optimized into an OS-specific batch write operation (such as writev).

    @@ -1196,8 +1191,8 @@ crypto/x509: return error for missing SerialNumber (CL 27238)

    - The Go DNS resolver now supports resolv.conf's "rotate" - and "option ndots:0" options. The "ndots" option is + The Go DNS resolver now supports resolv.conf's “rotate” + and “option ndots:0” options. The “ndots” option is now respected in the same way as libresolve.

    @@ -1224,7 +1219,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238) ServeContent now support HTTP If-Match conditional requests, in addition to the previous If-None-Match - support. + support for ETags properly formatted according to RFC 7232, section 2.3. @@ -1244,11 +1239,11 @@ crypto/x509: return error for missing SerialNumber (CL 27238) existing CloseNotifier support. This functionality requires that the underlying net.Conn implements - recently-clarified interface documentation. + recently clarified interface documentation.
  • - To serve trailers known after the header has been written, + To serve trailers produced after the header has already been written, see the new TrailerPrefix mechanism. @@ -1275,7 +1270,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238)

    Client & Transport changes:

      -
    • +
    • The Client now copies most request headers on redirect. See the documentation @@ -1320,7 +1315,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238)
    • The DefaultTransport.Dialer now enables DualStack ("Happy Eyeballs") support, - to use IPv4 as a backup if it looks like IPv6 might be + allowing the use of IPv4 as a backup if it looks like IPv6 might be failing.
      • @@ -1364,7 +1359,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238) ModifyResponse, for modifying the response from the back end before proxying it to the client.

      - +
    • @@ -1374,7 +1369,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238)

    Empty quoted strings are once again allowed in the name part of an address. That is, Go 1.4 and earlier accepted - "" <gopher@example.com>, + "" <gopher@example.com>, but Go 1.5 introduced a bug that rejected this address. The address is recognized again.

    @@ -1389,7 +1384,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238) allows parsing dates found in other header lines, such as the Resent-Date: header.

    - + @@ -1397,10 +1392,10 @@ crypto/x509: return error for missing SerialNumber (CL 27238)

    - If an implementation of - the Auth - interface's Start method returns an - empty toServer value, the package no longer sends + If an implementation of the + Auth.Start + method returns an empty toServer value, + the package no longer sends trailing whitespace in the SMTP AUTH command, which some servers rejected.

    @@ -1411,14 +1406,17 @@ crypto/x509: return error for missing SerialNumber (CL 27238)
    net/url
    -

    The new functions +

    + The new functions PathEscape and PathUnescape are similar to the query escaping and unescaping functions but - for path elements.

    + for path elements. +

    -

    The new methods +

    + The new methods URL.Hostname and URL.Port @@ -1426,7 +1424,8 @@ crypto/x509: return error for missing SerialNumber (CL 27238) correctly handling the case where the port may not be present.

    -

    The existing method +

    + The existing method URL.ResolveReference now properly handles paths with escaped bytes without losing the escaping. @@ -1445,7 +1444,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238) now rejects URLs like this_that:other/thing instead of interpreting them as relative paths (this_that is not a valid scheme). To force interpretation as a relative path, - such URLs should be prefixed with "./". + such URLs should be prefixed with “./”. The URL.String method now inserts this prefix as needed.

    @@ -1454,7 +1453,7 @@ crypto/x509: return error for missing SerialNumber (CL 27238)
    os
    -

    +

    The new function Executable returns the path name of the running executable. @@ -1475,12 +1474,12 @@ crypto/x509: return error for missing SerialNumber (CL 27238) existing empty directory. Previously it would fail when renaming to a non-empty directory but succeed when renaming to an empty directory. - This makes the behavior on Unix correspond to that on other systems. + This makes the behavior on Unix correspond to that of other systems.

    On Windows, long absolute paths are now transparently converted to - extended-length paths (paths that start with \\?\). + extended-length paths (paths that start with “\\?\”). This permits the package to work with files whose path names are longer than 260 characters.

    @@ -1505,16 +1504,15 @@ crypto/x509: return error for missing SerialNumber (CL 27238)
    path/filepath

    -

    A number of bugs and corner cases on Windows were fixed: - Abs now calls Clean paths as documented, + A number of bugs and corner cases on Windows were fixed: + Abs now calls Clean as documented, Glob now matches - "\\?\c:\*", + “\\?\c:\*”, EvalSymlinks now - correctly handles "C:.", and + correctly handles “C:.”, and Clean now properly - handles a leading ".." in the path. -

    - + handles a leading “..” in the path. +

    @@ -1615,14 +1613,6 @@ crypto/x509: return error for missing SerialNumber (CL 27238) test or benchmark.

    -

    - The new method - T.Context - (and B.Context) returns - a Context for - the current running test or benchmark. -

    -

    The new function CoverMode @@ -1635,15 +1625,15 @@ crypto/x509: return error for missing SerialNumber (CL 27238) Previously, individual test cases would appear to pass, and only the overall execution of the test binary would fail.

    - +
    unicode

    - SimpleFold now returns its argument unchanged - if the provided input was an invalid rune. + SimpleFold + now returns its argument unchanged if the provided input was an invalid rune. Previously, the implementation failed with an index bounds check panic.