Summary

Change doc.rust-lang.org to redirect to the latest release instead of an alias of stable.

Introduce a banner that contains a dropdown allowing users to switch between versions, noting when a release is not the most current release.

Motivation

Today, if you hit https://doc.rust-lang.org/, you’ll see the same thing as if you hit https://doc.rust-lang.org/stable/. It does not redirect, but instead displays the same documentation. This is suboptimal for multiple reasons:

  • One of the oldest bugs open in Rust, from September 2013 (a four digit issue number!), is about the lack of rel=canonical, which means search results are being duplicated between / and /stable, at least (issue link)
  • / not having any version info is a similar bug, stated in a different way, but still has the same problems. (issue link)
  • We’ve attempted to change the URL structure of Rustdoc in the past, but it’s caused many issues, which will be elaborated below. (issue link)

There’s other issues that stem from this as well that haven’t been filed as issues. Two notable examples are:

  • When we release the new book, links are going to break. This has multiple ways of being addressed, and so isn’t a strong motivation, but fixing this issue would help out a lot.
  • In order to keep links working, we modified rustdoc to add redirects from the older format. But this can lead to degenerate situations in certain crates. libc, one of the most important crates in Rust, and included in the official docs, had their docs break because so many extra files were generated that GitHub Pages refused to serve them any more.

From #rust-internals on 2016-12-22:

18:19 <@brson> lots of libc docs
18:19 <@steveklabnik> :(
18:20 <@brson> 6k to document every C constant

Short URLs are nice to have, but they have an increasing maintenance cost that’s affecting other parts of the project in an adverse way.

The big underlying issue here is that people tend to link to /, because it’s what you get by default. By changing the default, people will link to the specific version instead. This means that their links will not break, and will allow us to update the URL structure of our documentation more freely.

Detailed design

https://doc.rust-lang.org/ will be updated to have a heading with a drop-down that allows you to select between different versions of the docs. It will also display a message when looking at older documentation.

https://doc.rust-lang.org/ should issue a redirect to https://doc.rust-lang.org/RELEASE, where RELEASE is the latest stable release, like 1.14.0.

The exact details will be worked out before this is ‘stabilized’ on doc.rust-lang.org; only the general approach is presented in this RFC.

How We Teach This

There’s not a lot to teach; users end up on a different page than they used to.

Drawbacks

Losing short URLs is a drawback. This is outweighed by other considerations, in my opinion, as the rest of the RFC shows.

Alternatives

We could make no changes. We’ve dealt with all of these problems so far, so it’s possible that we won’t run into more issues in the future.

We could do work on the rel=canonical issue instead, which would solve this in a different way. This doesn’t totally solve all issues, however, only the duplication issue.

We could redirect all URLs that don’t start with a version prefix to redirect to /, which would be an index page showing all of the various places to go. Right now, it’s unclear how many people even know that we host specific old versions, or stuff like /beta.

Unresolved questions

None.