[rust-dev] Rust Guidelines

Brian Anderson banderson at mozilla.com
Fri Jul 11 11:58:10 PDT 2014


Thanks, Aaron. This is going to be an important reference for authors. I 
love the sensible organization and that it's already seeded with many of 
our existing conventions.

On 07/11/2014 11:49 AM, Aaron Turon wrote:
> Rustafarians,
>
> As we head toward 1.0, we need to do do more than stabilize the 
> language: we need a broad and stable base of libraries as well.
>
> One of the key steps in that direction is reaching firm decisions on a 
> number of API design questions, ranging from bikesheddy stuff like 
> naming conventions to meatier stuff like when and how to use traits 
> for overloading.
>
>
> # THE RUST GUIDELINES DOCUMENT
>
> I've been accumulating a set of guidelines based mostly on current 
> Rust practice:
>
>     http://aturon.github.io/
>
> but I need a lot of help from the community to bring this project to 
> fruition.
>
> As of today, the repository for the guidelines is now owned by the 
> rust-lang github organization:
>
>     https://github.com/rust-lang/rust-guidelines
>
> Each guideline is tagged with a status:
>
> * [FIXME]: Marks places where there is clear work to be done that does 
> not require further discussion or consensus.
>
> * [OPEN]: Marks open questions that require concrete proposals for 
> further discussion.
>
> * [RFC]: Marks concrete, proposed guidelines that need further 
> discussion to reach consensus.
>
> * Untagged guidelines are considered accepted. To begin with, there 
> are almost none of these!
>
>
> # VIEWING THE GUIDELINES
>
> For now, http://aturon.github.io/ will host snapshots of the current 
> guidelines.
>
> I plan to move the guidelines away from gitbook and onto something 
> homegrown (built on rustdoc) soon, at which point we'll do rendering 
> in some more official way as part of the nightlies.
>
> The guidelines are also easy to browse from within github.
>
>
> # HOW YOU CAN HELP
>
> These guidelines cover a fair amount of ground, but still need a lot 
> of work:
>
> * We need to decide whether the [RFC]-status guidelines are ready to 
> be accepted.
>
> * We need to write many, many more guidelines. I've stubbed out a lot 
> of these at [OPEN] status, but there are plenty of unknown-unknowns.
>
> This project runs the risk of painting the biggest bikeshed ever. To 
> help keep things managable:
>
>   **DO NOT USE THE MAILING LIST** for discussing guidelines!
>
> Instead:
>
>   - Primarily, use http://discuss.rust-lang.org/ with category 
> "guidelines"
>   - Use the github.com/rust-lang/rust-guidelines issue tracker
>   - Submit PRs!
>
> Because guidelines are tagged with statuses, we can accept PRs at 
> [RFC] status without formally "approving" them.
>
>
> # CONSENSUS AND DECISIONS
>
> The process for accepting guidelines will evolve over time, as with 
> all of our processes. I'm hoping it will be a lighter-weight version 
> of the RFC process:
>
> 1. Discussion on http://discuss.rust-lang.org/ and the repo for a 
> given guideline goes on for a while.
>
> 2. At some point, either consensus is reached, or we simply need to 
> make a decision.
>
> 3. The decision is made by the Rust team during a "library" meeting. 
> For now, these are separate from the general Rust meetings.
>
> Once a guideline is approved, its [RFC] tag will be removed. We still 
> reserve the right to change the guideline later, but expect this to be 
> rare.
>
> The best part: approved guidelines can turn into (1) new github issues 
> to bring libstd into line and (2) an authoritative way to resolve 
> debates on libstd PRs.
>
> Here's to having these debates one last time, and then ending them!
> Aaron
> _______________________________________________
> Rust-dev mailing list
> Rust-dev at mozilla.org
> https://mail.mozilla.org/listinfo/rust-dev



More information about the Rust-dev mailing list