_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>
diff --git a/_content/doc/code.html b/_content/doc/code.html
index ffa9b08..973871a 100644
--- a/_content/doc/code.html
+++ b/_content/doc/code.html
@@ -66,17 +66,17 @@
<p>
To compile and run a simple program, first choose a module path (we'll use
-<code>example.com/user/hello</code>) and create a <code>go.mod</code> file that
+<code>example/user/hello</code>) and create a <code>go.mod</code> file that
declares it:
</p>
<pre>
$ mkdir hello # Alternatively, clone it if it already exists in version control.
$ cd hello
-$ <b>go mod init example.com/user/hello</b>
-go: creating new go.mod: module example.com/user/hello
+$ <b>go mod init example/user/hello</b>
+go: creating new go.mod: module example/user/hello
$ cat go.mod
-module example.com/user/hello
+module example/user/hello
go 1.16
$
@@ -108,7 +108,7 @@
</p>
<pre>
-$ <b>go install example.com/user/hello</b>
+$ <b>go install example/user/hello</b>
$
</pre>
@@ -151,7 +151,7 @@
<p>
Commands like <code>go install</code> apply within the context of the module
containing the current working directory. If the working directory is not within
-the <code>example.com/user/hello</code> module, <code>go install</code> may fail.
+the <code>example/user/hello</code> module, <code>go install</code> may fail.
</p>
<p>
@@ -162,7 +162,7 @@
</p>
<pre>
-$ go install example.com/user/hello
+$ go install example/user/hello
</pre>
<pre>
@@ -272,7 +272,7 @@
import (
"fmt"
- <b>"example.com/user/hello/morestrings"</b>
+ <b>"example/user/hello/morestrings"</b>
)
func main() {
@@ -285,7 +285,7 @@
</p>
<pre>
-$ <b>go install example.com/user/hello</b>
+$ <b>go install example/user/hello</b>
</pre>
<p>
@@ -312,7 +312,7 @@
import (
"fmt"
- "example.com/user/hello/morestrings"
+ "example/user/hello/morestrings"
"github.com/google/go-cmp/cmp"
)
@@ -333,7 +333,7 @@
$ go mod tidy
go: finding module for package github.com/google/go-cmp/cmp
go: found github.com/google/go-cmp/cmp in github.com/google/go-cmp v0.5.4
-$ go install example.com/user/hello
+$ go install example/user/hello
$ hello
Hello, Go!
string(
@@ -341,7 +341,7 @@
+ "Hello Go",
)
$ cat go.mod
-module example.com/user/hello
+module example/user/hello
go 1.16
@@ -415,7 +415,7 @@
<pre>
$ <b>go test</b>
PASS
-ok example.com/user/morestrings 0.165s
+ok example/user/hello/morestrings 0.165s
$
</pre>
diff --git a/_content/doc/faq.html b/_content/doc/faq.html
index 928db42..a2dce2f 100644
--- a/_content/doc/faq.html
+++ b/_content/doc/faq.html
@@ -1327,7 +1327,7 @@
</p>
<pre>
-go mod init example.com/project
+go mod init example/project
</pre>
<p>
diff --git a/_content/doc/modules/gomod-ref.md b/_content/doc/modules/gomod-ref.md
index c39ee46..d78e6c0 100644
--- a/_content/doc/modules/gomod-ref.md
+++ b/_content/doc/modules/gomod-ref.md
@@ -21,10 +21,10 @@
Go generates a go.mod file when you run the [`go mod init`
command](/ref/mod#go-mod-init). The following example creates a go.mod file,
-setting the module's module path to example.com/mymodule:
+setting the module's module path to example/mymodule:
```
-$ go mod init example.com/mymodule
+$ go mod init example/mymodule
```
Use `go` commands to manage dependencies. The commands ensure that the
@@ -46,8 +46,8 @@
## Example {#example}
-A go.mod file includes directives shown in the following example. These are
-described in this topic.
+A go.mod file includes directives as shown in the following example. These are
+described elsewhere in this topic.
```
module example.com/mymodule
@@ -67,8 +67,8 @@
## module {#module}
Declares the module's module path, which is the module's unique identifier
-(when combined with the module version number). This becomes the import prefix
-for all packages the module contains.
+(when combined with the module version number). The module path becomes the
+import prefix for all packages the module contains.
For more, see [`module` directive](/ref/mod#go-mod-file-module) in the
Go Modules Reference.
@@ -101,9 +101,16 @@
### Notes {#module-notes}
-The module path should be a path from which Go tools can download the module
-source. In practice, this is typically the module source's repository domain
-and path to the module code within the repository. The <code>go</code> command
+The module path must uniquely identify your module. For most modules, the path
+is a URL where the `go` command can find the code (or a redirect to the code).
+For modules that won't ever be downloaded directly, the module path
+can be just some name you control that will ensure uniqueness. The prefix
+`example/` is also reserved for use in examples like these.
+
+For more details, see [Managing dependencies](/doc/modules/managing-dependencies#naming_module).
+
+In practice, the module path is typically the module source's repository domain
+and path to the module code within the repository. The `go` command
relies on this form when downloading module versions to resolve dependencies
on the module user's behalf.
@@ -113,14 +120,16 @@
If at first you don't know the module's eventual repository location, consider
temporarily using a safe substitute, such as the name of a domain you own or
-`example.com`, along with a path following from the module's name or source
-directory.
+a name you control (such as your company name), along with a path following
+from the module's name or source directory. For more, see
+[Managing dependencies](/doc/modules/managing-dependencies#naming_module).
For example, if you're developing in a `stringtools` directory, your temporary
-module path might be `example.com/stringtools`, as in the following example:
+module path might be `<company-name>/stringtools`, as in the following example,
+where _company-name_ is your company's name:
```
-go mod init example.com/stringtools
+go mod init <company-name>/stringtools
```
## go {#go}
@@ -433,7 +442,8 @@
go mod edit -exclude=example.com/theirmodule@v1.3.0
```
-For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
+For more about version numbers, see
+[Module version numbering](/doc/modules/version-numbers).
## retract {#retract}
@@ -442,6 +452,9 @@
published prematurely or a severe problem was discovered after the version was
published.
+For more, see [`retract` directive](/ref/mod#go-mod-file-retract) in the
+Go Modules Reference.
+
### Syntax {#retract-syntax}
<pre>
diff --git a/_content/doc/modules/managing-dependencies.md b/_content/doc/modules/managing-dependencies.md
index 6955dd5..aaf5fcb 100644
--- a/_content/doc/modules/managing-dependencies.md
+++ b/_content/doc/modules/managing-dependencies.md
@@ -90,21 +90,23 @@
its own module. This creates a go.mod file at the root of your source tree.
Dependencies you add will be listed in that file.
-To add your code to its own module, use the [`go mod init`
-command](/ref/mod#go-mod-init).
-For example, from the command line, change to your code's root directory, then
-run the command as in the following example:
+To add your code to its own module, use the
+[`go mod init` command](/ref/mod#go-mod-init). For example, from the command
+line, change to your code's root directory, then run the command as in the
+following example:
```
-$ go mod init example.com/mymodule
+$ go mod init example/mymodule
```
The `go mod init` command's argument is your module's module path. If possible,
-the module path should be the repository location of your source code. If at
-first you don't know the module's eventual repository location, consider
-temporarily using a safe substitute, such as the name of a domain you own or
-`example.com`, along with a path following from the module's name or source
-directory.
+the module path should be the repository location of your source code.
+
+If at first you don't know the module's eventual repository location, use a
+safe substitute. This might be the name of a domain you own or another name you
+control (such as your company name), along with a path following from the
+module's name or source directory. For more, see
+[Naming a module](#naming_module).
As you use Go tools to manage dependencies, the tools update the go.mod file so
that it maintains a current list of your dependencies.
@@ -118,6 +120,64 @@
See the [go.mod reference](/doc/modules/gomod-ref) for more.
+## Naming a module {#naming_module}
+
+When you run `go mod init` to create a module for tracking dependencies, you
+specify a module path that serves as the module's name. The module path
+becomes the import path prefix for packages in the module. Be sure to specify
+a module path that won't conflict with the module path of other modules.
+
+At a minimum, a module path need only indicate something about its origin, such
+as a company or author or owner name. But the path might also be more
+descriptive about what the module is or does.
+
+The module path is typically of the following form:
+
+```
+<prefix>/<descriptive-text>
+```
+
+* The _prefix_ is typically a string that partially describes the module, such
+ as a string that describes its origin. This might be:
+
+ * The location of the repository where Go tools can find the module's source
+ code (required if you're publishing the module).
+
+ For example, it might be `github.com/<project-name>/`.
+
+ Use this best practice if you think you might publish the module for
+ others to use. For more about publishing, see
+ [Developing and publishing modules](/doc/modules/developing).
+
+ * A name you control.
+
+ If you're not using a repository name, be sure to choose a prefix that
+ you're confident won't be used by others. A good choice is your
+ company's name. Avoid common terms such as `widgets`, `utilities`, or
+ `app`.
+
+* For the _descriptive text_, a good choice would be a project name. Remember
+ that package names carry most of the weight of describing functionality.
+ The module path creates a namespace for those package names.
+
+**Reserved module path prefixes**
+
+Go guarantees that the following strings won't be used in package names.
+
+- `test` -- You can use `test` as a module path prefix for a module whose code
+ is designed to locally test functions in another module.
+
+ Use the `test` path prefix for modules that are created as part of a test.
+ For example, your test itself might run `go mod init test` and then set up
+ that module in some particular way in order to test with a Go source code
+ analysis tool.
+
+- `example` -- Used as a module path prefix in some Go documentation, such as
+ in tutorials where you're creating a module just to track dependencies.
+
+ Note that Go documentation also uses `example.com` to illustrate when the
+ example might be a published module.
+
## Adding a dependency {#adding_dependency}
Once you're importing packages from a published module, you can add that module
diff --git a/_content/doc/modules/managing-source.md b/_content/doc/modules/managing-source.md
index 63ebc41..6fe171b 100644
--- a/_content/doc/modules/managing-source.md
+++ b/_content/doc/modules/managing-source.md
@@ -78,8 +78,11 @@
<a href="gomod-ref">go.mod reference</a>.</p>
<p>The module path will be given in a module directive, such as:</p>
<pre>module example.com/mymodule</pre>
- <p>Though you can edit this file, much of it is maintained for you by go
- commands.</p>
+ <p>For more about choosing a module path, see
+ <a href="/doc/modules/managing-dependencies#naming_module">Managing
+ dependencies</a>.</p>
+ <p>Though you can edit the go.mod file, you'll find it more reliable to
+ make changes through <code>go</code> commands.</p>
</td>
</tr>
<tr class="DocTable-row">
@@ -90,7 +93,7 @@
authentic. Where this confirmation fails, Go will display a security error.<p>
<p>The file will be empty or not present when there are no dependencies.
You shouldn't edit this file except by using the <code>go mod tidy</code>
- command, which removes unneeded entries.</p>
+ command, which removes unneeded entries.</p>
</td>
</tr>
<tr class="DocTable-row">
diff --git a/_content/doc/tutorial/create-module.html b/_content/doc/tutorial/create-module.html
index e9df336..d187f4f 100644
--- a/_content/doc/tutorial/create-module.html
+++ b/_content/doc/tutorial/create-module.html
@@ -152,6 +152,12 @@
Go tools. That would be your code's repository.
</p>
+ <p>
+ For more on naming your module with a module path, see
+ <a href="/doc/modules/managing-dependencies#naming_module">Managing
+ dependencies</a>.
+ </p>
+
<pre>
$ go mod init example.com/greetings
go: creating new go.mod: module example.com/greetings
diff --git a/_content/doc/tutorial/database-access.md b/_content/doc/tutorial/database-access.md
index 16a3d7c..361021f 100644
--- a/_content/doc/tutorial/database-access.md
+++ b/_content/doc/tutorial/database-access.md
@@ -78,14 +78,18 @@
Run the `go mod init` command, giving it your new code's module path.
```
- $ go mod init example.com/data-access
- go: creating new go.mod: module example.com/data-access
+ $ go mod init example/data-access
+ go: creating new go.mod: module example/data-access
```
This command creates a go.mod file in which dependencies you add will be
listed for tracking. For more, be sure to see
[Managing dependencies](/doc/modules/managing-dependencies).
+ **Note:** In actual development, you'd specify a module path that's
+ more specific to your own needs. For more, see
+ [Managing dependencies](/doc/modules/managing-dependencies#naming_module).
+
Next, you'll create a database.
## Set up a database {#set_up_database}
diff --git a/_content/doc/tutorial/getting-started.html b/_content/doc/tutorial/getting-started.html
index 43e23d9..2946f27 100644
--- a/_content/doc/tutorial/getting-started.html
+++ b/_content/doc/tutorial/getting-started.html
@@ -104,20 +104,24 @@
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>
diff --git a/_content/doc/tutorial/web-service-gin.md b/_content/doc/tutorial/web-service-gin.md
index 60767bf..99447ea 100644
--- a/_content/doc/tutorial/web-service-gin.md
+++ b/_content/doc/tutorial/web-service-gin.md
@@ -98,13 +98,13 @@
will be in.
```
- $ go mod init example.com/web-service-gin
- go: creating new go.mod: module example.com/web-service-gin
+ $ go mod init example/web-service-gin
+ go: creating new go.mod: module example/web-service-gin
```
This command creates a go.mod file in which dependencies you add will be
- listed for tracking. For more, be sure to see
- [Managing dependencies](/doc/modules/managing-dependencies).
+ listed for tracking. For more about naming a module with a module path, see
+ [Managing dependencies](/doc/modules/managing-dependencies#naming_module).
Next, you'll design data structures for handling data.
