x/website: outdated info about workspace and modules?

[mindplay-dk]

The Getting Started page talks about setting up your workspace:

Check that Go is installed correctly by setting up a workspace and building a simple program, as follows.

Create your workspace directory, %USERPROFILE%\go. (If you'd like to use a different directory, you will need to set the GOPATH environment variable.)

It links to the "Workspaces" section in How To Write Go Code, which explains a number of things:

Go programmers typically keep all their Go code in a single workspace.

Do they still do that today?

Note that this differs from other programming environments in which every project has a separate workspace and workspaces are closely tied to version control repositories.

Is that still true?

These pages explain how to set up your workspace and GOPATH, etc. - how to create your first program and library in the workspace, how to install packages, and so on.

Modules and go mod are never even mentioned.

The Go 1.11 release notes stated:

Using modules, developers are no longer confined to working inside GOPATH, version dependency information is explicit yet lightweight, and builds are more reliable and reproducible.

That sounds great. Why isn't this the prescribed way to get started?

I found a useful introduction to go modules on this website, but (beyond the 1.11 announcement post) I haven't really seen modules mentioned or promoted anywhere on the official website.

With support for modules proper, it seems like this should be the preferred approach - the role of the global workspace should be reduced to global installations of tools and so forth, as is the case with most common package managers for other languages? (npm, etc.)

When the official documentation tells me that Go programmers "typically" keep all their Go code in a single workspace, that makes me feel insecure about even learning about modules.

Is a single, global workspace still the preferred/recommended approach?

Or why aren't you promoting the use of modules?

[ALTree]

Thanks for reporting this.

but (beyond the 1.11 announcement post) I haven't really seen modules mentioned or promoted anywhere on the official website.

Not completely true: There is a 4-parts series of posts about Go Modules on the project's website (first instalment: https://blog.golang.org/using-go-modules, with links to the other three).

Obviously the fact that you didn't know this suggests there's a "discoverability" issue somewhere.

Besides this, it's true that much of the documentation still needs to be updated to reflect changes in the way Go code is written after the introduction of modules.

• A general tracking issue is doc: restructure module documentation #33637 (doc: restructure module documentation)
• An issue specifically about updating "How to Write Go Code" is website: Update "How to Write Go Code" with go modules #28215 (website: Update "How to Write Go Code" with go modules)

A rewrite of "How to write Go code" is in progress at CL 199417; and you can follow the changes linked at the bottom in #33637 for an overview of the general progress being made.

Overall, the questions you raise here are valid, but the work needed to update the documentation is already being tracked in other issues (#33637 is the main one), so I think we can close this thread in favour of the older ones.

[ghost]

R. Schultz

Online repositories including .deb and .rpm packages tend to use /usr/share/gocode as a directory to locate Golang sub-repositories, though these sometimes may place compiled executables outside of the Golang prescribed subdirectory structure for a Go path directory.

bash-4.3$ go version
go version go1.13.3 linux/386
bash-4.3$ go help gopath | head -n7
The Go path is used to resolve import statements.
It is implemented by and documented in the go/build package.

The GOPATH environment variable lists places to look for Go code.
On Unix, the value is a colon-separated string.
On Windows, the value is a semicolon-separated string.
On Plan 9, the value is a list.
bash-4.3$ 

The value is unset, but a default is encoded in the go compiler.

($HOME/go on Unix, %USERPROFILE%\go on Windows, and $home/go on Plan 9)

To set on Unix-like a custom GOPATH, one can use shell builtins, export and setenv, respectively of bash and tcsh, entered in any of user customisation files, within an active shell session, or sourced via shell scripts.

If a Golang sub-repository is to be downloaded locally which depends on a sub-repository already installed globally note the ordering in the colon-separated string

bash-4.3$ go help gopath | head -n61 | tail -n3
Go searches each directory listed in GOPATH to find source code,
but new packages are always downloaded into the first directory
in the list.
bash-4.3$ 

The Windows NT kernel introduced multiple user-accounts and Vista added UAC, but I don't see for example C:\gocode being used for Golang sub-repositories to be installed globally.

As it stands on Plan 9 coders only use $home/go in their GOPATH.

bash-4.3$ go help gopath | grep modules | head -n1
When using modules, GOPATH is no longer used for resolving imports.
bash-4.3$   

Try also typing go help modules.

A. Donizetti

Any resolution regarding (as I framed it) discouraging editing by non-contributors of certain wiki pages?

I noticed the Modules page has two edits this November.

[dmitshur]

/cc @jayconrod @jadekler

[jayconrod]

We should do a pass through the installation instructions and any other new user docs and updating things for modules. Just a quick note on documentation in progress though:

@jadekler has an open CL to rewrite How to Write Go Code for modules. See CL 199417. That should land pretty soon.

I'm working on module reference documentation (#33637), which will be available at golang.org/ref/modules, linked from golang.org/doc. That will launch with Go 1.14 and should supercede a lot of existing reference information, both on the wiki and in go help (though neither will disappear in the short term).

@jadekler and @tbpg have written a series of blog posts on modules, linked from golang.org/doc/#Modules. These are intended to be introductory guides.

[ghost]

The OP mentioned "Workspaces" and J. Conrad cites a code.html rewrite.

For convenience, add the workspace's bin subdirectory to your PATH:

Maybe - though this is off topic - the following could be added (beneath the preceding quote).

Plan 9 configuration is usually done at the beginning of $home/lib/profile.

bind -a $home/go/bin /bin

For PowerShell/PowerShell ISE add for example $Env:Path += ";~\go\bin" in the relevant file below.

profile.ps1
Microsoft.PowerShell_profile.ps1
Microsoft.PowerShellISE_profile.ps1

NB: M. Klement's Gist (Out-FileUtf8NoBom.ps1) might be of interest.

[ghost]

there's no anchor #Modules

under golang.org/doc/#articles

could be added in the Modules section

Go Modules: v2 and Beyond

[dmitshur]

could be added in the Modules section

Go Modules: v2 and Beyond

That has already been done in CL 209038, and you can see it on tip.golang.org. It will show up on golang.org the next time the website is deployed.

[sprive]

Similar to @mindplay-dk's issue... except while his focus was on module locations and workflow, my issue is simply discontinuity or differences between pages under Documents section.

The Documents has this index

1. Getting Started
   1. NOTE: this has you work inside $HOME/go/ - explicitly stated so.
2. Tour of Go
   1. (No issue. Just mentioned for index completeness.)
3. How to write Go code. (A few issues here...)
   1. Text does not explicitly designate any working directory. So one assumes it is still "$HOME/go/" from "Getting Started"
   2. The "How to Write" text has you begin with amkdir hello... which fails, because you will be in $HOME/go/, from Getting Started, above (and there's already a "hello" dir).
   3. Since we're talking about 2 code dirs named "hello", then perhaps (and this is regardless of the working directory) it would be good to call the "How to write" version hello2?
   4. After we've created the directory, typed in the code code, then we bump into the git init example code block, which reveals we were actually working in /home/user/hello/

These bumps are easy to work around if you know you can work in any directory.
But if you're new to Go, and reading the doc pages "in order", it leaves you questioning if you skipped over text.

[ghost]

Getting Started

Test your installation

this section uses %USERPROFILE%\go\src\hello (Windows)

How to Write Go Code

Your first program

this section would infer %USERPROFILE%\go\src\github.com\sprive\hello (Windows)

[sprive]

@apparluk Agree/+1 to this correction to my statement.

[sprive]

IN "How to Write Go Code", it is not made clear why the module name github.com/user/hello was named as such.

Coming from Python or another language, you would never see what appears to be a DNS FQDN in the package name - so the first viewing of this raises some interesting questions:

(Note: I am not using this space to ask these questions - please don't answer as such. I am pointing out that these were questions raised and unanswered, by reading "How to Write Go Code" )

1. Question: Are we certain there is no relationship between this code, and a project hosted on github.com?
   1. (Answer: "foobar" could replace "github.com" if you wanted. Experimenting with the code makes this clear. It's just a directory name).
2. Question: Is it a Go convention to sometimes use a domain name as the module name?
   1. (Answer: Apparently "yes" however one should not mistake this for a URL or link. As this naming concept is just being introduced here, a few words would help, and maybe link to a Reference page. Or if a simpler module name could be used, then this aspect of module naming could be deferred).

(To clarify, I've already "answered" these questions to myself by plowing past them and using Google. How can we avoid leaving the reader with unanswered questions, when introducing new concepts? Also, if something I've said here is inaccurate or misleading, feel free to restate my question and answer)

[jayconrod]

@sprive Thanks for the feedback, this is helpful. Agree that How to Write Go Code should explain module paths and directories a bit more.

One thing to point out though: working in $HOME/go works fine with modules and is still a useful way to organize code. It's a strong convention in the Go ecosystem, and in the interest of having a concrete directory to work in in tutorials, we continued to use that. We should clarify in these articles that this is just a suggestion, and any directory will work though.

This is a point of confusion for now because before Go 1.13, by default, module mode was never enabled within $GOPATH. That was changed so that module mode is enabled whenever a go.mod file is present in the current directory or in any parent directory. We thought about including this in the rewrite of How to Write Go Code but dropped it in the interest of concision.

[ghost]

@sprive

cf: GH hosted repos for Go code

note the install location

obviously one would only run rm -rf ~/go if factually one wanted to recursively delete that directory

https://github.com/golang/text

bash-4.3$ export PATH=/usr/local/go/bin:${PATH}
bash-4.3$ rm -rf ~/go
bash-4.3$ mkdir ~/go
bash-4.3$ go get -u golang.org/x/text
bash-4.3$ tree -L 4 ~/go
/home/eric/go
|-- pkg
|   `-- linux_386
|       `-- golang.org
|           `-- x
`-- src
    `-- golang.org
        `-- x
            `-- text

8 directories, 0 files
bash-4.3$ 

https://github.com/golang/protobuf

bash-4.3$ export PATH=/usr/local/go/bin:${PATH}
bash-4.3$ rm -rf ~/go
bash-4.3$ mkdir ~/go
bash-4.3$ go get -u github.com/golang/protobuf/protoc-gen-go
bash-4.3$ tree -L 5 ~/go
/home/eric/go
|-- bin
|   `-- protoc-gen-go
`-- src
    `-- github.com
        `-- golang
            `-- protobuf
                |-- AUTHORS
                |-- CONTRIBUTORS
                |-- LICENSE
                |-- Makefile
                |-- README.md
                |-- descriptor
                |-- go.mod
                |-- go.sum
                |-- jsonpb
                |-- proto
                |-- protoc-gen-go
                |-- ptypes
                `-- regenerate.sh

10 directories, 9 files
bash-4.3$ 

https://github.com/gonum/gonum

$GOPATH/src/gonum.org/v1/gonum

[seankhliao]

The doc now promotes modules as the primary workflow.