doc: $GOPATH is opaque even if you find the doc #9228

Closed
rsc opened this Issue Dec 9, 2014 · 9 comments

Projects

None yet

4 participants

@rsc
Contributor
rsc commented Dec 9, 2014

Rick and Austin both ran into problems with trying to set up $GOPATH. They both found https://golang.org/doc/code.html but it didn't help either of them. Perhaps the doc should start out more prescriptive and only then move into the description of what a workspace is.

Also, the recipe given uses $HOME/go as $GOPATH, which is just about the worst possible suggestion, because it's where we tell people to check out Go trees in http://golang.org/doc/install/source. This doc should probably use $HOME/work. People will be able to figure out how to generalize to other values of 'work'.

It looks like all the necessary information is in the doc, it's just too hard to find if you're skimming trying to solve a problem. Maybe there should be a short intro that hits the highlights:

(1) mkdir $HOME/work; export GOPATH=$HOME/work; export PATH=$GOPATH/bin:$PATH
(2) Your own work goes in $GOPATH/src/github.com/you/project. Your version control applies to that subdirectory tree, not to all of $GOPATH.

and then the rest of the doc can elaborate.

@adg @aclements @rlh

@rsc rsc added the documentation label Dec 9, 2014
@adg adg was assigned by rsc Dec 9, 2014
@aclements
Member

Expanding on (2), it would be helpful to directly dispel reader's preconceptions. I got tripped up by where to put different Go projects because I was thinking in a traditional model where each project has a separate and unrelated top-level workspace directory and that's what you put under version control. It would have helped me if the document explicitly said something like "Typically, there is just one Go workspace shared by all Go projects (everything that you 'go get' and everything you start yourself)."

@adg
Contributor
adg commented Dec 16, 2014

@aclements the 'how to write go code' doc says:

A typical workspace would contain many source repositories containing many
packages and commands. Most Go programmers keep all their Go source code
and dependencies in a single workspace.

@adg
Contributor
adg commented Dec 16, 2014

Sent https://go-review.googlesource.com/1577 to use $HOME/work instead of $HOME/go as the proposed $GOPATH.

@adg adg added a commit that referenced this issue Dec 16, 2014
@adg adg doc: propose $GOPATH as $HOME/work, not $HOME/go
Related to issue #9228

Change-Id: I0819e657f6393788754d1412f9c2126a170d4cf1
Reviewed-on: https://go-review.googlesource.com/1577
Reviewed-by: Rob Pike <r@golang.org>
8655f04
@aclements
Member

On Mon, Dec 15, 2014 at 8:15 PM, Andrew Gerrand notifications@github.com
wrote:

@aclements https://github.com/aclements the 'how to write go code doc'
says:

A typical workspace would contain many source repositories containing many
packages and commands. Most Go programmers keep all their Go source code
and dependencies in a single workspace.

When I read this I was thinking "but how do I version control separate
projects if they're all in one workspace?" because I was still equating
repositories and workspaces. Go is fairly unique in not equating these
and I think this document should be more explicit about this.

Looking back at the document now I see one ".git" nested in the workspace
that hints at this, but this is really too subtle. There's also some
discussion of this under "remote packages", but at the time I was
interested in how to lay out my projects, not remote packages.

@aclements
Member

In fact, I actually have notes from when I read this document that capture
exactly what my interpretation (and mental context) were at the time:

This is fine if I'm just working with one code tree, but what's the
intended layout if I'm working on multiple projects? Presumably not that I
keep them all in one source tree, since that would conflict with source
control. Where do I put tools that I go get like godoc? A few simple
pointers on multi-workspace setups would be helpful.

Of course, now I understand that the single workspace layout doesn't
conflict with source control because workspace != repository and you don't
need multiple workspaces. But I think it was this initial confusion that
led me to a much more complicated and non-standard workspace setup.

@adg
Contributor
adg commented Feb 23, 2015

I sent a change to add a Quick Start section to code.html.

@rsc
Contributor
rsc commented Apr 10, 2015

Pending CL just needs to be finished.

@rsc rsc added this to the Go1.5 milestone Apr 10, 2015
@gopherbot

CL https://golang.org/cl/5561 mentions this issue.

@rsc rsc modified the milestone: Go1.6, Go1.5 Aug 5, 2015
@rsc
Contributor
rsc commented Jan 6, 2016

ping @adg. can we get this in?

@gopherbot gopherbot pushed a commit that closed this issue Jan 12, 2016
@adg adg doc: add Overview and other small edits to How To Write Go Code
Fixes #9228

Change-Id: Ic4df4a39f6f363bdd6eb9228c8164e6e9dccee1b
Reviewed-on: https://go-review.googlesource.com/5561
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Austin Clements <austin@google.com>
1abb863
@gopherbot gopherbot closed this in 1abb863 Jan 12, 2016
@gopherbot gopherbot locked and limited conversation to collaborators Jan 13, 2017
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.