Docs on pkg.go are from 2018 (and docs for other packages are also out of date)

[zot]

Location

https://pkg.go.dev/github.com/libp2p/go-libp2p

Description

The godoc docs are up to date: https://godoc.org/github.com/libp2p/go-libp2p

but pkg.go points to old ones: https://pkg.go.dev/github.com/libp2p/go-libp2p

Here are some other libp2p projects that have the same problem on pkg.go:

• go-libp2p-autonat at pkg.go the ones at godoc.org
• go-libp2p-discovery at pkg.go the ones at godoc.org
• go-libp2p-relay at pkg.go (404) the ones at godoc.org
• go-libp2p-circuit at pkg.go (404) the ones at godoc.org

[Jorropo]

Yes that a known issue see golang/go#34189 the best you can do is put a thumbs up on this issue.

For short some day an error was made and a major release was release, the go proxy downloaded this thinking that a brand new release and never forget it since it.
So pkg.go uses that old wrong cache and take the biggest number.

[marten-seemann]

Shouldn't that have been fixed with Go 1.14?

[Jorropo]

@marten-seemann maybe not sure, thx I wasn't knowing something was planned.
Edit:
After few reading, yes, just need to wait 1.14

[zot]

I got an email from the folks at pkg.dev that might have some useful info about versioning:

Hi Bill,
We'd like to help.

I just visited https://pkg.go.dev/mod/github.com/libp2p/go-libp2p-autonat and saw that the latest version, according to us, is v0.1.1.

I then went to the repo, https://github.com/libp2p/go-libp2p-autonat, and indeed the latest tag is v0.1.1. That is behind master, however, and I think that's what your issue is.

As you know, the big difference between pkg.go.dev and godoc.org is that the former is module-aware, and that means it understands versions. pkg.go.dev's concept of "latest" is "highest release version," because we want to show the latest stable version of a package by default.

• If you feel your current master is stable, all you need to do is tag it (you can use a patch bump, v0.1.2, if there are no API changes), and then "go get" it so the proxy sees it.

• If you want to see the doc at master, we'll soon support "pkgname@master" URLs, so you can do that. But they won't be the default: we'll keep that as it is.

[Stebalien]

That's a separate issue (we need to cut a release of go-libp2p-autonat).

• go-libp2p-relay was renamed to go-libp2p-circuit.
• go-libp2p-circuit works fine.

[Stebalien]

Closing as there's nothing we can really do about this.

[zot]

What about talking to the go-doc team? I've found them to be very helpful and I'm sure they'd be willing to make changes to their code if they really need to.

I just checked and it's still showing the 2018 docs here: https://pkg.go.dev/github.com/libp2p/go-libp2p?tab=doc

Since that's the standard place Go programmers look for package docs, I think it's worth making sure they're correct.