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: request for documentation for non-std modules responds with an error #51368

Open
bhcleek opened this issue Feb 25, 2022 · 3 comments
Open
Labels
NeedsInvestigation pkgsite/cmd pkgsite
Milestone

Comments

@bhcleek
Copy link
Contributor

@bhcleek bhcleek commented Feb 25, 2022

What is the URL of the page with the issue?

Any module that does not have a dot in its name and is not part of the standard library.

What is your user agent?

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

What did you do?

  1. Run a local pkgsite instance to serve documentation for a module that is only available internally and which does not have a . in its name.
  2. Request the godoc for module's packages.

What did you expect to see?

The godoc for the page.

What did you see instead?

An error page.

The issue is caused by "github.com/golang/pkgsite/internal/frontend".serveDetails, which calls "github.com/golang/pkgsite/internal/frontend".extractURLPathInfo which in turn relies on "github.com/golang/pkgsite/internal/stdlib".Contains.

While I can understand the standard library taking precedence, it would be nice if serveDetails would fallback to checking the other modules so that modules which are internal to a company and not expected to be available publicly could have documentation served by pkgsite as well.

Unfortunately, updating the module name is a disruption that is not yet worth the trouble.

@gopherbot gopherbot added this to the pkgsite/unplanned milestone Feb 25, 2022
@jamalc
Copy link

@jamalc jamalc commented Mar 14, 2022

I understand the use case but I'm not sure this is something we would move forward with. Package names should always be globally unique and this namespace is reserved for the stdlib. Others might disagree. /cc @jba @julieqiu

Would the replace directive be useful here in avoiding major disruption from a module name change?

@jamalc jamalc added the NeedsInvestigation label Mar 14, 2022
@jamalc jamalc removed this from the pkgsite/unplanned milestone Mar 14, 2022
@jamalc jamalc added this to the pkgsite/cmd milestone Mar 14, 2022
@jba
Copy link
Contributor

@jba jba commented Mar 14, 2022

I agree with Jamal.
If you don't want to change your package names, I'd suggest patching our code for your local deployment.

@bhcleek
Copy link
Contributor Author

@bhcleek bhcleek commented Mar 14, 2022

this namespace is reserved for the stdlib

I recognize that this is understood within the Go team, and I understand why packages without a dot in the name must be preferred to come from stdlib in the event of a collision, but is this documented some place? Since starting to work with Go in 2013, I have never seen anyone say this or talk about it except for in some GitHub issues and some meetings with the Go team.

Given that godoc doesn't have this restriction and given that the go tool itself doesn't enforce such a restriction on package names, the incongruence in pkgsite is very unexpected.

@hyangah hyangah added the pkgsite/cmd label May 20, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
NeedsInvestigation pkgsite/cmd pkgsite
Projects
None yet
Development

No branches or pull requests

5 participants