forked from rust-lang/rfcs
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Change the default URL of doc.rust-lang.org
- Loading branch information
1 parent
16318db
commit 2688de4
Showing
1 changed file
with
92 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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]: https://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. |