Improve the maintenance badge user experience

[jhinch]

• Change the alt-text to be a little more descriptive
  and screen-reader friendly
• Link to the Cargo documentation from the badge which describes what the maintenance intentions are

This addresses #2134. Have a read through of my summary for the motivations on the ticket to get a little context of what this is trying to achieve.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @smarnach (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[jhinch]

I'm happy to add tests but I'm unsure exactly what they would look like or if there are some examples I can look at. I'm a little out of practice with my frontend dev

[jhinch]

I have rebased my changes onto master to fix the broken tests which appear to be fixed on master. I am not familiar percy.io or what is needed to get it to pass.

[jhinch]

When I looked into the percy.io failure, it seems like the visual difference actually fixes a bug in terms of the vertical alignment (at least when I look at the vertical line spacing in comparison with other badges.

[bors]

☔ The latest upstream changes (presumably #2185) made this pull request unmergeable. Please resolve the merge conflicts.

[locks]

@jhinch thank you for helping out! Can you check the current conflict?

[jhinch]

Thanks for the response! I'll take a look at resolving the conflict

[jtgeibel]

@jhinch we discussed these changes in the team meeting yesterday, and the general consensus is that we should avoid duplicating documentation between crates.io and cargo. So far, we've preferred to link to cargo documentation unless the documentation is specific to crates.io, such as the policies page.

Would you mind splitting the documentation improvement part of this PR into a PR against the cargo documentation? I'd like to merge the improvements to the badge text and alt-text as part of this PR and then land a separate PR to link to the improved documentation. There are already some upstream changes to the cargo documentation that are currently in beta (linked below). Relative to the current stable the beta changes split [badges] into its own section. Maybe the documentation improvements from this PR can be applied there with a new header added under that section so that the maintenance badge section can be linked to directly.

The downside to this approach is that the documentation changes then take 6 to 12 weeks to hit stable. That still seems preferable to duplicating documentation between the two repos, and we could temporarily link to nightly/beta temporarily until the changes land on stable.

Okay, having said all that, there is a reasonable argument that the [badges] section is special. It's entirely possible that alternative registries offer different (or even no) badges. So maybe the badges section in cargo's documentation should just mention that the section is registry-specific and link to a page on crates.io. Moving all the badges documentation to this repo would be a larger change and we'd want to make sure the cargo team agrees with that change in approach as well.

So in summary, would you mind trimming this PR down to just the alt-text and screen reader improvements and then opening either a PR against cargo to improve the documentation or opening an issue to discuss migrating the badges documentation?

Docs Source (master): https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/manifest.md#the-badges-section
Rendered (beta): https://doc.rust-lang.org/beta/cargo/reference/manifest.html#the-badges-section

[jhinch]

Thanks for the detailed response. It's much appreciated. I agree that keeping the documentation in one place is much better if the Cargo documentation can be expanded on. For this PR, should I keep the link in place but link to the Cargo documentation, or would you like me to remove the link as well?

[jtgeibel]

Linking to the cargo docs in this PR sounds fine, thanks!

…

On Sat, Feb 22, 2020, 16:33 Jason Hinch ***@***.***> wrote: Thanks for the detailed response. It's much appreciated. I agree that keeping the documentation in one place is much better if the Cargo documentation can be expanded on. For this PR, should I keep the link in place but link to the Cargo documentation, or would you like me to remove the link as well? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#2140?email_source=notifications&email_token=AAAFNKWX2OCSZXLVFVEXAQTREGK2XA5CNFSM4KIFEEC2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEMVLCJY#issuecomment-590000423>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFNKTXVFGTAC54WN4R4LTREGK2XANCNFSM4KIFEECQ> .

[jhinch]

PR has been updated with feedback addressed. Apologies for the delay.

[Turbo87]

@bors r+

[bors]

📌 Commit cc7d217 has been approved by Turbo87

[bors]

⌛ Testing commit cc7d217 with merge ecc3239...

[bors]

☀️ Test successful - checks-travis
Approved by: Turbo87
Pushing ecc3239 to master...