x/website: install from source directions use all.bash which can be problematic/confusing

[danp]

The trouble in #76072 possibly came from the install from source documentation using all.bash which runs tests that may be flaky in some environments.

In the Gophers slack #performance thread there was some surprise from @mknyszek and @jakebailey that the documentation uses all.bash here instead of make.bash.

Should that be changed?

[danp]

I sent CL 717040 and @thepudds encouraged me to open this issue for discussion.

[gopherbot]

Change https://go.dev/cl/717040 mentions this issue: _content/doc/install: prefer make.bash for source install

[gabyhelp]

Related Issues

• doc: document that developers working in the go repo should run 'go test' #29266 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[thepudds]

Some different categories of people who might land on the install from source page might include:

1. people who want to do a git clone for a variety of reasons (philosophical reasons, or because they want to then make a code modification, or because they are on an atypical platform, or some less common situation like some distro package maintainer who might not be innately familiar with Go, or many other reasons...)
2. people who just want to try something out on master as easily as possible.
3. people who were looking for the standard binary downloads.
4. other people.

To help the people in category 3, the Install from Source page already leads off with (ephasis added):

This topic describes how to build and run Go from source code. To install with an installer, see Download and install.

And just in case people were not paying attention, the page doubles-down on that ~2 paragraphs later with:

This document explains how to check out the sources, build them on your own machine, and run them.
Most users don't need to do this, and will instead install from precompiled binary packages as described in Download and install, a much simpler process.

---

To help the people in category 2 ("I just want to try something out on master as easily as possible"), I wonder if it would be better to instead mention gotip as an option.

If you just want to try something out, I think gotip is more convenient in practice than make.bash to get started, and then later having gotip still in your path is also very convenient (compared to juggling multiple go binaries in your path), and gotip works to download CLs as well, which can be helpful when asking someone to confirm an issue can be closed, etc.

---

For the people in category 1 ("I want to do a git clone), I think it's not terrible for them to start out with all.bash over make.bash.

This helps them start with a baseline of correctness, which is helpful in part because some people are in this category for some atypical reason.

For ~first time contributors, I think it is also better for them to start with all.bash (including some people clearly send contributions without ever having run all.bash locally, even after their change).

To help someone doing all.bash based on the instructions on this page, though, perhaps the page could add a reminder along the lines of:

"If you see a failure with all.bash, please search for the error messages in the issue tracker to see if it is a known issue."

For people who are cloning the source, I do think the Go project is better off with a bug report of:

"Here's an odd error from all.bash...."

compared to:

"Here's an odd error from go test ./my-private-package, sorry I can't share the source code..."

... which can be the result if someone clones the source and just runs make.bash when all.bash would have failed, if they had run it.

Or better yet, no bug report at all if the error from all.bash is already in an issue that someone is able to find on their own (e.g., perhaps based on watchflakes having already captured it).

And if someone is doing all.bash many times, it seems people in practice do eventually learn that make.bash is an option.

---

In any event, sorry for the long comment.

The short version is there is some value to the ordering on the page as it stands today. Maybe it does makes sense to swap it around exactly as done in https://go.dev/cl/717040, but I thought it worth at least some brief discussion first.

[seankhliao]

I think all.bash should still be recommended over make.bash.
being able to build the go command doesn't necessarily mean it or the programs it builds will run correctly, and it's usually better to catch those early.

[thepudds]

There was a follow-up to this issue in Gopher slack earlier today, where the person who filed issue #76142 (which was seemingly the proximate cause for this issue here being opened) explained that they actually were just looking for binaries, but they happened to land on build from source instructions, and as a result they seemingly thought build from source was the proper way to get binaries. (And then they hit an issue, and filed #76142).

Maybe an alternate change would be to have a new section at the top of the install from source directions that is more prominent, including with its own header (and without trying to pick specific language right now), where the header would be something along the lines of “Before you begin” or “Choosing the most suitable approach” or "What approach is best for me", or similar, with ~3 clear / concise bullets in that top section for the 3 main cases:

• pre-built binaries, or
• gotip, or
• continuing with the build from source instructions.

And try to steer people more clearly to the best option for them.

Or something like that.

(That third bullet could also be a spot to include a concise reminder to search for a known issue on GitHub if they see a test fail with all.bash, and at least consider briefly mention fallbacks like trying again after disabling cgo, or mention option to fall back to make.bash).

[findleyr]

Hi, we discussed this CL while missing the relevant discussion here. We think that the current proposed change is a strict improvement, given how flaky all.bash can be. (as a point of reference, I think most people on the team prefer make.bash over all.bash when building Go from source).

Can we merge the CL, and continue discussion here about how other documentation could be improved?