go.dev: go.dev/about instructions to add package to the docs need clarification

[natefinch]

These instructions on go.dev/about for adding a package to the docs are not actionable:

To add a package or module, simply fetch it from proxy.golang.org.

I don't know what "fetch it from proxy.golang.org" means or how to go about doing that. I'm sure I'm not the only one.

Also, avoid putting "simply" or "just" in directions, because they trivialize a step which may actually not be trivial for the person attempting it. Like, me, trying to figure out how to fetch something from a go proxy. Remove the word and it reads exactly the same, except if I don't know how to do it, I don't feel like I've been talked down to.

[dmitshur]

/cc @julieqiu

[hunterloftis]

I just ran into the same issue. After a little googling, my best guess about how to "simply fetch it from proxy.golang.org" is:

GO111MODULE=on go get {package}@latest

I don't know whether that's accurate or not. Whatever the solution, I agree @natefinch it should just be spelled out at https://go.dev/about#adding-a-package

[dtitov]

The best confirmation of the fact that this step is really not obvious is that I had the same question and, by googling, I ended up here. So +1 to the issue.

[posener]

+1 for improving the instructions. I ran the command which I understand from the instructions and this issue:

$ GOPROXY=https://proxy.golang.org GO111MODULE=on go get github.com/posener/compare@latest
go: github.com/posener/compare latest => v0.0.1

But it stil does not appear in go.dev: https://pkg.go.dev/search?q=posener%2Fcompare says "No results found".

[posener]

OK, it took it a couple of minutes. I suggest adding in the instructions that the update is not immediate.

[julieqiu]

Agreed - we are working with the broader go.dev team to update the about section, and add more detailed instructions with examples to the about page.

We are also working on supporting #37106. In the meantime, if you don’t see a package on pkg.go.dev, you can add it by:

Making a request to proxy.golang.org for the module version

• https://proxy.golang.org/<module>/@latest
• https://proxy.golang.org/<module>/@v/<version>.info
• For github.com/posener/compare, for example:
  • https://proxy.golang.org/github.com/posener/compare/@latest
  • https://proxy.golang.org/github.com/posener/compare/@v/v0.0.1.info

Downloading the package via the go command

• $ GOPROXY=https://proxy.golang.org GO111MODULE=on go get <package>
• Example: go.dev: go.dev/about instructions to add package to the docs need clarification #37005 (comment)

/cc @pearring @spf13 @fflewddur

[posener]

Any reason that is not being added automatically? I mean, instead of showing the not found page, why wouldn't the server make the above calls and update itself?

[dtitov]

@posener, I assume it's done like that in order to prevent DoS-like misuse: if one would constantly issue requests to non-existing packages, then the server would need to issue a lot of "update" attempts in its turn which may lead to some bad consequences.

[posener]

There are solutions for that, such as rate limiting the internal calls to update the index.

[julieqiu]

https://go.dev/about has been updated.

We plan to make this experience better by supporting #37106 and #37002 in the future.