Change the default URL of doc.rust-lang.org

text/0000-change-doc-default-urls.md

@@ -0,0 +1,105 @@
+- Feature Name: N/A
+- Start Date: 2016-12-22
+- RFC PR: 
+- Rust Issue: 
+
+# Summary
+[summary]: #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
+[motivation]: #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][9461])
+* `/` not having any version info is a similar bug, stated in a different way,
+  but still has the same problems. ([issue link][14466])
+* 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][34271])
+
+[9461]: http://github.com/rust-lang/rust/issues/9461
+[14466]: https://github.com/rust-lang/rust/issues/14466
+[34271]: https://github.com/rust-lang/rust/issues/34271
+
+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](https://github.com/rust-lang/rust/issues/35020). 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](https://github.com/rust-lang/libc/pull/438) because so many extra
+  files were generated that GitHub Pages refused to serve them any more.
+
+From `#rust-internals` on 2016-12-22:
+
+```text
+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
+[design]: #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
+[how-we-teach-this]: #how-we-teach-this
+
+There's not a lot to teach; users end up on a different page than they used to.
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+Losing short URLs is a drawback. This is outweighed by other considerations,
+in my opinion, as the rest of the RFC shows.
+
+# Alternatives
+[alternatives]: #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
+[unresolved]: #unresolved-questions
+
+None.