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.

[posener]

@julieqiu

There is a type in the instructions: (redundant/missing double-quotes) in GOPROXY=“https://proxy.golang.org GO111MODULE=on go get example.com/my/module@v1.0.0

Also - I think it is better to replace @v1.0.0 with @latest.

Also - for the first way of adding the entry: https://proxy.golang.org/example.com/my/module/@v/v1.0.0.info, it is not clear that it should be curled, and when trying it with my own repo I get 404 - is it expected when the repo is not yet in pkg.go.dev?

Also - what about my proposal that go.dev will do it for the developer? I still don't understand why the developer needs to manually add it (see #37005 (comment)).

Thanks!

[julieqiu]

@posener - thanks for catching the typo and for the suggestion. We will fix it and add additional instructions for downloading the latest version of a module.

Also - for the first way of adding the entry: https://proxy.golang.org/example.com/my/module/@v/v1.0.0.info, it is not clear that it should be curled, and when trying it with my own repo I get 404 - is it expected when the repo is not yet in pkg.go.dev?

What repo are you trying to fetch and what URL did you visit?

Also - what about my proposal that go.dev will do it for the developer? I still don't understand why the developer needs to manually add it (see #37005 (comment)).

I mentioned in #37005 (comment) that we are planning to support #37106 and #37002. Is your proposal different from #37002? If so, could you please file a new issue?

[posener]

Great,

• x/pkgsite: support Refresh now like godoc.org #37106 looks like the 404 I got.
• x/pkgsite: automatically fetch a requested package if it does not exist on pkg.go.dev #37002 seems to address my proposal :-)

Until they those issues are addressed, I think that the current instructions are still not good enough. What does "making a request" mean - how to do it, and what to expect in the returned response.

Thanks!