From 12eac51beafb23e225a5e486c056626386672c60 Mon Sep 17 00:00:00 2001
From: Steve Traut <straut@google.com>
Date: Thu, 19 Aug 2021 10:27:41 -0400
Subject: _content/doc: module naming best practices

This adds new content with best practices for the module path. It also
revises existing content to use the best practice.

This change includes:

* A new "Naming a module" section in "Managing dependencies" describing
  naming best practices and reserved terms for module paths.
* Changing module path prefix from "example.com/*" to "example/*"
  where the content seems aimed specifically at new users. This is
  designed to reduce confusion for those who wonder if a domain name
  is required in the local, simple context.
* Links to the "Naming a module" section so that new users can follow up
  from the simple case to learn about best practices.

Change-Id: I07eac1f805ce506a486d3c0e7b54539554e3c30b
Reviewed-on: https://go-review.googlesource.com/c/website/+/344469
Trust: Steve Traut <straut@google.com>
Trust: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
---
 _content/doc/tutorial/getting-started.html | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

(limited to '_content/doc/tutorial/getting-started.html')

diff --git a/_content/doc/tutorial/getting-started.html b/_content/doc/tutorial/getting-started.html
index 43e23d97..2946f272 100644
--- a/_content/doc/tutorial/getting-started.html
+++ b/_content/doc/tutorial/getting-started.html
@@ -104,20 +104,24 @@ cd hello
       the
       <a href="/ref/mod#go-mod-init"><code>go mod init</code> command</a>,
         giving it the name of the module your code will be in. The name is the
-        module's module path. In most cases, this will be the repository
-        location where your source code will be kept, such as
-        <code>github.com/mymodule</code>. If you plan to publish your module
-        for others to use, the module path <em>must</em> be a location from
-        which Go tools can download your module.
+        module's module path.</p>
+    <p>In actual development, the module path will typically be the repository
+        location where your source code will be kept. For example, the module
+        path might be <code>github.com/mymodule</code>. If you plan to publish
+        your module for others to use, the module path <em>must</em> be a
+        location from which Go tools can download your module. For more about
+        naming a module with a module path, see
+        <a href="/doc/modules/managing-dependencies#naming_module">Managing
+            dependencies</a>.
     </p>
 
       <p>For the purposes of this tutorial, just use
-        <code>example.com/hello</code>.
+          <code>example/hello</code>.
     </p>
 
     <pre>
-$ go mod init example.com/hello
-go: creating new go.mod: module example.com/hello
+$ go mod init example/hello
+go: creating new go.mod: module example/hello
 </pre
     >
   </li>
-- 
cgit v1.3-6-g1900