Go: proposal: x/build/cmd/release: remove godoc for Go 1.13

[bradfitz]

Split out of #27151 (reduce download sizes), this proposal is to remove godoc (the webserver) from Go 1.13 releases and document that users can go get it instead.

As of Go 1.12, godoc is only a webserver and go doc is the CLI tool.

/cc @dmitshur

[rsc]

I am skeptical about removing batteries like godoc from the go distribution.
People who want to be able to view HTML versions of docs and the spec and other things that are already in-tree should be able to do that, no?

If anything, I think we should be having discussions about what tools are _missing_ from the go distribution, like goimports.

[bradfitz]

I suspect few users use godoc's HTML mode, though. People are always shocked to hear that it's possible or that I use it. As a user of it myself, I'd be fine with it being go get-able if it means smaller downloads.

[rsc]

We discussed this some more. A lot of us use godoc to view package docs and the spec locally but we suspect very few users do. Let's try deleting godoc from cmd/release now, it will be dropped from Go 1.13 beta, and we'll see if we get pushback then.

[gopherbot]

Change https://golang.org/cl/162417 mentions this issue: doc/go1.12: note that Go 1.12 is the last release to include godoc

[gopherbot]

Change https://golang.org/cl/162557 mentions this issue: [release-branch.go1.12] doc/go1.12: note that Go 1.12 is the last release to include godoc

[spagettikod]

Maybe it's only me but I start the web server before starting my editor.

I preach about Go when ever I get a chance and one of the selling points is that all you need to do to get started is to install the binary, start the web server and all you need is there on your machine to start learning Go.

When having to use Java I download the API docs to always have it available. With Go it's so great to have everything in one package, while a go get... is not hard it's still one more thing to do.

I'm all for removing clutter but I think easy access to the documentation should come with the binary. To me it's not clutter.

If it’s underused maybe it should be more prominent in the getting started section? Or maybe have godoc start the web server at 6060 instead of having to use flags?

[spagettikod]

Just to see how long it takes I just downloaded the latest MacOS binary and it took me 8 seconds. I don't know how much I would save by loosing the web server but even if I had a slower connection I wouldn't consider a 4-5 minute download a long time.

But then again maybe I'm just old when considering a 4 minute download as "fast"... :)

[dmitshur]

@spagettikod Thanks for feedback.

One of the bigger motivations for making it available primarily via go get is to detach the release frequency of the godoc binary from the Go releases. When the godoc binary is included in the release, we can only update it once every 6 months, but when it's available via go get, we can release new versions at a different frequency.

When I talked about this issue with @ianthehat, he made a good point that we've only considered two extremes in this proposal so far: to include vs not include the godoc binary in the distribution. However, there are other in-between options we may want to consider. For example, the Google Cloud SDK distribution includes idea of components that can be installed/uninstalled or updated at a custom frequency. See https://cloud.google.com/sdk/gcloud/reference/components/. Another source of inspiration could be the golang.org/dl/goX.Y.Z and golang.org/dl/gotip commands that are able to download a part of themselves on demand.

It would be a bigger change to design and implement (and should be a separate proposal), but perhaps a similar solution can provide a better experience to Go users (e.g., they can conveniently choose whether to have the godoc component installed, and we can provide updates at a custom frequency).

[spagettikod]

Thanks for considering my feedback @dmitshur!

I didn't realize that godoc changed between releases, at least not what I consider the most central sections:

• Installing Go
• Learning Go
• References

I looked at the Google Cloud link but I don't see the difference between that and what you already get usinggo get, as I see it go get allows you to install and update existing packages. If you meant an additional "component tool" should be introduced, I feel that, if not kept very strict regarding what components would be allowed, might open a Pandora's box that might lead to not knowing what was actually installed and not knowing if members of a team had the same components.

Anyway I don't mind the possibility of updating the docs provided in the release using go get or that godoc would check for updates when it starts. But I would mind not having the easy access the web server provides to the essential documentation included in the release. I consider godoc and its server an important differentiator to other programing environments and, to me, fells very much like the Go-way of doing things. It would be like a Linux command without a man-page.

[dmitshur]

@spagettikod You should be aware of https://github.com/golang/go/issues/29206#issuecomment-446832422. The current plan is to make godoc just an HTML documentation server. The rest of the golang.org website content would be the responsibility of the golangorg binary (which is what serves golang.org today).

[spagettikod]

@dmitshur Sorry for the late follow up, I didn't realize there was a new comment.

Does that mean that godoc would still be included in the binary to serve the things I mention in my previous comment and not as a separate download?

[gopherbot]

Change https://golang.org/cl/174322 mentions this issue: cmd/release: don't include godoc in releases in Go 1.13+

[gopherbot]

Change https://golang.org/cl/182619 mentions this issue: doc: add release notes for godoc and go doc