Update rationale for the 1.15 changes

docs/option-philosophy.md

@@ -19,7 +19,8 @@ Then there's a bunch of interesting cases.
 
 - `--trailing-comma es5` was added to make it easier to use trailing commas in most environments without having to transpile (trailing function commas were added in ES2017).
 - `--prose-wrap` is important to support all quirky markdown renderers in the wild.
-- `--arrow-parens` was added after [huge demand](https://github.com/prettier/prettier/issues/812). Prettier has to strike a balance between ideal goals and listening to the community.
+- `--arrow-parens` was added after – at the time – [huge demand](https://github.com/prettier/prettier/issues/812). Prettier has to strike a balance between ideal goals and listening to the community.
+- `--jsx-single-quote` was also added after [great demand](https://github.com/prettier/prettier/issues/1080), but after more consideration. It took quite some time to figure out the right approach.
 - `--jsx-bracket-same-line` was needed for a big company with a huge code base (Facebook), which backed the project when it got started, to be able to [adopt Prettier at all](https://github.com/prettier/prettier/pull/661#issuecomment-295770645).
 
 Finally, perhaps the most interesting of them all is `--bracket-spacing`.

docs/rationale.md

@@ -15,7 +15,8 @@ The first requirement of Prettier is to output valid code that has the exact sam
 
 Double or single quotes? Prettier chooses the one which results in the fewest number of escapes. `"It's gettin' better!"`, not `'It\'s gettin\' better!'`. In case of a tie, Prettier defaults to double quotes (but that can be changed via the [`--single-quote`](options.html#quotes) option).
 
-JSX always uses double quotes. JSX takes its roots from HTML, where the dominant use of quotes for attributes is double quotes. Browser developer tools also follow this convention by always displaying HTML with double quotes, even if the source code uses single quotes.
+JSX has its own option for quotes: [`--jsx-single-quote`](options.html#jsx-quotes).
+JSX takes its roots from HTML, where the dominant use of quotes for attributes is double quotes. Browser developer tools also follow this convention by always displaying HTML with double quotes, even if the source code uses single quotes. A separate option allows using single quotes for JS and double quotes for "HTML" (JSX).
 
 Prettier maintains the way your string is escaped. For example, `"🙂"` won't be formatted into `"\uD83D\uDE42"` and vice versa.
 
@@ -28,13 +29,114 @@ It turns out that empty lines are very hard to automatically generate. The appro
 
 ### Multi-line objects
 
-By default, Prettier’s printing algorithm prints expressions on a single line if they fit. Objects are used for a lot of different things in JavaScript, though, and sometimes it really helps readability if they stay multiline. See [object lists], [nested configs], [stylesheets] and [keyed methods], for example. We haven't been able to find a good rule for all those cases, so Prettier instead keeps objects multiline if there's a newline anywhere inside it in the original source code. A consequence of this is that long singleline objects are automatically expanded, but short multiline objects are never collapsed.
+By default, Prettier’s printing algorithm prints expressions on a single line if they fit. Objects are used for a lot of different things in JavaScript, though, and sometimes it really helps readability if they stay multiline. See [object lists], [nested configs], [stylesheets] and [keyed methods], for example. We haven't been able to find a good rule for all those cases, so Prettier instead keeps objects multiline if there's a newline between the `{` and the first key in the original source code. A consequence of this is that long singleline objects are automatically expanded, but short multiline objects are never collapsed.
+
+**Tip:** If you have a multiline object that you'd like to join up into a single line:
+
+```js
+const user = {
+  name: "John Doe",
+  age: 30
+};
+```
+
+…all you need to do is remove the newline after `{`:
+
+<!-- prettier-ignore -->
+```js
+const user = {  name: "John Doe",
+  age: 30
+};
+```
+
+…and then run Prettier:
+
+```js
+const user = { name: "John Doe", age: 30 };
+```
+
+And if you'd like to go multiline again, add in a newline after `{`:
+
+<!-- prettier-ignore -->
+```js
+const user = {
+ name: "John Doe", age: 30 };
+```
+
+…and run Prettier:
+
+```js
+const user = {
+  name: "John Doe",
+  age: 30
+};
+```
 
 [object lists]: https://github.com/prettier/prettier/issues/74#issue-199965534
 [nested configs]: https://github.com/prettier/prettier/issues/88#issuecomment-275448346
 [stylesheets]: https://github.com/prettier/prettier/issues/74#issuecomment-275262094
 [keyed methods]: https://github.com/prettier/prettier/pull/495#issuecomment-275745434
 
+### Decorators
+
+Just like with objects, decorators are used for a lot of different things. Sometimes it makes sense to write decorators _above_ the line they're decorating, sometimes it's nicer if they're on the _same_ line. We haven't been able to find a good rule for this, so Prettier keeps your decorator positioned like you wrote them (if they fit on the line). This isn't ideal, but a pragmatic solution to a difficult problem.
+
+```js
+@Component({
+  selector: "hero-button",
+  template: `<button>{{label}}</button>`
+})
+class HeroButtonComponent {
+  // These decorators were written inline and fit on the line so they stay
+  // inline.
+  @Output() change = new EventEmitter();
+  @Input() label: string;
+
+  // These were written multiline, so they stay multiline.
+  @readonly
+  @nonenumerable
+  NODE_TYPE: 2;
+}
+```
+
+There's one exception: classes. We don't think it ever makes sense to inline the decorators for them, so they are always moved to their own line.
+
+<!-- prettier-ignore -->
+```js
+// Before running Prettier:
+@observer class OrderLine {
+  @observable price: number = 0;
+}
+```
+
+```js
+// After running Prettier:
+@observer
+class OrderLine {
+  @observable price: number = 0;
+}
+```
+
+Note: Prettier 1.14.x and older tried to automatically move your decorators, so if you've run an older Prettier version on your code you might need to manually join up some decorators here and there to avoid inconsistencies:
+
+```js
+@observer
+class OrderLine {
+  @observable price: number = 0;
+  @observable
+  amount: number = 0;
+}
+```
+
+One final thing: TC39 has [not yet decided if decorators come before or after `export`](https://github.com/tc39/proposal-decorators/issues/69). In the meantime, Prettier supports both:
+
+```js
+@decorator
+export class Foo { }
+
+export @decorator class Foo { }
+```
+
 ### Semicolons
 
 This is about using the [`--no-semi`](options.md#semicolons) option.