x/pkgsite: redesign - umbrella issue #41585

This is the umbrella issue for an upcoming redesign of pkg.go.dev. Specific plans will be shared via a series of additional issues:

1. x/pkgsite: redesign - the pkg.go.dev/<path> page #41586: the pkg.go.dev/<path> page
2. x/pkgsite: redesign - the documentation section #41587: the documentation section
3. x/pkgsite: redesign - surfacing “latest” #41588: surfacing “latest”
4. x/pkgsite: support custom links #42968: support custom links
5. x/pkgsite: additional metadata in the right sidebar #43129: additional metadata in the right sidebar

Milestone: pkgsite/design-2020

Background

Pkg.go.dev is a site for developers to discover and evaluate Go packages and modules, and have the information they need to decide whether they want to integrate these packages into their codebase. Like godoc.org, pkg.go.dev serves Go documentation, but it also provides information about past versions of packages. Eventually, traffic from godoc.org will be redirected to the corresponding page on pkg.go.dev.

A Go repository can contain several Go modules, each of which has its own packages. The way this information is organized on pkg.go.dev today makes it confusing to users how packages, modules, different major versions, and repositories are related to each other.

Based on feedback, the general themes are:

pkg.go.dev/<path> page

The /mod/ pages are not surfacing useful information:

• x/pkgsite: modules with no package at the root directory are shown awkwardly #36791: modules with no package at the root directory are shown awkwardly
• x/pkgsite: rethink module page #38087: rethink module page

Package page lacks potentially useful information:

• x/pkgsite: add repository link on documentation page #39218: add repository link on documentation page
• x/pkgsite: show README.md of "subpackages" in overview tab #38513: show README of subpackage in overview tab
• x/pkgsite: subdirectories are missing for nested modules #38596: subdirectories are missing for nested modules
• x/pkgsite: add option to refresh a package on the package page #41278: add option to refresh a package on the package page
• x/pkgsite: provide multiple "copy to clipboard" options #38514: provide multiple "copy to clipboard" options
• x/pkgsite: add import / imported by counts #37912: add import / imported by count

The “latest” version for a pkg.go.dev/<path> pages can be confusing:

• x/pkgsite: flag packages that are no longer present in the latest version of the containing module #37631: flag packages that are no longer present in the latest version of the containing module
• x/pkgsite: /<path> should show the contents for the latest version of the containing module  #39244: /<path> should show the contents for the latest version of the containing module
• x/pkgsite: multi-module projects have confusing versions #41032: multi-module projects have confusing versions
• x/pkgsite: new major version not surfaced when it does not yet have a release tag #41345: new major version not surfaced when it does not yet have a release tag
• x/pkgsite: latest version should not be +incompatible  #37714 (recently fixed): latest version should not be +incompatible
• x/pkgsite: don't imply that vN.x.y is the latest version when vN+1 exists #37765 (recently fixed): don't imply that vN.x.y is the latest version when vN+1 exists (also mentioned in proposal: cmd/go: notify about newer major versions #40323)

Search page

Search results are noisy:

• x/pkgsite: do not show packages of a module at the top level #37788: do not show packages of a module at the top level
• x/pkgsite: searching for modules isn't supported #36814: searching for modules isn't supported
• x/pkgsite: searching for "youtube" only show results for github.com/youtube/vitess  #39525: searching for "youtube" only show results for github.com/youtube/vitess

The “latest” version for a search result can be confusing:

• x/pkgsite: search ranking ought to prioritize more recent major module versions #36969: search ranking ought to prioritize more recent major module versions (also x/pkgsite: search results show incorrect latest version if the latest version of the module and package do not match #41108)
• x/pkgsite: search results show incorrect latest version if the latest version of the module and package do not match #41108: search results show incorrect latest version if the latest version of the module and package do not match
• x/pkgsite: partial search doesn't return (any) matches which are "close" or latest #36806 (comment): rank the newest version of a module in a series of modules, higher than older ones:

Next

We plan to redesign pkg.go.dev to address these issues, with the goal of providing a better user experience on pkg.go.dev. These plans will be shared via a series of issues for discussion. Work for this milestone will be tracked at pkgsite/design-2020.