Topbar menu includes links for all past versions of a crate

[jsha]

Steps to reproduce:

1. Visit https://docs.rs/libc/0.2.139/libc/constant.ABMON_5.html
2. Open the crate menu
3. Look at the "VERSIONS" section

Expected result:

It contains a handful of recent versions, or the latest version in each major version sequence.

Actual result:

It contains all of the past versions! This results in this page being 101kB in size.

[GuillaumeGomez]

A solution about this could to get this list only when the menu is opened and make an endpoint on the server to query it. What do you think about this approach?

[jsha]

I like that idea but for a different reason: it would mean we could set a Last-Modified header on the page based on its build dates, since the versions list would no longer be changing based on other versions being released.

[GuillaumeGomez]

Oh well, if both back-end and front-end gets an advantage out of it, I guess it's a good idea. 😆

[notriddle]

JavaScript lazy-loading would fix the perf problems, but I think it would be better to just show the current version, maybe a few previous versions, and a link to a separate page with all of the versions on it:

• Consider how the UI is actually designed, with the list of versions inside a scrolling sub-panel in the mega dropdown. Does anyone actually want to scroll through hundreds of versions in that tiny little window? Or would you rather get to use your whole screen for it?
• It requires shipping the JavaScript to actually populate the list. That's probably smaller than the list of libc versions, but most crates aren't libc. JS-based lazy loading is a pessimization on crates with only a few versions.

[GuillaumeGomez]

Consider how the UI is actually designed, with the list of versions inside a scrolling sub-panel in the mega dropdown. Does anyone actually want to scroll through hundreds of versions in that tiny little window? Or would you rather get to use your whole screen for it?

I'm actually not sure to understand what you mean there. Do you suggest actually putting the version numbers into a real dropdown instead with a button "go to this version"?

It requires shipping the JavaScript to actually populate the list. That's probably smaller than the list of libc versions, but most crates aren't libc. JS-based lazy loading is a pessimization on crates with only a few versions.

We could have a threshold like "if we have less than X versions, then we directly render the versions into the HTML, otherwise we include the script to load them". The JS itself would be pretty small since it only requires to be triggered on a given even, send an AJAX query and then populate the list.

[notriddle]

I'm actually not sure to understand what you mean there. Do you suggest actually putting the version numbers into a real dropdown instead with a button "go to this version"?

I was actually thinking of having a threshold where if there's more than five or so versions, you get a link to a dedicated page with all the versions, like how feature flags work.

Mockup

Though putting the version numbers into a real dropdown sounds like a good idea, yeah. The important idea that I was trying to get across is that the current UX is inadequate for large numbers of versions, regardless of how good the implementation is.

We could have a threshold like "if we have less than X versions, then we directly render the versions into the HTML, otherwise we include the script to load them". The JS itself would be pretty small since it only requires to be triggered on a given even, send an AJAX query and then populate the list.

Sure, but that's probably not worth the extra complexity, and doesn't help with the Last-Modified HTTP header implementation. My version doesn't help either, though.

[jsha]

We could move the "platforms" dropdown into the crate dropdown, freeing up some space for a standalone "versions" dropdown.

As an FYI / addition: the "docs.rs crate page" also has a list of versions (in the sidebar) and it has the same problem: https://docs.rs/crate/libc/latest

[GuillaumeGomez]

Though putting the version numbers into a real dropdown sounds like a good idea, yeah. The important idea that I was trying to get across is that the current UX is inadequate for large numbers of versions, regardless of how good the implementation is.

Seems like everyone agrees on that. :)

Sure, but that's probably not worth the extra complexity, and doesn't help with the Last-Modified HTTP header implementation. My version doesn't help either, though.

Last-Modified HTTP header implementation is just the last time the crate was updated, not really difficult to find nor to implement considering we have this information. Still more than what we currently have though indeed.

We could move the "platforms" dropdown into the crate dropdown, freeing up some space for a standalone "versions" dropdown.

Do we have statistics of usage of specific platform versus specific version? I think it'd be helpful to have these numbers before modifying things.

As an FYI / addition: the "docs.rs crate page" also has a list of versions (in the sidebar) and it has the same problem: https://docs.rs/crate/libc/latest

A dropdown to fix them all. :D

