Link to last successful build when build fails

[jyn514]

I thought about this while investigating why https://docs.rs/crate/hyper/0.13.0 failed to build - the reason this usually matters to library authors is because new users/users upgrading see an error instead of the docs. If there a version of the docs, even an out of date version, I imagine that would make the failures much less critical for library authors.

[jyn514]

I want to make it a link, not a redirect, so people know that it's an old version.

[jyn514]

Actually maybe this would be better served by implementing #341, #396 at the same time and just putting it in the 'Redirect to Latest Version' button at the top? 'Latest Version' is no longer an accurate description then ... 'latest successful stable version' is closer but way too verbose to put in a link.

[jyn514]

Hmm ... but in this case I think people would want to know the latest version is released even if there's no docs. I think separate links is fine.

Relevant code: https://github.com/rust-lang/docs.rs/blob/master/templates/crate_details.hbs#L65

[jyn514]

The way to get started with this would be to

• find the last successful build from the database (something like SELECT version FROM releases INNER JOIN crates ON releases.crate_id = crates.id WHERE build_status = true AND yanked = false AND crates.name = $1;)
• add the last successful build to the variables for the page
• add a message to the error template which links to the last build

[yvrhdn]

Hi, I would like to work on this 👋 Can you assign me? 🙂

[yvrhdn]

I did some analysis, just to make sure I'm changing the right things 😉

So the main issue: if the build of a release of a crate fails, a user should be able to find the most recent successful build fairly simple.
Currently we often link to the latest release which isn't necessary a successful build.

There a two places this causes a problem:

Crate details page

If a build failed (for example fie-0.16.2), currently an error message is showed:

We can extend the error message with a quick link: "The most recent successful build is fie-0.15.0"
This will allow users to quickly find working documentation.

I also propose extending the "Versions" segment in the left column. I think it would be nice to show a little icon (⚠️) next to versions that failed to build.
That would look a bit like this then 👇

Navigation header

Another place with a possibly problematic link is the navigation bar.

Let's take as example this crate fie. Version 0.16.x doesn't build, but 0.15.0 did.
So when you visit fie-0.15.0, there is a link ":warning: Go to latest version"
This links to a fie-0.16.2 which is not available!

Maybe we can split this up and show two messages instead:

• if the latest release failed: ":warning: Build of latest release failed" --> this links to crate details (useful for library authors)
• if there is a more recent successful build: ":warning: This is not the latest available documentation" --> links to most recent successful build (useful for users)

Changes

So changes I would like to implement:

1. crate details: extend error message to link to the last successful build
2. crate details: add a little icon to versions that failed to build
3. navigation header: split up warning messages into "latest release failed to build" and "go to latest successful build"

Feedback and comments are welcome!

[jyn514]

Currently we often link to the latest release which isn't necessary a successful build.

Yes, and moreover usually it's the latest release which failed a build (at least if the user sees the message at all).

We can extend the error message with a quick link: "The most recent successful build is fie-0.15.0"

Yes, that's about what I was imagining.

I think it would be nice to show a little icon (warning) next to versions that failed to build.

That would be really great! I hadn't though of that :)

So when you visit fie-0.15.0, there is a link "warning Go to latest version" This links to a fie-0.16.2 which is not available!

I am not opposed to fixing this, but there are many issues with the current 'latest version' calculation and I think that would be better as a separate PR. See #396, #502, #223, #341, #513 for related issues.

[jyn514]

So in other words, 1. and 2. are very welcome but it may be better to hold off on 3. for a while.

[yvrhdn]

Agree, I'll focus on crate details for now.

I have been able to add the link to the last successful build. Just not sure how to add it to the UI...

The current error message looks like this:

I can add the link "inline":

Or I can put it in a separate box:

Inline:

➖ feels a bit cluttered
➖ the link is not super intuitive, you have to read the text of the error message

Separate box:

➕ I like that the message comes across very clear
➖ having two info/warning boxes seems a bit much?

[jyn514]

I don't have a strong opinion either way. @GuillaumeGomez you do more of the CSS/styling, do you have a preference?

[pietroalbini]

I prefer the separate box myself.