[go] cmd/go/internal/help: reword packages and importpath docs

[Sean Liao (Gerrit)]

Sean Liao has uploaded the change for review

Commit message

cmd/go/internal/help: reword packages and importpath docs

This moves around some of the docs for packages and import paths
so similar concepts are grouped closer together.
It should read better if read top to bottom.
Follow up for CL 664235.

For #57655

Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Change diff

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 402cbc0..7c8cb59 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -2887,12 +2887,21 @@
 //
 // # Import path syntax
 //
-// An import path (see 'go help packages') denotes a package stored in the local
-// file system. In general, an import path denotes either a standard package (such
-// as "unicode/utf8") or a package found in a module (For more
+// An import path is used to uniquely identify and locate a package.
+// In general, an import path denotes either a standard library package
+// (such as "unicode/utf8") or a package found in a module (for more
 // details see: 'go help modules').
 //
-// # Internal Packages
+// The standard library reserves all import paths without a dot in the
+// first element for its packages. See "Fully-qualified import paths"
+// below for choosing an import path for your module.
+// The following names are reserved to be used as short module names
+// when working locally, and in tutorials, examples, and test code.
+//
+// - "test"
+// - "example"
+//
+// # Internal packages
 //
 // Code in or below a directory named "internal" is importable only
 // by code that shares the same import path above the internal directory.
@@ -2924,8 +2933,26 @@
 // # Fully-qualified import paths
 //
 // A fully-qualified import path for a package not belonging to the standard library
-// starts with the path of the module the package to which the package belongs. The module's path
-// specifies where to obtain the source code for the module.
+// starts with the path of the module the package to which the package belongs.
+// The module's path specifies where to obtain the source code for the module.
+// The complete import path is formed by joining the module path with the
+// relative directory path of a package within the module. Example:
+//
+//	/home/user/modules/m/
+//	        go.mod                 (declares "module example.com/m")
+//	        crash/
+//	            bang/              (importable as "example.com/m/crash/bang")
+//	                b.go
+//	        foo/                   (importable as "example.com/m/foo")
+//	            f.go
+//	            bar/               (importable as "example.com/m/foo/bar")
+//	                x.go
+//
+// As import paths without a dot in the first element are reserved by the standard library,
+// module paths (which form the prefix of all import paths) should start with an element
+// containing a dot, e.g. "github.com/user/repo", or "example.com/project".
+// An module path may point directly to a code hosting service,
+// or to a custom address that points to the code hosting service in a html meta tags.
 //
 // Import paths belonging to modules hosted on common code hosting sites have special syntax:
 //
@@ -3106,105 +3133,137 @@
 //
 //	go <action> [packages]
 //
-// Usually, [packages] is a list of import paths.
+// Usually, [packages] is a list of package patterns,
+// which can take several forms:
 //
-// An import path that is a rooted path or that begins with
-// a . or .. element is interpreted as a file system path and
-// denotes the package in that directory.
+// - A relative or absolute path to a file system directory
+// - An import path
+// - A reserved name that expands to a set of packages
+// - A list of files
 //
-// An import path beginning with ./ or ../ is called a relative path.
-// A relative path can be used as a shorthand on the command line.
+// If no import paths are given, the action applies to the
+// package in the current directory.
+//
+// A pattern contains "..." wildcards elements,
+// which is expanded to match 0 or more path elements.
+// Specific rules are described below.
+//
+// # File system patterns
+//
+// Patterns beginning with a file system root like / on Unixes,
+// or a volume name like C: on Windows are interpreted as absolute file system paths.
+// Patterns beginning with a "." or ".." element are interpreted as relative file system paths.
+// File system paths denote the package contained within the given directory.
+//
+// Relative path can be used as a shorthand on the command line.
 // If you are working in the directory containing the code imported as
 // "unicode" and want to run the tests for "unicode/utf8", you can type
 // "go test ./utf8" instead of needing to specify the full path.
 // Similarly, in the reverse situation, "go test .." will test "unicode" from
 // the "unicode/utf8" directory. Relative patterns are also allowed, like
-// "go test ./..." to test all subdirectories. See 'go help packages' for details
-// on the pattern syntax.
+// "go test ./..." to test all subdirectories.
 //
-// Otherwise, the import path P denotes a package found in
-// one of the modules in the build list. The "build list" is the
-// list of module versions used for a build.
+// File system patterns expanded with the "..." wildcard exclude the following:
+//
+// - Directories named "vendor"
+// - Directories named "testdata"
+// - Files and directories with names beginning with "_" or "."
+// - Directories that contain other go modules
+// - Directories matching an ignore directive in a module's go.mod file
+//
+// These can be included by either using them in the prefix,
+// or changing into the directories. For example, "./..." won't
+// match a "./testdata/foo" package, but "./testdata/..." will.
+//
+// Directories containing other go modules can only be matched
+// by changing the working directory into module.
+//
+// # Import path patterns
+//
+// Patterns may be import paths as described in "go help importpath".
+// Import path patterns generally describe the packages contained
+// in the build list, the set of packages in the current modules'
+// dependency graph.
 // See https://go.dev/ref/mod#glos-build-list for more details.
 //
