x/pkgsite: ?tab=doc is added automatically

[arp242]

I've been using pkg.go.dev pretty much exclusively for the last few weeks for both stdlib packages and external ones; overall, it works well without major problems 👍

There is one small annoyance I've noticed though: it automatically adds ?tab=doc

The way I generally use this is by typing pkg in my browser's URL bar; this autofills to https://pkg.go.dev/ and I can now type or paste the package name; great!

But the automatic adding of ?tab=doc means that typing, say, net means it'll be autofilled to https://pkg.go.dev/net?tab=doc. I need to remove the query string to go to, say, net/http, instead of just being able to type http.

I understand why this query string was added, and it's a minor annoyance, but for me at least, the experience would be improved by treating the lack of a query string as if ?tab=doc was added, instead of doing a 302 redirect to the ?tab=doc variant.

[toothrot]

/cc @julieqiu

[ghost]

The ?tab=doc detracts from the readability of links where the URL is displayed.

The Gophers Slack is an example of where people are posting ?tab=doc URLs. The godoc.org URLs are more readable in that context.

[aofei]

I tried pkg.go.dev for a few days. I found that I was used to editing the address bar directly to switch between packages. So this automatically added ?tab=doc does seem a bit annoying.

The doc is now the default value for the tab query. Maybe pkg.go.dev should go one step further and hide it when it's the default. Please consider it.

/cc @julieqiu one more time. 🍉

[andybons]

@aofei please don't /cc someone again if they're already on the issue (especially one that's only a week old). We take great care to look into every issue we receive and it all takes time to triage and respond. Thanks.

[julieqiu]

We're currently discussing this request with our UX team, along with other design feedback we've received for the site. We want to review design feedback we have received as part of a broader redesign, as opposed to make piecemeal decisions. I'll update this issue once we have decided on any changes.

/cc @fflewddur

[arp242]

I just noticed that if a package contains no documentation but subdirectories, it loads the that tab without changing the URL btw; for example: https://pkg.go.dev/text/

Not sure if this is an oversight or intentional?

[peterbourgon]

I second all of the comments here on principally aesthetic grounds, but would also add that the Doc, Overview, Subdirectories, etc. of a module are clearly hierarchical resources of the path and as such shouldn't be specified as a query parameter.

[toothrot]

@peterbourgon I don't agree that they are clearly hierarchical in the scope of this URL. Additionally, what would happen if a module included a doc, overview, or subdirectories nested module or sub-directory?

[peterbourgon]

@toothrot

I don't agree that they are clearly hierarchical in the scope of this URL.

Doc doesn't make semantic sense outside of the context of a specific module, so it's hierarchical. (c.f., e.g., a search query, ?q=search+text, which doesn't necessarily have this restriction.)

Additionally, what would happen if a module included a doc, overview, or subdirectories nested module or sub-directory?

GitHub, for example, reserves the first layer of the path after the repo identifier for its tokens. If you want to access the subdir e.g. /xyz it's necessarily underneath a /blob/master/xyz or /branch/abc/xyz etc. subtree. So that's an approach. Perhaps other code hosting sites with clean URLs could be reviewed and suitable prior art unearthed.

[toothrot]

@peterbourgon GitHub can do that because they control the structure of repos: it's always github.com/{{user}}/{{repo}}. For modules, that is not the case. There is no way by looking at a path to know whether you are at the root of a module. GitHub also sacrifices the ability to link into the repo without specifying a query of /blob/master. Other code hosting sites make a similar sacrifice, such as on Gerrit: with host.googlesource.com/repo/+/refs/heads/master/README. Again, this is only possible if you know the root of your tree.

We're open to suggestions, and believe me we have done the effort you suggested of considering patterns on other sites. This is the best we have come up with so far. If you have a reasonable suggestion that accounts for these constraints, we'd love to consider it.

[peterbourgon]

@toothrot

There is no way by looking at a path to know whether you are at the root of a module.

By the path alone, no, but pkg.go.dev has enough additional information to know if a path represents the root of a module.

GitHub also sacrifices the ability to link into the repo without specifying a query of /blob/master

I think I'd be OK with pkg.go.dev having a similar restriction and URL structure. For example:

• pkg.go.dev/github.com/peterbourgon/ff
  Overview of all major versions
• pkg.go.dev/github.com/peterbourgon/ff/version/v{0,1,2,...}
  Redirect to latest specific version of specified major version
• pkg.go.dev/github.com/peterbourgon/ff/version/v3.0.0
  Overview including docs of specific version
• pkg.go.dev/github.com/peterbourgon/ff/version/v3.0.0/ffcli
  Overview of subpackage at a specific version

Possibilities are many. To be clear, what I'm after here are clean URLs. I'm happy with any approach that gets me there :)

edit: if it would be useful, I could make a stab at defining complete clean URL structure for current pkg.go.dev resources — would that be worthwhile, or just annoying?

[toothrot]

@toothrot

There is no way by looking at a path to know whether you are at the root of a module.

By the path alone, no, but pkg.go.dev has enough additional information to know if a path represents the root of a module.

I would argue that the point of having a clean URL is that it is user predictable, not just predictable because we have a database of modules to query, or possibly fetch at runtime. The value is lost, to me, if a user has to think about it. Our current query parameter may not be aesthetically pleasing to everyone, but it is very predictable to omit and be redirected to.

GitHub also sacrifices the ability to link into the repo without specifying a query of /blob/master

I think I'd be OK with pkg.go.dev having a similar restriction and URL structure. For example:

• pkg.go.dev/github.com/peterbourgon/ff Overview of all major versions
• pkg.go.dev/github.com/peterbourgon/ff/version/v{0,1,2,...} Redirect to latest specific version of specified major version
• pkg.go.dev/github.com/peterbourgon/ff/version/v3.0.0 Overview including docs of specific version
• pkg.go.dev/github.com/peterbourgon/ff/version/v3.0.0/ffcli Overview of subpackage at a specific version

Possibilities are many. To be clear, what I'm after here are clean URLs. I'm happy with any approach that gets me there :)

