gopls/doc: move contents of golang/go#36899 to documentation
This change adds a workspace.md file that explains the different ways
of configuring your workspace with gopls. Ultimately, I think we should
move this to the user.md documentation, but I didn't want to deal with
merge conflicts from my other CL, so moving it here to start.
Trust: Rebecca Stambler <firstname.lastname@example.org>
Run-TryBot: Rebecca Stambler <email@example.com>
gopls-CI: kokoro <firstname.lastname@example.org>
TryBot-Result: Go Bot <email@example.com>
Reviewed-by: Robert Findley <firstname.lastname@example.org>
diff --git a/gopls/doc/workspace.md b/gopls/doc/workspace.md
new file mode 100644
@@ -0,0 +1,75 @@
+# Setting up your workspace
+`gopls` supports both Go module and GOPATH modes. However, it needs a defined
+scope in which language features like references, rename, and implementation
+The following options are available for configuring this scope:
+## Module mode
+### One module
+If you are working with a single module, you can open the module root (the
+directory containing the `go.mod` file), a subdirectory within the module,
+or a parent directory containing the module.
+**Note**: If you open a parent directory containing a module, it must **only**
+contain that single module. Otherwise, you are working with multiple modules.
+### Multiple modules
+As of Jan 2020, if you are working with multiple modules, you will need to
+create a "workspace folder" for each module. This means that each module has
+its own scope, and features will not work across modules. We are currently
+working on addressing this limitation--see details about
+[experimental workspace module mode](#experimental-workspace-module-mode)
+In VS Code, you can create a workspace folder by setting up a
+View the [documentation for your editor plugin](user.md#editor) to learn how to
+configure a workspace folder in your editor.
+#### Workspace module (experimental)
+Many `gopls` users would like to work with multiple modules at the same time
+specifically, have features that work across modules. We plan to add support
+for this via a concept called the "workspace module", which is described in
+[this design document](https://github.com/golang/proposal/blob/master/design/37720-gopls-workspaces.md).
+This feature works by creating a temporary module that requires all of your
+workspace modules, meaning all of their dependencies must be compatible.
+The workspace module feature is currently available as an opt-in experiment,
+and it will allow you to work with multiple modules without creating workspace
+folders for each module. You can try it out by configuring the
+setting. If you try it and encounter issues, please
+[report them](https://github.com/golang/go/issues/new) so we can address them
+before the feature is enabled by default.
+You can follow our progress on the workspace module work by looking at the
+open issues in the
+### GOPATH mode
+When opening a directory within your GOPATH, the workspace scope will be just
+### At your own risk
+Some users or companies may have projects that encompass one `$GOPATH`. If you
+open your entire `$GOPATH` or `$GOPATH/src` folder, the workspace scope will be
+your entire `GOPATH`. If your GOPATH is large, `gopls` to be very slow to start
+because it will try to find all of the Go files in the directory you have
+opened. It will then load all of the files it has found.
+To work around this case, you can create a new `$GOPATH` that contains only the
+packages you want to work on.
+If you have additional use cases that are not mentioned above, please
+[file a new issue](https://github.com/golang/go/issues/new).