-// If no import paths are given, the action applies to the
-// package in the current directory.
+// Some commands accept versioned package patterns,
+// like: "example.com/my/mod...@v1.2.3"
+// These describe the matching package at the given version,
+// independent of the versions used by the current module.
 //
-// There are several reserved names for paths that should not be used
-// for packages to be built with the go tool:
+// Import path patterns may also use a "..." wildcard,
+// like: "example.com/my/module/...".
+// This can be combined with the version specifier
+// like: "example.com/my/module/...@latest".
 //
-// - "main" denotes the top-level package in a stand-alone executable.
+// Import path pattern expansion with "..." depends on context:
+//
+//   - "prefix/..." matches all packages in the build list that share the prefix,
+//     even if they belong to different modules.
+//   - if "prefix/..." didn't match any packages in the build list,
+//     then it only includes packages within the module that contains "prefix".
+//
+// # Reserved names
+//
+// The following reserved names expand to a set of packages:
 //
 // - "work" expands to all packages in the main module (or workspace modules).
 //
+// - "tool" expands to the tools defined in the current module's go.mod file.
+//
 // - "all" expands to all packages in the main module (or workspace modules) and
 // their dependencies, including dependencies needed by tests of any of those. In
 // the legacy GOPATH mode, "all" expands to all packages found in all the GOPATH trees.
 //
-// - "std" is like all but expands to just the packages in the standard
-// Go library.
+// - "std" epands to all the packages in the standard library
+// and their internal libraries.
 //
 // - "cmd" expands to the Go repository's commands and their
 // internal libraries.
 //
-// - "tool" expands to the tools defined in the current module's go.mod file.
+// # List of .go files
 //
-// Package names match against fully-qualified import paths or patterns that
-// match against any number of import paths. For instance, "fmt" refers to the
-// standard library's package fmt, but "http" alone for package http would not
-// match the import path "net/http" from the standard library. Instead, the
-// complete import path "net/http" must be used.
+// If the pattern is a list of Go files rather than a complete package,
+// the go command synthesizes a virtual package named "command-line-arguments"
+// containing just the given files. In most cases, it is an error
+// to do so (e.g. "go build main.go"). Instead prefer to operate on
+// complete packages (directories), like: "go build .".
 //
-// Import paths beginning with "cmd/" only match source code in
-// the Go repository.
+// # Package names
 //
-// An import path is a pattern if it includes one or more "..." wildcards,
-// each of which can match any string, including the empty string and
-// strings containing slashes. Such a pattern expands to all packages
-// found in directories matching the pattern, in the case of a
-// file system path pattern, or all packages found in any build list
-// module matching the pattern, otherwise. The "..." wildcard does not
-// cross module boundaries in the case of a file system path pattern.
+// Packages are identified by their import path,
+// a combination of their module name and their relative directory path
+// within the module. Within program, all packages
+// must be identified by a unique import path.
 //
-// To make common patterns more convenient, there are two special cases.
-// First, /... at the end of the pattern can match an empty string,
-// so that net/... matches both net and packages in its subdirectories, like net/http.
-// Second, any slash-separated pattern element containing a wildcard never
-// participates in a match of the "vendor" element in the path of a vendored
-// package, so that ./... does not match packages in subdirectories of
-// ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
-// Note, however, that a directory named vendor that itself contains code
-// is not a vendored package: cmd/vendor would be a command named vendor,
-// and the pattern cmd/... matches it.
-// See https://go.dev/ref/mod#vendoring for more about vendoring or
-// golang.org/s/go15vendor for vendoring in the legacy GOPATH mode.
+// Packages also have names, declared with "package" keyword
+// in a .go file, and used as the identifier when imported
+// by another package. By convention, the names of importable packages
+// match the last element of their import path, generally the name
+// of the directory containing the package.
 //
-// An import path can also name a package to be downloaded from
-// a remote repository. Run 'go help importpath' for details.
+// Package names do not have to be unique within a module,
+// but packages that share the same name can't be imported
+// together without one of them being aliased to a different name.
 //
