From: Daniel Martí <mvdan@mvdan.cc>
Date: Thu, 5 Jul 2018 13:17:46 +0000 (+0100)
Subject: doc: explain minor change to gofmt in go1.11
X-Git-Tag: go1.11beta3~102
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=889809719738ff5708c3ae94b67e1827ce6ff1a4;p=gostls13.git

doc: explain minor change to gofmt in go1.11

Add the tools section with a Gofmt sub-section, just like in
go1.10.html. Instead of copying the two last paragraphs from 1.10, which
warn users about the hidden complexity of enforcing gofmt, move that to
go/format and link to it.

While at it, remove a duplicate "Tools" header that was likely added by
accident.

Fixes #26228.

Change-Id: Ic511c44b2b86f82a41f2b78dd7e7482d694b6c62
Reviewed-on: https://go-review.googlesource.com/122295
Reviewed-by: Ian Lance Taylor <iant@golang.org>
---

diff --git a/doc/go1.11.html b/doc/go1.11.html
index 0100c32707..da722fb31a 100644
--- a/doc/go1.11.html
+++ b/doc/go1.11.html
@@ -266,8 +266,6 @@ func f(v interface{}) {
   This is currently only supported by Delve.
 </p>
 
-<h2 id="tools">Tools</h2>
-
 <h3 id="test">Test</h3>
 
 <p>
@@ -312,6 +310,26 @@ func f(v interface{}) {
   user task/region analysis page.
 </p>
 
+<h3 id="gofmt">Gofmt</h3>
+
+<p>
+  One minor detail of the default formatting of Go source code has changed.
+  When formatting expression lists with inline comments, the comments were
+  aligned according to a heuristic.
+  However, in some cases the alignment would be split up too easily, or
+  introduce too much whitespace.
+  The heuristic has been changed to behave better for human-written code.
+</p>
+
+<p>
+  Note that these kinds of minor updates to gofmt are expected from time to
+  time.
+  In general, systems that need consistent formatting of Go source code should
+  use a specific version of the <code>gofmt</code> binary.
+  See the <a href="/pkg/go/format/">go/format</a> package godoc for more
+  information.
+</p>
+
 <h2 id="runtime">Runtime</h2>
 
 <p><!-- CL 85887 -->
diff --git a/src/go/format/format.go b/src/go/format/format.go
index cad5958e5c..9aa28fc63b 100644
--- a/src/go/format/format.go
+++ b/src/go/format/format.go
@@ -3,6 +3,15 @@
 // license that can be found in the LICENSE file.
 
 // Package format implements standard formatting of Go source.
+//
+// Note that formatting of Go source code changes over time, so tools relying on
+// consistent formatting should execute a specific version of the gofmt binary
+// instead of using this package. That way, the formatting will be stable, and
+// the tools won't need to be recompiled each time gofmt changes.
+//
+// For example, pre-submit checks that use this package directly would behave
+// differently depending on what Go version each developer uses, causing the
+// check to be inherently fragile.
 package format
 
 import (
@@ -79,10 +88,6 @@ func Node(dst io.Writer, fset *token.FileSet, node interface{}) error {
 // space as src), and the result is indented by the same amount as the first
 // line of src containing code. Imports are not sorted for partial source files.
 //
-// Caution: Tools relying on consistent formatting based on the installed
-// version of gofmt (for instance, such as for presubmit checks) should
-// execute that gofmt binary instead of calling Source.
-//
 func Source(src []byte) ([]byte, error) {
 	fset := token.NewFileSet()
 	file, sourceAdj, indentAdj, err := parse(fset, "", src, true)