link to /latest/ version of docs

[jsha]

Current behavior: the "latest" revision of a crate page, e.g. https://crates.io/crates/ureq, shows a link to docs.rs with an explicitly versioned URL, e.g. docs.rs/ureq/2.5.0. Since last year, docs.rs offers a page that will always show the latest version of docs: https://docs.rs/ureq/latest/ureq/. There's also a longstanding redirect from https://docs.rs/ureq that now goes to /latest/. The redirect is preferable because the linking page doesn't have to worry about crate name vs package name distinctions (- vs _, usually).

The purpose of the /latest/ URL is to have a consistent URL for search engines to assign rank to, to avoid searching engines linking to outdated crate versions.

To that end, it would be helpful if crates.io would link to docs.rs/<crate> instead of docs.rs/<crate>/<version, specifically in the case where the user is not on a specifically versioned page on crates.io.

[Turbo87]

I'm not sure I agree with that proposal unless we can be absolutely sure that both pages always show the exact same version. That would require us to perform the "default version" resolution on the server side and publish it on the API. That is certainly a possibility, but nothing we are currently doing.

[jsha]

In general I expect them to be the same, since both docs.rs and crates.io evaluate "latest" the same way, according to semver, right?

I think there is one edge cases where they wouldn't be exactly the same:

A new version was just built, and is visible on crates.io but not on docs.rs, for instance because it is stuck in the queue or failed the doc build. In this situation linking to the exact new version is a worse user experience. It will go to a 404.

Also I noticed something a little surprising: some crates, like hyper, specify their own docs URL but point at docs.rs:

https://github.com/hyperium/hyper/blob/23a56005bd35c7efb68a9cedda4ab41926c49821/Cargo.toml#L7

documentation = "https://docs.rs/hyper"

But visiting https://crates.io/crates/hyper it gets rewritten to docs.rs/hyper/0.14.20. Presumably there's some special logic that is aware docs.rs URLs can be transformed in this way?

[Turbo87]

In general I expect them to be the same, since both docs.rs and crates.io evaluate "latest" the same way, according to semver, right?

I'm not so sure about that. The crates.io frontend is not just ordering by semver and using the "highest" version, it also takes prereleases and yanked versions into account. (see https://github.com/rust-lang/crates.io/blob/master/app/routes/crate/version.js#L32-L33 and https://github.com/rust-lang/crates.io/blob/master/app/models/crate.js#L35-L42)

But visiting https://crates.io/crates/hyper it gets rewritten to docs.rs/hyper/0.14.20. Presumably there's some special logic that is aware docs.rs URLs can be transformed in this way?

yep, see https://github.com/rust-lang/crates.io/blob/master/app/models/version.js#L139-L159

[jsha]

docs.rs also takes into account yanked versions:

https://github.com/rust-lang/docs.rs/blob/6208c4a25b3e1a3693cab333bb6db0bb892dfc26/src/web/mod.rs#L350-L365

and pre-releases:

https://github.com/rust-lang/docs.rs/blob/6208c4a25b3e1a3693cab333bb6db0bb892dfc26/src/web/mod.rs#L367-L380

using the semver crate:

https://docs.rs/semver/latest/semver/index.html