]> Cypherpunks repositories - gostls13.git/commitdiff
doc: add section on module paths to module documentation
authorJay Conrod <jayconrod@google.com>
Fri, 10 Jan 2020 20:46:34 +0000 (15:46 -0500)
committerJay Conrod <jayconrod@google.com>
Fri, 7 Feb 2020 18:04:09 +0000 (18:04 +0000)
Updates #33637

Change-Id: I2197b20c2da2a5f57aacd40cc14611c5e6e25c5f
Reviewed-on: https://go-review.googlesource.com/c/go/+/214377
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Tyler Bui-Palsulich <tbp@google.com>
doc/modules.md

index 4d582c597d193d20d83cd68474b842c7b0a4af30..9a0dfc7c1bf5d109a6ad1444eaa5a553818f0459 100644 (file)
@@ -29,6 +29,38 @@ containing the package (relative to the module root). For example, the module
 `"golang.org/x/net"` contains a package in the directory `"html"`. That
 package's path is `"golang.org/x/net/html"`.
 
+<a id="module-path"></a>
+### Module paths
+
+A [*module path*](#glos-module-path) is the canonical name for a module,
+declared with the [`module` directive](#go.mod-module) in the module's
+[`go.mod` file](#glos-go.mod-file). A module's path is the prefix for package
+paths within the module.
+
+A module path should describe both what the module does and where to find it.
+Typically, a module path consists of a repository root path, a subdirectory
+within the repository (usually empty), and a major version suffix (for major
+version 2 or higher).
+
+* The repository root path is part of a URL that corresponds to a version
+  control repository. For example, `golang.org/x/net`. See [Custom import
+  paths](#custom-import-paths) for details on how paths are resolved to
+  repositories.
+* If the module is in a subdirectory of the version control repository, the
+  subdirectory should be part of the module path (but not the repository root
+  path). For example, the module `golang.org/x/tools/gopls` is in the `/gopls`
+  subdirectory of the repository `golang.org/x/tools`.
+* If the module is released at major version 2 or higher, the module path must
+  end with a [major version suffix](#major-version-suffixes) like
+  `/v2`. This may or may not be part of the subdirectory name. For example, the
+  module with path `golang.org/x/repo/sub/v2` could be in the `/sub` or
+  `/sub/v2` subdirectory of the repository `golang.org/x/repo`.
+
+If a module might be depended on by other modules, these rules must be followed
+so that the `go` command can find and download the module. There are also
+several [lexical restrictions](#go.mod-ident) on characters allowed in
+module paths.
+
 <a id="versions"></a>
 ### Versions