Skip to content
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

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

Closed
bradfitz opened this issue Jan 31, 2019 · 13 comments

Comments

@bradfitz
Copy link
Member

commented Jan 31, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Feb 6, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Feb 12, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Feb 13, 2019

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.

@rsc rsc modified the milestones: Proposal, Go1.13 Feb 13, 2019

@gopherbot

This comment has been minimized.

Copy link

commented Feb 13, 2019

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 pushed a commit that referenced this issue Feb 13, 2019
doc/go1.12: note that Go 1.12 is the last release to include godoc
Updates #30029

Change-Id: I88e09035d675e7a6855ada0262eb42636c9822cc
Reviewed-on: https://go-review.googlesource.com/c/162417
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@gopherbot

This comment has been minimized.

Copy link

commented Feb 13, 2019

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

gopherbot pushed a commit that referenced this issue Feb 14, 2019
[release-branch.go1.12] doc/go1.12: note that Go 1.12 is the last rel…
…ease to include godoc

Updates #30029

Change-Id: I88e09035d675e7a6855ada0262eb42636c9822cc
Reviewed-on: https://go-review.googlesource.com/c/162417
Reviewed-by: Andrew Bonventre <andybons@golang.org>
(cherry picked from commit 7cf31d8)
Reviewed-on: https://go-review.googlesource.com/c/162557
nebulabox added a commit to nebulabox/go that referenced this issue Feb 18, 2019
doc/go1.12: note that Go 1.12 is the last release to include godoc
Updates golang#30029

Change-Id: I88e09035d675e7a6855ada0262eb42636c9822cc
Reviewed-on: https://go-review.googlesource.com/c/162417
Reviewed-by: Andrew Bonventre <andybons@golang.org>
nebulabox added a commit to nebulabox/go that referenced this issue Feb 20, 2019
doc/go1.12: note that Go 1.12 is the last release to include godoc
Updates golang#30029

Change-Id: I88e09035d675e7a6855ada0262eb42636c9822cc
Reviewed-on: https://go-review.googlesource.com/c/162417
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@spagettikod

This comment has been minimized.

Copy link

commented Apr 1, 2019

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

This comment has been minimized.

Copy link

commented Apr 1, 2019

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

This comment has been minimized.

Copy link
Member

commented Apr 1, 2019

@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

This comment has been minimized.

Copy link

commented Apr 2, 2019

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

This comment has been minimized.

Copy link
Member

commented Apr 2, 2019

@spagettikod You should be aware of #29206 (comment). 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

This comment has been minimized.

Copy link

commented Apr 13, 2019

@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

This comment has been minimized.

Copy link

commented Apr 29, 2019

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

@gopherbot

This comment has been minimized.

Copy link

commented Jun 17, 2019

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

gopherbot pushed a commit that referenced this issue Jun 21, 2019
doc: add release notes for godoc and go doc
Updates #30029
Updates #31457

Change-Id: I08414a544615e74afb47f7a10a00f1e22adfd40c
Reviewed-on: https://go-review.googlesource.com/c/go/+/182619
Reviewed-by: Katie Hockman <katie@golang.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.