We want the same thing (clean, predictable URLs)! I appreciate the thought you're putting into this.

I have a couple other examples to throw in the mix:

• golang.org/x/build/maintner/cmd/maintserve (a nested module of pkg.go.dev/golang.org/x/build)
• rsc.io/quote
• errors (standard library)
• rsc.io/[email protected] (using the module syntax for versions)

edit: if it would be useful, I could make a stab at defining complete clean URL structure for current pkg.go.dev resources — would that be worthwhile, or just annoying?

I think it is worthwhile, but again, the most important thing to me is user predictability, not just a hierarchy that we can enforce in software.

Funny story from this weekend that's very relevant to you: I was mentioning github.com/go-kit/kit/log to someone in Slack, which turned it into a link. Even though that is the most precise way to refer to that package in Go, it is a 404 due to GitHub's URL structure. I like that this works in our current design on pkg.go.dev, and would love for our URL design to be compatible with Go's import paths.

[peterbourgon]

@toothrot

I'll give it a shot, including your examples, and we'll see if something emerges 👍

Even though that is the most precise way to refer to that package in Go, it is a 404 due to GitHub's URL structure. I like that this works in our current design on pkg.go.dev, and would love for our URL design to be compatible with Go's import path

I would argue that this "working" on pkg.go.dev is actually a bug, or at least not desirable. Go modules' SIV dictates that the un-versioned github.com/go-kit/kit identifier resolves to latest of the v0 or v1 major versions, but — IMO here — that's a sort of convenience, or sugar. The truth of the matter is that all resources in a module necessarily exist at, or under, a specific version, and therefore github.com/go-kit/kit/log should really 301 or whatever to the actual, explicit, permanent resource github.com/go-kit/kit/version/v0.10.0/log.

[FiloSottile]

As much as I dislike ?tab=doc, it's only an aesthetic concern. GitHub paths where I can't just paste a filesystem path regularly cause me friction, and I strongly value the ability of typing pkg.go.dev/IMPORT_PATH.

(I do think tab= leaks a presentation concern, so I would suggest ?overview, ?versions, etc. with the default omitted, so we get clean URLs for docs. I think it would be a great color for the bike shed.)

[peterbourgon]

I strongly value the ability of typing pkg.go.dev/IMPORT_PATH

+1 — I just think it should 301 to the explicit version the path resolves to, if that would enable better clean URLs.

[dmitshur]

@peterbourgon Issue #38429 may be related.

[prashantv]

As I mentioned in #40550, editing the address bar is much more painful to do a simple operation like go to a subpackage.

I think it's important to drop the ?tab=doc but also keep the pkg.go.dev/IMPORT for similar typability.

[gopherbot]

Change https://golang.org/cl/254745 mentions this issue: internal/frontend: remove tab=doc query param

[julieqiu]

Thanks for all the feedback, everyone. We're going to drop the ?tab=doc query param.

Moving forward, requests to pkg.go.dev/<path>?tab=doc will redirect to pkg.go.dev/<path> and requests to pkg.go.dev/<path> will stay there.