go: Export the latest version of internal guide. (#915)

The updates enhance the existing guidance around package naming, utility
packages, import renaming, function call arguments that span many lines,
and the prohibition of assertion frameworks.

go/decisions.md

@@ -113,8 +113,12 @@ code may contain underscores. Specific examples include:
 [shadowed]: best-practices#shadowing
 
 Avoid uninformative package names like `util`, `utility`, `common`, `helper`,
-and so on. See more about
-[so-called "utility packages"](best-practices#util-packages).
+`models`, and so on that would tempt users of the package to
+[rename it when importing](#import-renaming). See:
+
+*   [Guidance on so-called "utility packages"](best-practices#util-packages)
+*   [Go Tip #97: What's in a Name](https://google.github.io/styleguide/go/index.html#gotip)
+*   [Go Tip #108: The Power of a Good Package Name](https://google.github.io/styleguide/go/index.html#gotip)
 
 When an imported package is renamed (e.g. `import foopb
 "path/to/foo_go_proto"`), the local name for the package must comply with the
@@ -840,18 +844,23 @@ Tips:
 
 ### Import renaming
 
-Imports should only be renamed to avoid a name collision with other imports. (A
-corollary of this is that [good package names](#package-names) should not
-require renaming.) In the event of a name collision, prefer to rename the most
-local or project-specific import. Local names (aliases) for packages must follow
+Package imports shouldn't normally be renamed, but there are cases where they
+must be renamed or where a rename improves readability.
+
+Local names for imported packages must follow
 [the guidance around package naming](#package-names), including the prohibition
-on the use of underscores and capital letters.
+on the use of underscores and capital letters. Try to be
+[consistent](guide#consistency) by always using the same local name for the same
+imported package.
 
-Generated protocol buffer packages must be renamed to remove underscores from
-their names, and their aliases must have a `pb` suffix. See
-[proto and stub best practices] for more information.
+An imported package *must* be renamed to avoid a name collision with other
+imports. (A corollary of this is that [good package names](#package-names)
+should not require renaming.) In the event of a name collision, prefer to rename
+the most local or project-specific import.
 
-[proto and stub best practices]: best-practices#import-protos
+Generated protocol buffer packages *must* be renamed to remove underscores from
+their names, and their local names must have a `pb` suffix. See [proto and stub
+best practices] for more information.
 
 ```go
 // Good:
@@ -860,14 +869,10 @@ import (
 )
 ```
 
-Imports that have package names with no useful identifying information (e.g.
-`package v1`) should be renamed to include the previous path component. The
-rename must be consistent with other local files importing the same package and
-may include the version number.
-
-**Note:** It is preferred to rename the package to conform with
-[good package names](#package-names), but that is often not feasible for
-packages in vendored directories.
+Lastly, an imported, non-autogenerated package *can* be renamed if it has an
+uninformative name (e.g. `util` or `v1`) Do this sparingly: do not rename the
+package if the code surrounding the use of the package conveys enough context.
+When possible, prefer refactoring the package itself with a more suitable name.
 
 ```go
 // Good:
@@ -1781,20 +1786,19 @@ understanding the call.
 
 ```go
 // Good:
-canvas.RenderCube(cube,
-    x0, y0, z0,
-    x0, y0, z1,
-    x0, y1, z0,
-    x0, y1, z1,
-    x1, y0, z0,
-    x1, y0, z1,
-    x1, y1, z0,
-    x1, y1, z1,
+canvas.RenderHeptagon(fillColor,
+    x0, y0, vertexColor0,
+    x1, y1, vertexColor1,
+    x2, y2, vertexColor2,
+    x3, y3, vertexColor3,
+    x4, y4, vertexColor4,
+    x5, y5, vertexColor5,
+    x6, y6, vertexColor6,
 )
 ```
 
 Note that the lines in the above example are not wrapped at a specific column
-boundary but are grouped based on coordinate triples.
+boundary but are grouped based on vertex coordinates and color.
 
 Long string literals within functions should not be broken for the sake of line
 length. For functions that include such strings, a line break can be added after
@@ -3036,10 +3040,13 @@ See also:
 *   [Print diffs](#print-diffs)
 *   For more on the distinction between test helpers and assertion helpers, see
     [best practices](best-practices#test-functions)
+*   [Go FAQ] section on [testing frameworks] and their opinionated absence
 
 [useful failure messages]: #useful-test-failures
 [`fmt`]: https://golang.org/pkg/fmt/
 [marking test helpers]: #mark-test-helpers
+[Go FAQ]: https://go.dev/doc/faq
+[testing frameworks]: https://go.dev/doc/faq#testing_framework
 
 <a id="identify-the-function"></a>