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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: modules with no package at the root directory are shown awkwardly #36791

Open
mvdan opened this issue Jan 27, 2020 · 1 comment
Open

x/pkgsite: modules with no package at the root directory are shown awkwardly #36791

mvdan opened this issue Jan 27, 2020 · 1 comment

Comments

@mvdan
Copy link
Member

@mvdan mvdan commented Jan 27, 2020

For example, say I want to share a module with friends. Coming from godoc.org, and being used to go list -m, I simply do: https://pkg.go.dev/mvdan.cc/sh/v3

However, that page looks wrong. It simply lists the subdirectories, not showing much else that's useful besides the version and license.

Perhaps I have to click into the "overview" tab? That seems to work, as it shows me the README at least. But other useful tabs like Versions are greyed out. What gives?

It turns out what I actually want is https://pkg.go.dev/mod/mvdan.cc/sh/v3. Funnily enough, that page looks almost exactly the same as the previous overview tab, but with a different set of tabs.

I find this pretty confusing. As a module author, which one should I be sharing with others? I think I clearly want the last URL for the module view, but I presume many Go users will go through the same three-step dance to get to the information we want, just like I did.

I think the root of the problem here is that we're not giving module information enough priority. I see two ways we could address this; they could both be done at the same time.

  1. If a path is a module and not a Go package, we should directly show the module information, e.g. via a redirect
  2. If a path is both a module and a Go package, we should make that extremely clear, and not just via the small Module: text tucked away between the title and the bar with tabs.

In my particular case, 1 would be important so that people find what's useful right away, even if they try the "wrong" URL. If they really do want the package subdirectories, they can always use https://pkg.go.dev/mvdan.cc/sh/v3?tab=subdirectories.

Number 2 would make the site far less confusing in my eyes. The discovery site seems to give preference to packages over modules, which I assume is to be expected given godoc.org, and how go list requires the -m flag to be switched to modules. However, I think a path being the root of a module is very important information we should make extremely obvious to someone skimming the page.

@mvdan
Copy link
Member Author

@mvdan mvdan commented Jan 27, 2020

For the record, about eight months ago I argued that the /mod prefix was a bad idea, and that module information should be available at /import/path/go.mod instead of /mod/import/path. When /import/path does not contain a Go package, then I think it's even more obvious that we should show the information for /import/path/go.mod.

Unfortunately, the feedback had to be given in private, and I presume the decision to discard the idea happened in person or in private. I'd like to think that it's not too late to consider the idea.

@rogpeppe rogpeppe added the pkgsite label Jan 27, 2020
@gopherbot gopherbot added this to the Unreleased milestone Feb 6, 2020
@julieqiu julieqiu added the UX label Mar 11, 2020
@julieqiu julieqiu changed the title go.dev: modules with no package at the root directory are shown awkwardly x/pkgsite: modules with no package at the root directory are shown awkwardly 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
4 participants
You can’t perform that action at this time.