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

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

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

Comments

Projects
None yet
4 participants
@rsc
Copy link
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

@rsc rsc assigned adg Dec 9, 2014

@aclements

This comment has been minimized.

Copy link
Member

aclements commented Dec 10, 2014

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

This comment has been minimized.

Copy link
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

This comment has been minimized.

Copy link
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 added a commit that referenced this issue Dec 16, 2014

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>
@aclements

This comment has been minimized.

Copy link
Member

aclements commented Dec 16, 2014

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

This comment has been minimized.

Copy link
Member

aclements commented Dec 16, 2014

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

This comment has been minimized.

Copy link
Contributor

adg commented Feb 23, 2015

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

@rsc

This comment has been minimized.

Copy link
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

This comment has been minimized.

Copy link

gopherbot commented Apr 25, 2015

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

@rsc rsc modified the milestones: Go1.6, Go1.5 Aug 5, 2015

@rsc

This comment has been minimized.

Copy link
Contributor

rsc commented Jan 6, 2016

ping @adg. can we get this in?

@gopherbot gopherbot closed this in 1abb863 Jan 12, 2016

@golang golang 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.