[rust-dev] Rust Guidelines

Aaron Turon aturon at mozilla.com
Fri Jul 11 11:49:15 PDT 2014


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


More information about the Rust-dev mailing list