|
| 1 | +# Rust code formatting RFCs |
| 2 | + |
| 3 | +This repository exists to decide on a code style for Rust code, to be enforced |
| 4 | +by the Rustfmt tool. Accepted RFCs live in the `text` directory and form a |
| 5 | +specification for formatting tools. |
| 6 | + |
| 7 | +## The formatting RFC process |
| 8 | + |
| 9 | +See [RFC TODO](TODO) for more details. Where this process is under-specified, |
| 10 | +see the process for [Rust RFCs](https://github.com/rust-lang/rfcs). |
| 11 | + |
| 12 | +* If there is no single, obvious style, then open a GitHub issue on the |
| 13 | + fmt-rfcs repo for initial discussion. This initial discussion should identify |
| 14 | + which Rustfmt options are required to enforce the guideline. |
| 15 | +* Implement the style in rustfmt (behind an option if it is not the current |
| 16 | + default). In exceptional circumstances (such as where the implementation would |
| 17 | + require very deep changes to rustfmt), this step may be skipped. |
| 18 | +* Write an RFC formalising the formatting convention and referencing the |
| 19 | + implementation, submit as a PR to fmt-rfcs. The RFC should include the default |
| 20 | + values for options to enforce the guideline and which non-default options |
| 21 | + should be kept. |
| 22 | +* The RFC PR will be triaged by the style team and either assigned to a team |
| 23 | + member for [shepherding](https://github.com/rust-lang/rfcs#the-role-of-the-shepherd), |
| 24 | + or closed. |
| 25 | +* When discussion has reached a fixed point, the RFC PR will be put into a final |
| 26 | + comment period (FCP). |
| 27 | +* After FCP, the RFC will either be accepted and merged or closed. |
| 28 | +* Implementation in Rustfmt can then be finished (including any changes due to |
| 29 | + discussion of the RFC), and defaults are set. |
| 30 | + |
| 31 | + |
| 32 | +### Scope of the process |
| 33 | + |
| 34 | +This process is specifically limited to formatting style guidelines which can be |
| 35 | +enforced by Rustfmt with its current architecture. Guidelines that cannot be |
| 36 | +enforced by Rustfmt without a large amount of work are out of scope, even if |
| 37 | +they only pertain to formatting. |
| 38 | + |
| 39 | + |
| 40 | +### Size of RFCs |
| 41 | + |
| 42 | +RFCs should be self-contained and coherent, whilst being as small as possible to |
| 43 | +keep discussion focused. For example, an RFC on 'arithmetic and logic |
| 44 | +expressions' is about the right size; 'expressions' would be too big, and |
| 45 | +'addition' would be too small. |
| 46 | + |
| 47 | + |
| 48 | +### When is a guideline ready for RFC? |
| 49 | + |
| 50 | +The purpose of the style RFC process is to foster an open discussion about style |
| 51 | +guidelines. Therefore, RFC PRs should be made early rather than late. It is |
| 52 | +expected that there may be more discussion and changes to style RFCs than is |
| 53 | +typical for Rust RFCs. However, at submission, RFC PRs should be completely |
| 54 | +developed and explained to the level where they can be used as a specification. |
| 55 | + |
| 56 | +A guideline should usually be implemented in Rustfmt **before** an RFC PR is |
| 57 | +submitted. The RFC should be used to select an option to be the default |
| 58 | +behaviour, rather than to identify a range of options. An RFC can propose a |
| 59 | +combination of options (rather than a single one) as default behaviour. An RFC |
| 60 | +may propose some reorganisation of options. |
| 61 | + |
| 62 | +Usually a style should be widely used in the community before it is submitted as |
| 63 | +an RFC. Where multiple styles are used, they should be covered as alternatives |
| 64 | +in the RFC, rather than being submitted as multiple RFCs. In some cases, a style |
| 65 | +may be proposed without wide use (we don't want to discourage innovation), |
| 66 | +however, it should have been used in *some* real code, rather than just being |
| 67 | +sketched out. |
| 68 | + |
| 69 | + |
| 70 | +### Triage |
| 71 | + |
| 72 | +RFC PRs are triaged by the style team. An RFC may be closed during triage (with |
| 73 | +feedback for the author) if the style team think it is not specified in enough |
| 74 | +detail, has too narrow or broad scope, or is not appropriate in some way (e.g., |
| 75 | +applies to more than just formatting). Otherwise, the PR will be assigned a |
| 76 | +shepherd as for other RFCs. |
| 77 | + |
| 78 | + |
| 79 | +### FCP |
| 80 | + |
| 81 | +FCP will last for two weeks (assuming the team decide to meet every two weeks) |
| 82 | +and will be announced in the style team sub-team report. |
| 83 | + |
| 84 | + |
| 85 | +### Decision and post-decision process |
| 86 | + |
| 87 | +The style team will make the ultimate decision on accepting or closing a style |
| 88 | +RFC PR. Decisions should be by consensus. Most discussion should take place on |
| 89 | +the PR comment thread, a decision should ideally be made when consensus is |
| 90 | +reached on the thread. Any additional discussion amongst the style team will be |
| 91 | +summarised on the thread. |
| 92 | + |
| 93 | +If an RFC PR is accepted, it will be merged. An issue for implementation will be |
| 94 | +filed in the appropriate place (usually the Rustfmt repository) referencing the |
| 95 | +RFC. If the style guide needs to be updated, then an issue for that should be |
| 96 | +filed on the Rust repository. |
| 97 | + |
| 98 | +The author of an RFC is not required to implement the guideline. If you are |
| 99 | +interested in working on the implementation for an 'active' RFC, but cannot |
| 100 | +determine if someone else is already working on it, feel free to ask (e.g. by |
| 101 | +leaving a comment on the associated issue). |
| 102 | + |
0 commit comments