Polish the API Guidelines to `1.0`

[KodrAus]

This is a tracking issue for polishing the API Guidelines as a stable resource. We might want to close this in favour of an issue on the Guidelines repository.

What do we need to do before we can call the API Guidelines '1.0'? How do we want to curate the discussion around guidelines going forward?

[KodrAus]

cc @aturon @dtolnay

[aturon]

AFAIK the actual content is ready to go, and what needs to happen next is for it to become a part of the official "Rust Bookshelf".

@steveklabnik, how does that work?

[QuietMisdreavus]

The basic process for getting something onto the Bookshelf and into official docs is something like this:

• Open a PR to rust-lang/rust that adds the new docs to the repo:
  • Adds a new submodule for the book
  • Adds rules to rustbuild to allow it to be built with the rest of the docs
  • (Does linkchecker/tidy run automatically? If not, they may need to be pointed at the new output)
  • Add a line to the docs landing page linking to the new book
• Nominate/FCP it to the docs team for merging

At least, that's basically how it worked for Rust By Example. At that point, i'd probably want to make sure we have some kind of subteam set up for its maintenance, since my understanding would be that it would come under the docs team's purview at that point.

[KodrAus]

Thanks @QuietMisdreavus!

I'm also interested to know what we want to do with the ongoing discussions, outside of the content itself.

[ghost]

Having API Guidelines is very good situation. Having tool which detects API Guidelines invalidations and shows example from the guadline (more or like clippy does) is even much better. I know the compiler warns about a few of them (like camelcase). Wouldn't this feature be expanded?