-// Every package in a program must have a unique import path.
-// Paths without a dot in the first path element are reserved
-// for the standard library, or in the case of 'example' and 'test',
-// are reserved for use in tutorials, examples, and test code.
-// In module mode, all import paths outside of the standard library
-// start with the module path. This means module paths should have
-// a dot in the first element, e.g., 'github.com/user/repo', or
-// 'example.com/project'.
+// As the go command primarily operates on directories,
+// all .go files within a directory (excluding subdirectories)
+// should share the same package declaration.
 //
-// Packages in a program need not have unique package names,
-// but there are two reserved package names with special meaning.
-// The name main indicates a command, not a library.
-// Commands are built into binaries and cannot be imported.
-// The name documentation indicates documentation for
-// a non-Go program in the directory. Files in package documentation
-// are ignored by the go command.
+// There following package names have special meanings:
 //
-// As a special case, if the package list is a list of .go files from a
-// single directory, the command is applied to a single synthesized package
-// named "command-line-arguments" made up of exactly those files.
+// - "main" denotes the top-level package in a stand-alone executable.
+// "main" packages cannot be imported.
 //
-// Directory and file names that begin with "." or "_" are ignored
-// by the go tool, as are directories named "testdata".
+// - "documentation"  indicates documentation for a non-Go program
+// in the directory. Files in package documentation are ignored
+// by the go command.
+//
+// - "_test" suffix in "*_test.go" files. These form a separate test
+// package that only has access to the colocated package's exported
+// identifiers. See "go doc testing" for details.
+//
+// For more information about import paths, see "go help importpath".
 //
 // # Configuration for downloading non-public code
 //
diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go
index 6d60733..78fe1cf 100644
--- a/src/cmd/go/internal/help/helpdoc.go
+++ b/src/cmd/go/internal/help/helpdoc.go
@@ -38,119 +38,159 @@
 
 	go <action> [packages]
 
-Usually, [packages] is a list of import paths.
+Usually, [packages] is a list of package patterns,
+which can take several forms:
 
-An import path that is a rooted path or that begins with
-a . or .. element is interpreted as a file system path and
-denotes the package in that directory.
+- A relative or absolute path to a file system directory
+- An import path
+- A reserved name that expands to a set of packages
+- A list of files
 
-An import path beginning with ./ or ../ is called a relative path.
-A relative path can be used as a shorthand on the command line.
+If no import paths are given, the action applies to the
+package in the current directory.
+
+A pattern contains "..." wildcards elements,
+which is expanded to match 0 or more path elements.
+Specific rules are described below.
+
+File system patterns
+
+Patterns beginning with a file system root like / on Unixes,
+or a volume name like C: on Windows are interpreted as absolute file system paths.
+Patterns beginning with a "." or ".." element are interpreted as relative file system paths.
+File system paths denote the package contained within the given directory.
+
+Relative path can be used as a shorthand on the command line.
 If you are working in the directory containing the code imported as
 "unicode" and want to run the tests for "unicode/utf8", you can type
 "go test ./utf8" instead of needing to specify the full path.
 Similarly, in the reverse situation, "go test .." will test "unicode" from
 the "unicode/utf8" directory. Relative patterns are also allowed, like
-"go test ./..." to test all subdirectories. See 'go help packages' for details
-on the pattern syntax.
+"go test ./..." to test all subdirectories.
 
-Otherwise, the import path P denotes a package found in
-one of the modules in the build list. The "build list" is the
-list of module versions used for a build.
+File system patterns expanded with the "..." wildcard exclude the following:
+
+- Directories named "vendor"
+- Directories named "testdata"
+- Files and directories with names beginning with "_" or "."
+- Directories that contain other go modules
+- Directories matching an ignore directive in a module's go.mod file
+
+These can be included by either using them in the prefix,
+or changing into the directories. For example, "./..." won't
+match a "./testdata/foo" package, but "./testdata/..." will.
+
+Directories containing other go modules can only be matched
+by changing the working directory into module.
+
+Import path patterns
+
+Patterns may be import paths as described in "go help importpath".
+Import path patterns generally describe the packages contained
+in the build list, the set of packages in the current modules'
+dependency graph.
 See https://go.dev/ref/mod#glos-build-list for more details.
 
-If no import paths are given, the action applies to the
-package in the current directory.
+Some commands accept versioned package patterns,
+like: "example.com/my/mod...@v1.2.3"
+These describe the matching package at the given version,
+independent of the versions used by the current module.
 
-There are several reserved names for paths that should not be used
-for packages to be built with the go tool:
+Import path patterns may also use a "..." wildcard,
+like: "example.com/my/module/...".
+This can be combined with the version specifier
+like: "example.com/my/module/...@latest".
 
-- "main" denotes the top-level package in a stand-alone executable.
+Import path pattern expansion with "..." depends on context:
+
+- "prefix/..." matches all packages in the build list that share the prefix,
+  even if they belong to different modules.
+- if "prefix/..." didn't match any packages in the build list,
+  then it only includes packages within the module that contains "prefix".
+
+Reserved names
+
+The following reserved names expand to a set of packages:
 
 - "work" expands to all packages in the main module (or workspace modules).
 
