[rust-dev] Rust Guidelines

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