Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: ?tab=doc is added automatically #37351

Open
arp242 opened this issue Feb 21, 2020 · 16 comments
Open

x/pkgsite: ?tab=doc is added automatically #37351

arp242 opened this issue Feb 21, 2020 · 16 comments

Comments

@arp242
Copy link

@arp242 arp242 commented Feb 21, 2020

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.

@gopherbot gopherbot added this to the Unreleased milestone Feb 21, 2020
@gopherbot gopherbot added the pkgsite label Feb 21, 2020
@toothrot
Copy link
Contributor

@toothrot toothrot commented Feb 21, 2020

/cc @julieqiu

@ghost
Copy link

@ghost ghost commented Feb 26, 2020

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
Copy link
Contributor

@aofei aofei commented Feb 27, 2020

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
Copy link
Member

@andybons andybons commented Feb 27, 2020

@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
Copy link
Contributor

@julieqiu julieqiu commented Feb 28, 2020

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
Copy link
Author

@arp242 arp242 commented Apr 1, 2020

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
Copy link
Member

@peterbourgon peterbourgon commented Apr 20, 2020

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
Copy link
Contributor

@toothrot toothrot commented Apr 20, 2020

@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
Copy link
Member

@peterbourgon peterbourgon commented Apr 21, 2020

@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
Copy link
Contributor

@toothrot toothrot commented Apr 21, 2020

@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
Copy link
Member

@peterbourgon peterbourgon commented Apr 21, 2020

@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
Copy link
Contributor

@toothrot toothrot commented Apr 21, 2020

@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/quote@v1.5.3-pre1 (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
Copy link
Member

@peterbourgon peterbourgon commented Apr 21, 2020

@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
Copy link
Member

@FiloSottile FiloSottile commented Apr 21, 2020

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
Copy link
Member

@peterbourgon peterbourgon commented Apr 21, 2020

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
Copy link
Member

@dmitshur dmitshur commented Apr 21, 2020

@peterbourgon Issue #38429 may be related.

@julieqiu julieqiu changed the title go.dev: ?tab=doc is added automatically x/pkgsite: ?tab=doc is added automatically Jun 15, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
9 participants
You can鈥檛 perform that action at this time.