+- "tool" expands to the tools defined in the current module's go.mod file.
+
 - "all" expands to all packages in the main module (or workspace modules) and
 their dependencies, including dependencies needed by tests of any of those. In
 the legacy GOPATH mode, "all" expands to all packages found in all the GOPATH trees.
 
-- "std" is like all but expands to just the packages in the standard
-Go library.
+- "std" epands to all the packages in the standard library
+and their internal libraries.
 
 - "cmd" expands to the Go repository's commands and their
 internal libraries.
 
-- "tool" expands to the tools defined in the current module's go.mod file.
+List of .go files
 
-Package names match against fully-qualified import paths or patterns that
-match against any number of import paths. For instance, "fmt" refers to the
-standard library's package fmt, but "http" alone for package http would not
-match the import path "net/http" from the standard library. Instead, the
-complete import path "net/http" must be used.
+If the pattern is a list of Go files rather than a complete package,
+the go command synthesizes a virtual package named "command-line-arguments"
+containing just the given files. In most cases, it is an error
+to do so (e.g. "go build main.go"). Instead prefer to operate on
+complete packages (directories), like: "go build .".
 
-Import paths beginning with "cmd/" only match source code in
-the Go repository.
+Package names
 
-An import path is a pattern if it includes one or more "..." wildcards,
-each of which can match any string, including the empty string and
-strings containing slashes. Such a pattern expands to all packages
-found in directories matching the pattern, in the case of a
-file system path pattern, or all packages found in any build list
-module matching the pattern, otherwise. The "..." wildcard does not
-cross module boundaries in the case of a file system path pattern.
+Packages are identified by their import path,
+a combination of their module name and their relative directory path
+within the module. Within program, all packages
+must be identified by a unique import path.
 
-To make common patterns more convenient, there are two special cases.
-First, /... at the end of the pattern can match an empty string,
-so that net/... matches both net and packages in its subdirectories, like net/http.
-Second, any slash-separated pattern element containing a wildcard never
-participates in a match of the "vendor" element in the path of a vendored
-package, so that ./... does not match packages in subdirectories of
-./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
-Note, however, that a directory named vendor that itself contains code
-is not a vendored package: cmd/vendor would be a command named vendor,
-and the pattern cmd/... matches it.
-See https://go.dev/ref/mod#vendoring for more about vendoring or
-golang.org/s/go15vendor for vendoring in the legacy GOPATH mode.
+Packages also have names, declared with "package" keyword
+in a .go file, and used as the identifier when imported
+by another package. By convention, the names of importable packages
+match the last element of their import path, generally the name
+of the directory containing the package.
 
-An import path can also name a package to be downloaded from
-a remote repository. Run 'go help importpath' for details.
+Package names do not have to be unique within a module,
+but packages that share the same name can't be imported
+together without one of them being aliased to a different name.
 
-Every package in a program must have a unique import path.
-Paths without a dot in the first path element are reserved
-for the standard library, or in the case of 'example' and 'test',
-are reserved for use in tutorials, examples, and test code.
-In module mode, all import paths outside of the standard library
-start with the module path. This means module paths should have
-a dot in the first element, e.g., 'github.com/user/repo', or
-'example.com/project'.
+As the go command primarily operates on directories,
+all .go files within a directory (excluding subdirectories)
+should share the same package declaration.
 
-Packages in a program need not have unique package names,
-but there are two reserved package names with special meaning.
-The name main indicates a command, not a library.
-Commands are built into binaries and cannot be imported.
-The name documentation indicates documentation for
-a non-Go program in the directory. Files in package documentation
-are ignored by the go command.
+There following package names have special meanings:
 
-As a special case, if the package list is a list of .go files from a
-single directory, the command is applied to a single synthesized package
-named "command-line-arguments" made up of exactly those files.
+- "main" denotes the top-level package in a stand-alone executable.
+"main" packages cannot be imported.
 
