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.

Sign up for GitHub

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

Jump to bottom

x/pkgsite: don't imply that vN.x.y is the latest version when vN+1 exists #37765

Closed
cespare opened this issue Mar 9, 2020 · 12 comments
Closed

x/pkgsite: don't imply that vN.x.y is the latest version when vN+1 exists #37765

cespare opened this issue Mar 9, 2020 · 12 comments
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Milestone
pkgsite/design-2020

Comments

@cespare
Copy link
Contributor

cespare commented Mar 9, 2020 •
edited
Loading

What is the URL of the page with the issue?

For example: https://pkg.go.dev/github.com/cespare/xxhash?tab=doc

What is your user agent?

N/A

Screenshot

screen_20200309145922

What did you do?

Viewed the v1 documentation for a module that also has a v2.

What did you expect to see?

No v1 version of my module should be marked as "Latest" since v2 exists.

What did you see instead?

v1.1.0 was marked as "Latest".

I understand that v1 and v2 are essentially two different modules, and that the discovery site is showing that v1.1.0 is the latest version of the v1 module. However, this may mislead users into thinking that v1.1.0 is somehow up-to-date. I do not want new users of my module to use v1.1.0; I want them to use the real latest version of the module which is v2.1.1 at the moment.

Ideally, when viewing v1.1.0, the users would see on the page that v2 exists and is the latest major module version. There ought to be a link to quickly go to the latest version, just as there is a red "Go to latest" link when viewing the not-latest-minor-version page (example):

screen_20200309150757

This is related to #36969, where the search ranking also pushes users toward using the old major version of my module.

Right now it seems that the discovery site has very little notion of the relationship between different major versions of the same module. Please consider how to make this site more friendly for maintainers of v2+ modules.
@gopherbot gopherbot added this to the Unreleased milestone Mar 9, 2020
@julieqiu julieqiu added the UX Issues that involve UXD/UXR input label Mar 10, 2020
@julieqiu
Copy link
Member

Thanks for the feedback! We understand that this is confusing and plan to fix it as part of an upcoming round of UX changes.

/cc @fflewddur

@julieqiu julieqiu added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Mar 10, 2020
@bcmills
Copy link
Contributor

bcmills commented Mar 10, 2020

I think there are two different notions of “latest” at play here.

One is “what is the latest implementation of this API?”, and for that notion, v1.1.0 is correct.

The other is “what is the latest variant of this API that addresses the same general use-cases?”, and that notion is better answered by v2.1.1.

It may be worthwhile to surface both of those answers in some fashion.

@mvdan mvdan mentioned this issue Apr 30, 2020
Closed
@julieqiu julieqiu changed the title go.dev: don't imply that vN.x.y is the latest version when vN+1 exists x/pkgsite: don't imply that vN.x.y is the latest version when vN+1 exists Jun 15, 2020
@bcmills bcmills mentioned this issue Aug 12, 2020
Closed
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/250797 mentions this issue: internal: create GetLatestMajorVersion function in DataSource

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/250937 mentions this issue: internal/postgres: create GetLatestMajorVersion in postgres package

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/251083 mentions this issue: internal/middleware: change latestversion to latestminorversion

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/251157 mentions this issue: internal/middleware: add latest major version value to latest version middleware

gopherbot pushed a commit to golang/pkgsite that referenced this issue Aug 28, 2020
internal/postgres: create GetLatestMajorVersion in postgres package
a457b9e 
This change completes the GetLatestMajorVersion function in the
DataSource interface that retrieves the latest major version of a module
path by adding the implementation for the postgres package.

Updates golang/go#37765

Change-Id: I48eadab8b71ffe73cec49f5c8bcd4f48f13b490d
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/250937
Reviewed-by: Julie Qiu <julie@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Run-TryBot: Julie Qiu <julie@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
gopherbot pushed a commit to golang/pkgsite that referenced this issue Aug 28, 2020
internal/middleware: change latestversion to latestminorversion
2a24ee1 
With the inclusion of the latest major version function, this commit
changes current "latestversion" naming to "latestminorversion" in the
latestversion middleware to specify the difference between both
functions.

Updates golang/go#37765

Change-Id: I1c4d8edf6ac30431ef1278abaa334d96cd459258
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/251083
Reviewed-by: Julie Qiu <julie@golang.org>
Run-TryBot: Julie Qiu <julie@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
gopherbot pushed a commit to golang/pkgsite that referenced this issue Aug 28, 2020
internal: create GetLatestMajorVersion function in DataSource
cd2ea52 
This change creates a function in the DataSource interface that
retrieves the latest major version of a module path. This includes a
function in the proxydatasource package.

Updates golang/go#37765

Change-Id: I29505c1d7df51dd9bef8228e73bbedeea9771347
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/250797
Reviewed-by: Julie Qiu <julie@golang.org>
Run-TryBot: Julie Qiu <julie@golang.org>
@AceroM
Copy link

AceroM commented Aug 31, 2020

We’re planning to add a banner to pkg.go.dev, to indicate when there is a newer major version. Here is a mock:
image

@myitcv
Copy link
Member

myitcv commented Aug 31, 2020

Looks great! However, I'd suggest the pkg.go.dev/ prefix is redundant/misleading in this case. Because the module path of the latest major version is github.com/russross/blackfriday/v2 - the user will just so happen to be viewing that via pkg.go.dev

gopherbot pushed a commit to golang/pkgsite that referenced this issue Aug 31, 2020
internal/middleware: add latest major version middleware function
6f12538 
This change introduces a middleware function for the new
GetLatestMajorVersion function. We also rename the function name to
LatestVersions to clarify the scope better.

The latest major version value is generated and writen into new
placeholder values that is prepared for the upcoming HTML changes.

Updates golang/go#37765

Change-Id: I1f3b19a4e2cfb290000f756e8548670cbfd4033d
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/251157
Reviewed-by: Jonathan Amsterdam <jba@google.com>
@AceroM
Copy link

AceroM commented Aug 31, 2020

Looks great! However, I'd suggest the pkg.go.dev/ prefix is redundant/misleading in this case. Because the module path of the latest major version is github.com/russross/blackfriday/v2 - the user will just so happen to be viewing that via pkg.go.dev

Thanks! We had it as the module path at first but we didn't want users thinking they would redirect to github.com/...

@cespare
Copy link
Contributor Author

cespare commented Aug 31, 2020

I agree with @myitcv -- it seems better to phrase this in terms of actual module names.

The fact that package/module names look an awful lot like github.com/[other hosting provider] URLs is just one of those things that Go users have to get used to. I attached a few examples at the bottom where module names are links within pkg.go.dev already.

But it also seems to me that the message could simply be:

The latest major version is v2

That draws attention to the major version number, which is the important part of the message.

link1

link2

@AceroM
Copy link

AceroM commented Sep 1, 2020 •
edited
Loading

But it also seems to me that the message could simply be:
The latest major version is v2
That draws attention to the major version number, which is the important part of the message.

Thanks @cespare for your suggestion! We will update the text accordingly. 🙂

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/251817 mentions this issue: internal: add GetLatestMajorVersion banner in documentation HTML

@julieqiu julieqiu removed the UX Issues that involve UXD/UXR input label Sep 1, 2020
@bcmills bcmills mentioned this issue Sep 21, 2020
Open
This was referenced Sep 23, 2020
Closed
Closed
@golang golang locked and limited conversation to collaborators Sep 1, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Projects
None yet
Milestone
pkgsite/design-2020
Development

No branches or pull requests
6 participants
@cespare @myitcv @bcmills @julieqiu @gopherbot @AceroM