Go: x/pkgsite: support viewing a package @master

[myitcv]

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/moby/moby/client?tab=doc

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.66 Safari/537.36

Screenshot

What did you do?

Visited the aforementioned link.

What did you expect to see?

The current docs for github.com/moby/moby/client, like on godoc:

https://godoc.org/github.com/docker/docker/client

(notice https://github.com/docker/docker redirects to https://github.com/moby/moby)

What did you see instead?

Per the screenshot, at the time of writing, docs for v1.13.1, which was tagged on Feb 8, 2017.

The godoc version is looking at ~master at any given moment in time.

The current advice from the project maintainers is to use master of this package/module:

• https://github.com/moby/moby/issues/40185#issuecomment-568483750
• https://github.com/moby/moby/issues/40235

Hence only godoc.org works as a means of viewing "current" docs for github.com/moby/moby/client.

[julieqiu]

We're actively working on designing a better flow, but the workaround for this right now is to do the following:

1. Get the semantic version from proxy.golang.org using the .info endpoint. For example:
   https://proxy.golang.org/github.com/moby/moby/@v/master.info currently shows:

{
    "Version": "v1.4.2-0.20200128034134-2ebaeef943cc",
    "Time": "2020-01-28T03:41:34Z"
}

Note. This will also automatically fetch the module for the proxy and populate it on pkg.go.dev, if it does not already exist (per instructions at https://go.dev/about#adding-a-package). It may take a minute or two for the package to appear on pkg.go.dev, if it is not already there.

1. Visit pkg.go.dev/<import-path>@<semantic-version> for the package documentation, in this case:
   https://pkg.go.dev/github.com/moby/moby/[email protected].

We know that this isn't the best user experience, and are working on a better workflow.

[mewmew]

We know that this isn't the best user experience, and are working on a better workflow.

How about a "Fetch latest version from master" link added to the bottom of pages on pkg.go.dev in similar fashion to the "Refresh now" link of godoc.org?

This is issue #37106

[hugelgupf]

Hey Julie, do you have any updates on the progress? This is a major blocker for us (u-root) to go.dev :( Thanks!

[julieqiu]

@hugelgupf thanks for letting us know! We deprioritized this feature temporarily to work on open sourcing (#36747) and with our product/UX teams to address UX issues. I don't have an exact timeline on when this feature will be ready, but we are aiming for within the next month or so.

Out of curiosity, does the workaround in https://github.com/golang/go/issues/36811#issuecomment-579404726 work for your use case (aside from the suboptimal user experience)?

[gopherbot]

Change https://golang.org/cl/240457 mentions this issue: internal/frontend: add fetch endpoint to robots.txt

[gopherbot]

Change https://golang.org/cl/240459 mentions this issue: content: update frontend fetch UI

[gopherbot]

Change https://golang.org/cl/240613 mentions this issue: internal/postgres: support requests for master version in GetPathInfo

[gopherbot]

Change https://golang.org/cl/240682 mentions this issue: internal/frontend: return 400 on @master requests for stdlib paths

[gopherbot]

Change https://golang.org/cl/240945 mentions this issue: internal/frontend: fix serveDetails for master version and latest error

[gopherbot]

Change https://golang.org/cl/240946 mentions this issue: internal/testing/integration: add TestFrontendFetchForMasterVersion

[gopherbot]

Change https://golang.org/cl/242358 mentions this issue: internal/frontend: fix typo in logic for when to fetch path@master

[gopherbot]

Change https://golang.org/cl/242437 mentions this issue: migrations: set not-null constraint on version_map.go_mod_path

[gopherbot]

Change https://golang.org/cl/242458 mentions this issue: internal/frontend: return 303 for alternative modules

[gopherbot]

Change https://golang.org/cl/245120 mentions this issue: internal/testing/integration: add test cases to TestFrontendFetchAtMasterVersion

[gopherbot]

Change https://golang.org/cl/244601 mentions this issue: internal/frontend: refetch paths that previously 404ed

[gopherbot]

Change https://golang.org/cl/245121 mentions this issue: internal/frontend: fix timeout error from checkForPath

[gopherbot]

Change https://golang.org/cl/245021 mentions this issue: internal/frontend: delete s.fetchModule

[gopherbot]

Change https://golang.org/cl/245020 mentions this issue: internal/frontend: use StatusNotFoundInVersionMap for frontend fetch

[gopherbot]

Change https://golang.org/cl/245437 mentions this issue: content: alphabetize classes with prefix Fetch

[gopherbot]

Change https://golang.org/cl/245402 mentions this issue: internal/worker: don't delete 40x results from version_map

[gopherbot]

Change https://golang.org/cl/245401 mentions this issue: content: center text in h3.FetchMessage

[gopherbot]

Change https://golang.org/cl/245640 mentions this issue: internal/frontend: tweak response text for fetch requests

[gopherbot]

Change https://golang.org/cl/245646 mentions this issue: content: update text in fetch.tmpl for 404s

[julieqiu]

You can now view a package at master using the URL, https://pkg.go.dev/<path>@master. For example, https://pkg.go.dev/github.com/moby/moby/client@master.

[SamWhited]

Are there limits to this? With the exception of the example you posted, none of the common packages I use appear to work. They all use vanity URLs, so maybe this has something to do with it?

[julieqiu]

@SamWhited - mind sharing what they are? I can look into it.

[SamWhited]

@julieqiu here are two of mine that appear to be exhibiting this behavior: https://pkg.go.dev/code.soquee.net/otp@master or https://pkg.go.dev/mellium.im/xmpp@master

[SamWhited]

Oh, apparently I have to "request" them or it 404s? I hadn't visited the actual page to click the link. I don't know what that means, but it's confusing

[julieqiu]

The reason is because code.soquee.net/otp@master and mellium.im/xmpp@master weren't in our database yet. In the future, visiting these pages will automatically refresh master.

Feel free to file a new issue with any UI suggestions.

[hugelgupf]

Hi @julieqiu,

a lot of repositories are now moving to renaming their default branches to main. It seems that master is hard-coded in pkgsite. Would it be possible to support some kind of magic version string that gets the default branch, whatever it may be named? This may end up being the reason that I move some of my repos back to master, which I'd like to avoid.

Let me know if I should open another issue for this.

Thanks!

[myitcv]

@hugelgupf - this issue is closed. Please open a new issue.

FWIW the means by which git can determine the default remote (origin in this case) branch looks like this:

git remote set-head origin -a

which then updates the following:

$ cat .git/refs/remotes/origin/HEAD
ref: refs/remotes/origin/main

[anacrolix]

In my experience, this only seems fixed for vanity URLs. More general module names don't work, like https://pkg.go.dev/github.com/anacrolix/torrent@master.