From 2688de47c89dc9327bac7b9c4aa20931c02d3a66 Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Thu, 22 Dec 2016 14:11:06 -0500 Subject: [PATCH 1/4] Change the default URL of doc.rust-lang.org --- text/0000-change-doc-default-urls.md | 92 ++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 text/0000-change-doc-default-urls.md diff --git a/text/0000-change-doc-default-urls.md b/text/0000-change-doc-default-urls.md new file mode 100644 index 00000000000..51eacbfa584 --- /dev/null +++ b/text/0000-change-doc-default-urls.md @@ -0,0 +1,92 @@ +- 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. + +# 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 `/`, becuase it's +what you get by defualt. 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/ should issue a redirect to https://doc.rust-lang.org/RELEASE, +where RELEASE is the latest stable release, like `1.14.0`. + +Part of the release process will be updating this redirect. + +# 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. + +# Unresolved questions +[unresolved]: #unresolved-questions + +None. From 70ddb1c4a54141cf173cb8218b623c8c39d08721 Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Thu, 22 Dec 2016 15:30:45 -0500 Subject: [PATCH 2/4] Add an alternative, thanks @QuietMisdreavus! :heart: --- text/0000-change-doc-default-urls.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/text/0000-change-doc-default-urls.md b/text/0000-change-doc-default-urls.md index 51eacbfa584..b08ca06bba5 100644 --- a/text/0000-change-doc-default-urls.md +++ b/text/0000-change-doc-default-urls.md @@ -86,6 +86,11 @@ 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 From 494294581cff5f3835c25d02b2282a87f044f105 Mon Sep 17 00:00:00 2001 From: Jake Goulding Date: Thu, 22 Dec 2016 17:13:42 -0500 Subject: [PATCH 3/4] Correct typos --- text/0000-change-doc-default-urls.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-change-doc-default-urls.md b/text/0000-change-doc-default-urls.md index b08ca06bba5..b0e26faa942 100644 --- a/text/0000-change-doc-default-urls.md +++ b/text/0000-change-doc-default-urls.md @@ -52,8 +52,8 @@ From `#rust-internals` on 2016-12-22: 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 `/`, becuase it's -what you get by defualt. By changing the default, people will link to the +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. From 638012962de0bc83eb859895954cd32dcd70378b Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Fri, 8 Sep 2017 14:20:25 -0400 Subject: [PATCH 4/4] update as per feedback --- text/0000-change-doc-default-urls.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/text/0000-change-doc-default-urls.md b/text/0000-change-doc-default-urls.md index b0e26faa942..c74a3560eda 100644 --- a/text/0000-change-doc-default-urls.md +++ b/text/0000-change-doc-default-urls.md @@ -9,6 +9,9 @@ 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 @@ -60,10 +63,15 @@ 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`. -Part of the release process will be updating this redirect. +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