- Feature Name: N/A
- Start Date: 2016-12-22
- RFC PR: rust-lang/rfcs#1826
- Rust Issue: rust-lang/rust#44687
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.
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
/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.
#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.
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
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.
Losing short URLs is a drawback. This is outweighed by other considerations, in my opinion, as the rest of the RFC shows.
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