[syphar]

I believe depending on the motivation for this change we could have different solutions.

Is the motivation page-size? Than making the dropdown async would help. Though seeing that we will cache the pages in the CDN + gzip compression, the difference is probably quite small.

Or is it UX? Then it probably boils down to: which versions does a user typically switch to? only between major/minor, and the latest patch is good enough? Or between the most recent patch releases? Here we don't have any data (yet).

We could move the "platforms" dropdown into the crate dropdown, freeing up some space for a standalone "versions" dropdown.

Do we have statistics of usage of specific platform versus specific version? I think it'd be helpful to have these numbers before modifying things.

I like that idea but for a different reason: it would mean we could set a Last-Modified header on the page based on its build dates, since the versions list would no longer be changing based on other versions being released.

Since we can also have yanks or crate/release-deletes, IMO this is not 100% true. The CDN invalidations only help with invalidating the pages in the case of caching the pages in the CDN, and not with the automatic last-modified based caching in the browser ( from a discussion in #1560).

some data:

there are 363 crates with more than 100 releases.

top 20, releases per crate:

 air-interpreter-wasm           |  1199
 debugzzzone                    |   830
 astrolab-smart-coffee-types    |   810
 rustc-ap-rustc_data_structures |   714
 rustc-ap-rustc_errors          |   706
 rustc-ap-serialize             |   659
 myutil                         |   644
 swc_ecmascript                 |   636
 rustc-ap-syntax_pos            |   617
 sctpx                          |   615
 rustc-ap-syntax                |   606
 rustc-ap-rustc_target          |   593
 swc_bundler                    |   536
 rustc-ap-arena                 |   521
 rustc-ap-rustc_cratesio_shim   |   517
 indy                           |   503
 indy-sys                       |   493
 swc_core                       |   480
 swc_ecma_transforms            |   475
 advent-of-code                 |   461

[syphar]

( about the visited pplatform/version graphs: this only shows us the amount of visited, not who used which dropdown or access method to get there)

[GuillaumeGomez]

The platform and the version are visible in the URL (although not that easy to parse I suppose in this case). I hoped that we had information about the number of URLs targeting a specific platform and URLs targeting a specific version.

[syphar]

we currently don't have that specific information collected, and we don't have request logs yet where we could parse it.

[GuillaumeGomez]

Ah that's too bad. Is it worth adding you think?

[jsha]

number of URLs targeting a specific platform and URLs targeting a specific version.
Is it worth adding you think?

I think not. It would not help decide on the appropriate UI change here. The question is: "how often do people navigate between versions of a crate's documentation?" That's different from "how often do people load a non-latest version of a crate's documentation?" The latter in particular is affected by search engines directing people to specific versions, and blog posts and other web pages linking directly to specific versions.

I like that idea (lazy-loading version list) but for a different reason: it would mean we could set a Last-Modified header on the page based on its build dates, since the versions list would no longer be changing based on other versions being released.

Since we can also have yanks or crate/release-deletes, IMO this is not 100% true. The CDN invalidations only help with invalidating the pages in the case of caching the pages in the CDN, and not with the automatic last-modified based caching in the browser ( from a discussion in #1560).

Yanks, crate deletes, and release deletes all affect two things:

• the versions list.
• the warning icon that says "this is not the latest version."

If we make the versions list not a part of the page, we could also tweak the warning icon code to be lazy-loaded via a separate (non-cacheable, non-blocking) request.

[syphar]

We now have lazy loading which helps with performance, but not yet with the UX part.

When we would think about limiting the versions we show in this dropdown, which would be the best choices?

The last X patch-versions?
or something semver-based? (the latest patch version for the last X minor versions?)

[GuillaumeGomez]

I thought about grouping versions into a collapsible section by bigger version number. Not sure if it'd be helpful or not though...

[jsha]

How about time-based? The 10 most recently published versions, with a "see all" link at the bottom that goes to the crate details page?

For that matter, the crate details page displays versions in a small box that gets cramped with many versions. Perhaps there should be a dedicated tab for displaying the list of versions? That would also allow room for additional details on a per-version basis, similar to how the crates.io versions tab works. For instance, we might want to show the publication date, plus fully written-out text for "documentation failed to build" or "this version was yanked."