-Directory and file names that begin with "." or "_" are ignored
-by the go tool, as are directories named "testdata".
-	`,
+- "documentation"  indicates documentation for a non-Go program
+in the directory. Files in package documentation are ignored
+by the go command.
+
+- "_test" suffix in "*_test.go" files. These form a separate test
+package that only has access to the colocated package's exported
+identifiers. See "go doc testing" for details.
+
+For more information about import paths, see "go help importpath".
+`,
 }
 
 var HelpImportPath = &base.Command{
 	UsageLine: "importpath",
 	Short:     "import path syntax",
 	Long: `
-
-An import path (see 'go help packages') denotes a package stored in the local
-file system. In general, an import path denotes either a standard package (such
-as "unicode/utf8") or a package found in a module (For more
+An import path is used to uniquely identify and locate a package.
+In general, an import path denotes either a standard library package
+(such as "unicode/utf8") or a package found in a module (for more
 details see: 'go help modules').
 
-Internal Packages
+The standard library reserves all import paths without a dot in the
+first element for its packages. See "Fully-qualified import paths"
+below for choosing an import path for your module.
+The following names are reserved to be used as short module names
+when working locally, and in tutorials, examples, and test code.
+
+- "test"
+- "example"
+
+Internal packages
 
 Code in or below a directory named "internal" is importable only
 by code that shares the same import path above the internal directory.
@@ -183,8 +223,26 @@
 Fully-qualified import paths
 
 A fully-qualified import path for a package not belonging to the standard library
-starts with the path of the module the package to which the package belongs. The module's path
-specifies where to obtain the source code for the module.
+starts with the path of the module the package to which the package belongs.
+The module's path specifies where to obtain the source code for the module.
+The complete import path is formed by joining the module path with the
+relative directory path of a package within the module. Example:
+
+    /home/user/modules/m/
+            go.mod                 (declares "module example.com/m")
+            crash/
+                bang/              (importable as "example.com/m/crash/bang")
+                    b.go
+            foo/                   (importable as "example.com/m/foo")
+                f.go
+                bar/               (importable as "example.com/m/foo/bar")
+                    x.go
+
+As import paths without a dot in the first element are reserved by the standard library,
+module paths (which form the prefix of all import paths) should start with an element
+containing a dot, e.g. "github.com/user/repo", or "example.com/project".
+An module path may point directly to a code hosting service,
+or to a custom address that points to the code hosting service in a html meta tags.
 
 Import paths belonging to modules hosted on common code hosting sites have special syntax:

Change information

Files:

• M src/cmd/go/alldocs.go
• M src/cmd/go/internal/help/helpdoc.go

Change size: L

Delta: 2 files changed, 265 insertions(+), 148 deletions(-)

Open in Gerrit

Related details

Attention set is empty

Submit Requirements:

• Code-Review
• No-Unresolved-Comments
• Review-Enforcement
• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: newchange

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 1

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

[Michael Matloob (Gerrit)]

Attention needed from Sean Liao and t hepudds

Michael Matloob added 16 comments

File src/cmd/go/internal/help/helpdoc.go

Line 44, Patchset 1 (Latest):- A relative or absolute path to a file system directory
- An import path

Michael Matloob . unresolved

These two are different than the other two, and I think we should mention that they can contain `...` upfront.

Line 52, Patchset 1 (Latest):A pattern contains "..." wildcards elements,

Michael Matloob . unresolved

can contain?

Line 63, Patchset 1 (Latest):Relative path can be used as a shorthand on the command line.

Michael Matloob . unresolved

`Relative paths`?

Line 76, Patchset 1 (Latest):- Directories that contain other go modules

Michael Matloob . unresolved

I think we should explicitly mention that these are directories that contain `go.mod` files

Line 90, Patchset 1 (Latest):in the build list, the set of packages in the current modules'
dependency graph.

Michael Matloob . unresolved

the build list is a set of modules at the specific versions used in the build. I also think the original is easier to read broken up into two sentences

Line 95, Patchset 1 (Latest):like: "example.com/my/mod...@v1.2.3"

Michael Matloob . unresolved

`such as`? (and for the ones below?)

Line 106, Patchset 1 (Latest):- "prefix/..." matches all packages in the build list that share the prefix,

Michael Matloob . unresolved

`packages in modules in the build list`?

Line 108, Patchset 1 (Latest):- if "prefix/..." didn't match any packages in the build list,


then it only includes packages within the module that contains "prefix".

Michael Matloob . unresolved

I'm not sure if I understand this. It matches packages in modules in the build list

Line 123, Patchset 1 (Latest):- "std" epands to all the packages in the standard library

Michael Matloob . unresolved

expands

Line 134, Patchset 1 (Latest):to do so (e.g. "go build main.go"). Instead prefer to operate on

Michael Matloob . unresolved

main.go does imply that there are other files in the package but I think we could spell it out more to readers of the documentation?

Line 140, Patchset 1 (Latest):a combination of their module name and their relative directory path

Michael Matloob . unresolved

this is a little weird because of the standard library. should we add them as a separate case?

Line 141, Patchset 1 (Latest):within the module. Within program, all packages

Michael Matloob . unresolved

`Within a program`?

Line 144, Patchset 1 (Latest):Packages also have names, declared with "package" keyword

Michael Matloob . unresolved

Nice! I'm glad we're explaining the name distinction here!

Line 144, Patchset 1 (Latest):Packages also have names, declared with "package" keyword

Michael Matloob . unresolved

`the "package" keyword`

Line 156, Patchset 1 (Latest):should share the same package declaration.

Michael Matloob . unresolved

I think we should mention that some test files can have a _test path up here before we get to the bullet point?

Line 242, Patchset 1 (Latest):module paths (which form the prefix of all import paths) should start with an element


containing a dot, e.g. "github.com/user/repo", or "example.com/project".

Michael Matloob . unresolved

Should we mention `test` and `example` here?

Open in Gerrit

Related details

Attention is currently required from:

• Sean Liao
• t hepudds

Submit Requirements:

• Code-Review

• No-Unresolved-Comments

• Review-Enforcement
• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: comment

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 1

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: t hepudds <thepud...@gmail.com>

Gerrit-CC: Alan Donovan <adon...@google.com>

Gerrit-Attention: Sean Liao <se...@liao.dev>

Gerrit-Attention: t hepudds <thepud...@gmail.com>

Gerrit-Comment-Date: Mon, 09 Mar 2026 18:50:06 +0000

Gerrit-HasComments: Yes

Gerrit-Has-Labels: No

[Sean Liao (Gerrit)]

Attention needed from Michael Matloob and t hepudds

Sean Liao added 3 comments

File src/cmd/go/internal/help/helpdoc.go

Line 90, Patchset 1 (Latest):in the build list, the set of packages in the current modules'
dependency graph.

Michael Matloob . unresolved

the build list is a set of modules at the specific versions used in the build. I also think the original is easier to read broken up into two sentences

Sean Liao

I wasn't sure about using "modules" when it's barely been explained in this doc how they relate to packages?

Line 134, Patchset 1 (Latest):to do so (e.g. "go build main.go"). Instead prefer to operate on

Michael Matloob . unresolved

main.go does imply that there are other files in the package but I think we could spell it out more to readers of the documentation?

Sean Liao

Even if main.go was the only file, the command-line-arguments mode is weird in that the binary doesn't carry module information, or vcs, etc.
I was going more for just discouraging any use of this mode?

Line 140, Patchset 1 (Latest):a combination of their module name and their relative directory path

Michael Matloob . unresolved

this is a little weird because of the standard library. should we add them as a separate case?

Sean Liao

Do we say that the standard library doesn't use a module prefix?

Open in Gerrit

Related details

Attention is currently required from:

• Michael Matloob
• t hepudds

Submit Requirements:

• Code-Review
• No-Unresolved-Comments
• Review-Enforcement
• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: comment

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 1

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: t hepudds <thepud...@gmail.com>

Gerrit-CC: Alan Donovan <adon...@google.com>

Gerrit-Attention: Michael Matloob <mat...@golang.org>

Gerrit-Attention: t hepudds <thepud...@gmail.com>

Gerrit-Comment-Date: Mon, 09 Mar 2026 19:34:18 +0000

Gerrit-HasComments: Yes

Gerrit-Has-Labels: No

Comment-In-Reply-To: Michael Matloob <mat...@golang.org>

[Sean Liao (Gerrit)]

Attention needed from Michael Matloob and t hepudds

Sean Liao uploaded new patchset

Sean Liao uploaded patch set #2 to this change.

Following approvals got outdated and were removed:

• TryBots-Pass: LUCI-TryBot-Result-1 by Go LUCI

Open in Gerrit

Related details

Attention is currently required from:

• Michael Matloob
• t hepudds

Submit Requirements:

• Code-Review
• No-Unresolved-Comments
• Review-Enforcement
• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: newpatchset

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 2

[Sean Liao (Gerrit)]

Attention needed from Michael Matloob, Sean Liao and t hepudds

Sean Liao uploaded new patchset

Sean Liao uploaded patch set #3 to this change.

Open in Gerrit

Related details

Attention is currently required from:

• Michael Matloob
• Sean Liao
• t hepudds

Submit Requirements:

• Code-Review
• No-Unresolved-Comments
• Review-Enforcement
• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: newpatchset

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 3

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: t hepudds <thepud...@gmail.com>

Gerrit-CC: Alan Donovan <adon...@google.com>

Gerrit-Attention: Michael Matloob <mat...@golang.org>

[Sean Liao (Gerrit)]

Attention needed from Michael Matloob and t hepudds

Sean Liao added 15 comments

File src/cmd/go/internal/help/helpdoc.go

Line 44, Patchset 1:- A relative or absolute path to a file system directory
- An import path

Michael Matloob . resolved

These two are different than the other two, and I think we should mention that they can contain `...` upfront.

Sean Liao

Done

Line 52, Patchset 1:A pattern contains "..." wildcards elements,

Michael Matloob . resolved

can contain?

Sean Liao

Done

Line 63, Patchset 1:Relative path can be used as a shorthand on the command line.

Michael Matloob . resolved

`Relative paths`?

Sean Liao

Done

Line 76, Patchset 1:- Directories that contain other go modules

Michael Matloob . resolved

I think we should explicitly mention that these are directories that contain `go.mod` files

Sean Liao

Done

Line 90, Patchset 1:in the build list, the set of packages in the current modules'
dependency graph.

Michael Matloob . resolved

the build list is a set of modules at the specific versions used in the build. I also think the original is easier to read broken up into two sentences

Sean Liao

I wasn't sure about using "modules" when it's barely been explained in this doc how they relate to packages?

Sean Liao

Done

Line 95, Patchset 1:like: "example.com/my/mod...@v1.2.3"

Michael Matloob . resolved

`such as`? (and for the ones below?)

Sean Liao

Done

Line 106, Patchset 1:- "prefix/..." matches all packages in the build list that share the prefix,

Michael Matloob . resolved

`packages in modules in the build list`?

Sean Liao

Done

Line 108, Patchset 1:- if "prefix/..." didn't match any packages in the build list,


then it only includes packages within the module that contains "prefix".

Michael Matloob . unresolved

I'm not sure if I understand this. It matches packages in modules in the build list

Sean Liao

I was going for what happens if you did something like: `go install example.com/mod/cmd/...@latest`
but you had something like `cmd/foo` carved out into its own module

Line 123, Patchset 1:- "std" epands to all the packages in the standard library

Michael Matloob . resolved

expands

Sean Liao

Done

Line 140, Patchset 1:a combination of their module name and their relative directory path

Michael Matloob . resolved

this is a little weird because of the standard library. should we add them as a separate case?

Sean Liao

Do we say that the standard library doesn't use a module prefix?

Sean Liao

Done

Line 141, Patchset 1:within the module. Within program, all packages

Michael Matloob . resolved

`Within a program`?

Sean Liao

Done

Line 144, Patchset 1:Packages also have names, declared with "package" keyword

Michael Matloob . resolved

Nice! I'm glad we're explaining the name distinction here!

Sean Liao

Acknowledged

Line 144, Patchset 1:Packages also have names, declared with "package" keyword

Michael Matloob . resolved

`the "package" keyword`

Sean Liao

Done

Line 156, Patchset 1:should share the same package declaration.

Michael Matloob . resolved

I think we should mention that some test files can have a _test path up here before we get to the bullet point?

Sean Liao

Done

Line 242, Patchset 1:module paths (which form the prefix of all import paths) should start with an element


containing a dot, e.g. "github.com/user/repo", or "example.com/project".

Michael Matloob . resolved

Should we mention `test` and `example` here?

Sean Liao

Done

Open in Gerrit

Related details

Attention is currently required from:

• Michael Matloob
• t hepudds

Submit Requirements:

• Code-Review
• No-Unresolved-Comments
• Review-Enforcement
• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: comment

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 3

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: t hepudds <thepud...@gmail.com>

Gerrit-CC: Alan Donovan <adon...@google.com>

Gerrit-Attention: Michael Matloob <mat...@golang.org>

Gerrit-Attention: t hepudds <thepud...@gmail.com>

Gerrit-Comment-Date: Wed, 11 Mar 2026 19:13:42 +0000

Gerrit-HasComments: Yes

Gerrit-Has-Labels: No

Comment-In-Reply-To: Michael Matloob <mat...@golang.org>

Comment-In-Reply-To: Sean Liao <se...@liao.dev>

[Michael Matloob (Gerrit)]

Attention needed from Sean Liao and t hepudds

Michael Matloob voted and added 2 comments

Votes added by Michael Matloob

Code-Review

+2

2 comments

File src/cmd/go/internal/help/helpdoc.go

Line 108, Patchset 1:- if "prefix/..." didn't match any packages in the build list,
then it only includes packages within the module that contains "prefix".

Michael Matloob . unresolved

I'm not sure if I understand this. It matches packages in modules in the build list

Sean Liao

I was going for what happens if you did something like: `go install example.com/mod/cmd/...@latest`
but you had something like `cmd/foo` carved out into its own module

Michael Matloob

Could we say something like "if there is a version specifier such as ..."?

Line 134, Patchset 1:to do so (e.g. "go build main.go"). Instead prefer to operate on

Michael Matloob . resolved

main.go does imply that there are other files in the package but I think we could spell it out more to readers of the documentation?

Sean Liao

Even if main.go was the only file, the command-line-arguments mode is weird in that the binary doesn't carry module information, or vcs, etc.
I was going more for just discouraging any use of this mode?

Michael Matloob

Done

Open in Gerrit

Related details

Attention is currently required from:

• Sean Liao
• t hepudds

Submit Requirements:

• Code-Review

• No-Unresolved-Comments
• Review-Enforcement

• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: comment

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 3

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: t hepudds <thepud...@gmail.com>

Gerrit-CC: Alan Donovan <adon...@google.com>

Gerrit-Attention: Sean Liao <se...@liao.dev>

Gerrit-Attention: t hepudds <thepud...@gmail.com>

Gerrit-Comment-Date: Tue, 17 Mar 2026 20:14:54 +0000

Gerrit-HasComments: Yes

Gerrit-Has-Labels: Yes

[Sean Liao (Gerrit)]

Attention needed from Sean Liao and t hepudds

Sean Liao uploaded new patchset

Sean Liao uploaded patch set #4 to this change.

Following approvals got outdated and were removed:

• TryBots-Pass: LUCI-TryBot-Result+1 by Go LUCI

Open in Gerrit

Related details

Attention is currently required from:

• Sean Liao
• t hepudds

Submit Requirements:

• Code-Review
• No-Unresolved-Comments
• Review-Enforcement

• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: newpatchset

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 4

[Sean Liao (Gerrit)]

Attention needed from t hepudds

Sean Liao added 1 comment

File src/cmd/go/internal/help/helpdoc.go

Line 108, Patchset 1:- if "prefix/..." didn't match any packages in the build list,
then it only includes packages within the module that contains "prefix".

Michael Matloob . resolved

I'm not sure if I understand this. It matches packages in modules in the build list

Sean Liao

I was going for what happens if you did something like: `go install example.com/mod/cmd/...@latest`
but you had something like `cmd/foo` carved out into its own module

Michael Matloob

Could we say something like "if there is a version specifier such as ..."?

Sean Liao

Done

Open in Gerrit

Related details

Attention is currently required from:

• t hepudds

Submit Requirements:

• Code-Review
• No-Unresolved-Comments

• Review-Enforcement
• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: comment

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 4

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: t hepudds <thepud...@gmail.com>

Gerrit-CC: Alan Donovan <adon...@google.com>

Gerrit-Attention: t hepudds <thepud...@gmail.com>

Gerrit-Comment-Date: Wed, 18 Mar 2026 21:54:56 +0000

Gerrit-HasComments: Yes

Gerrit-Has-Labels: No

[Dmitri Shuralyov (Gerrit)]

Attention needed from Sean Liao and t hepudds

Dmitri Shuralyov voted Code-Review+1

Code-Review

+1

Open in Gerrit

Related details

Attention is currently required from:

• Sean Liao
• t hepudds

Submit Requirements:

• Code-Review
• No-Unresolved-Comments
• Review-Enforcement

• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: comment

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 4

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Dmitri Shuralyov <dmit...@google.com>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: t hepudds <thepud...@gmail.com>

Gerrit-CC: Alan Donovan <adon...@google.com>

Gerrit-CC: Dmitri Shuralyov <dmit...@golang.org>

Gerrit-Attention: Sean Liao <se...@liao.dev>

Gerrit-Attention: t hepudds <thepud...@gmail.com>

Gerrit-Comment-Date: Thu, 19 Mar 2026 21:18:47 +0000

Gerrit-HasComments: No

Gerrit-Has-Labels: Yes

[Michael Matloob (Gerrit)]

Attention needed from Sean Liao and t hepudds

Michael Matloob voted Code-Review+1

Code-Review

+1

Open in Gerrit

Related details

Attention is currently required from:

• Sean Liao
• t hepudds

Submit Requirements:

• Code-Review
• No-Unresolved-Comments

• Review-Enforcement
• TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

Gerrit-MessageType: comment

Gerrit-Project: go

Gerrit-Branch: master

Gerrit-Change-Id: I45190c70a0e8698c52fbc06252045f278ff3f1a5

Gerrit-Change-Number: 752261

Gerrit-PatchSet: 4

Gerrit-Owner: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: Dmitri Shuralyov <dmit...@google.com>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>

Gerrit-Reviewer: Michael Matloob <mat...@google.com>

Gerrit-Reviewer: Sean Liao <se...@liao.dev>

Gerrit-Reviewer: t hepudds <thepud...@gmail.com>

Gerrit-CC: Alan Donovan <adon...@google.com>

Gerrit-CC: Dmitri Shuralyov <dmit...@golang.org>

Gerrit-Attention: Sean Liao <se...@liao.dev>

Gerrit-Attention: t hepudds <thepud...@gmail.com>

Gerrit-Comment-Date: Thu, 19 Mar 2026 21:19:49 +0000

Gerrit-HasComments: No

Gerrit-Has-Labels: Yes