Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cmd/go: workspace documentation is uninformative #51301

Closed
robpike opened this issue Feb 21, 2022 · 6 comments
Closed

cmd/go: workspace documentation is uninformative #51301

robpike opened this issue Feb 21, 2022 · 6 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. release-blocker
Milestone

Comments

@robpike
Copy link
Contributor

robpike commented Feb 21, 2022

The new workspace feature looks like a great thing, but the only helpful documentation is the design doc. The output from go help is barely rudimentary.

Look at where we start:

% go help work
Go workspace provides access to operations on workspaces.

Note that support for workspaces is built into many other commands,
not just 'go work'.

See 'go help modules' for information about Go's module system of
which workspaces are a part.

A workspace is specified by a go.work file that specifies a set of
module directories with the "use" directive. These modules are used
as root modules by the go command for builds and related operations.
A workspace that does not specify modules to be used cannot be used
to do builds from local modules.

To determine whether the go command is operating in workspace mode,
use the "go env GOWORK" command. This will specify the workspace
file being used.

Usage:

	go work <command> [arguments]

The commands are:

	edit        edit go.work from tools or scripts
	init        initialize workspace file
	sync        sync workspace build list to modules
	use         add modules to workspace file

Use "go help work <command>" for more information about a command.

It doesn't even say what a workspace is. It does kinda say how to make one, and hints at what it means, but it's just not good enough. The final sentence of the one substantive paragraph is unintelligible out of context.

What do they do? Why do I want one? Can I have more than one? What defines a workspace? etc. etc. The second sentence says they are so important they are implemented all over the place. What does that even mean and is it relevant?

The tip to go help modules is probably necessary but contains no direct information about workspaces and is itself a huge topic.

The individual commands add little:

% go help work use
usage: go work use [-r] [moddirs]

Use provides a command-line interface for adding directories,
optionally recursively, to a go.work file.

The -r flag searches recursively for modules in the argument directories.
% 

From the go help output alone I cannot understand this feature, what it is, what it solves, whether I should use it or not, and how to use it. Such an important new feature needs proper documentation support in the help system.

@ianlancetaylor
Copy link
Contributor

CC @matloob @bcmills

@ianlancetaylor ianlancetaylor added this to the Go1.18 milestone Feb 21, 2022
@ianlancetaylor ianlancetaylor added NeedsFix The path to resolution is known, but the work has not been done. release-blocker labels Feb 21, 2022
@rsc
Copy link
Contributor

rsc commented Feb 22, 2022

@matloob is still working on workspace documentation

@bcmills
Copy link
Contributor

bcmills commented Feb 22, 2022

@matloob is still working on workspace documentation

That's on me at the moment, I think‌ — I still owe him a review on CL 383854.

@matloob
Copy link
Contributor

matloob commented Mar 4, 2022

Hi, we now have a tutorial at https://go.dev/doc/tutorial/workspaces in addition to the reference documentation in https://go.dev/ref/mod#workspaces. I've submitted a CL (that will be cherry picked onto 1.18 and provides links to both of those docs from go help work.

@dmitshur
Copy link
Contributor

dmitshur commented Mar 7, 2022

The aforementioned CL has now been cherry-picked to release-branch.go1.18 via CL 389914 (commit 0b38b02).

@matloob
Copy link
Contributor

matloob commented Mar 9, 2022

I'm hoping that the workspace documentation improvements we've made address the sense that the documentation is uninformative.

Our plan with go command documentation is to have the website be the primary source of documentation rather than the command. So it's intentional that most of the documentation is on the website, and the go command documentation focuses only on the individual commands rather than workspaces as a whole.

If the documentation on the website is confusing or incomplete, we would definitely want to improve it.

@matloob matloob closed this as completed Mar 9, 2022
@rsc rsc unassigned matloob Jun 22, 2022
@golang golang locked and limited conversation to collaborators Jun 22, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. release-blocker
Projects
None yet
Development

No branches or pull requests

7 participants