identified.
Without explicit settings, the tests will be run using rustfmt's default
-configuration. It is possible to run a test using non-default settings in several
+configuration. It is possible to run a test using non-default settings in several
ways. Firstly, you can include configuration parameters in comments at the top
of the file. For example: to use 3 spaces per tab, start your test with
`// rustfmt-tab_spaces: 3`. Just remember that the comment is part of the input,
## Hack!
-Here are some [good starting issues](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Agood-first-issue).
+Here are some [good starting issues](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
If you've found areas which need polish and don't have issues, please submit a
PR, don't feel there needs to be an issue.
wish there weren't. You can leave `FIXME`s, preferably with an issue number.
+### Version-gate formatting changes
+
+A change that introduces a different code-formatting should be gated on the
+`version` configuration. This is to ensure the formatting of the current major
+release is preserved, while allowing fixes to be implemented for the next
+release.
+
+This is done by conditionally guarding the change like so:
+
+```rust
+if config.version() == Version::One { // if the current major release is 1.x
+ // current formatting
+} else {
+ // new formatting
+}
+```
+
+This allows the user to apply the next formatting explicitly via the
+configuration, while being stable by default.
+
+When the next major release is done, the code block of the previous formatting
+can be deleted, e.g., the first block in the example above when going from `1.x`
+to `2.x`.
+
+| Note: Only formatting changes with default options need to be gated. |
+| --- |
+
### A quick tour of Rustfmt
Rustfmt is basically a pretty printer - that is, its mode of operation is to
There are different nodes for every kind of item and expression in Rust. For
more details see the source code in the compiler -
-[ast.rs](https://dxr.mozilla.org/rust/source/src/libsyntax/ast.rs) - and/or the
-[docs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/index.html).
+[ast.rs](https://github.com/rust-lang/rust/blob/master/compiler/rustc_ast/src/ast.rs) - and/or the
+[docs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html).
Many nodes in the AST (but not all, annoyingly) have a `Span`. A `Span` is a
range in the source code, it can easily be converted to a snippet of source