RFC: Use object ...spread syntax in docs and examples

[gaearon]

Some early criticisms of Redux docs and examples included reliance on unstable features: #226. I think docs have come a long way since then, but we still don’t use decorators or object spread operator there.

I don’t think using decorators is a good idea. They are making people conflate presentational and container components, aren’t finalized, and aren’t currently included into Babel 6 as an official package.

However object spread is a different thing. It dramatically improves reducer readability, frees the user from worrying about Object.assign() polyfill, and is a very simple transformation. We already use ES6 array spread syntax everywhere, so adopting the object spread proposal wholeheartedly seems fitting. Finally, React users should already feel comfortable with it because JSX has a {...spread} equivalent.

I propose that we change all docs and examples to use the object spread operator, and add a page documenting our recommended Babel setup, as well as what the object spread operator desugars to.

Thoughts?

[gaearon]

(If you enjoy Twitter polls you can vote: https://twitter.com/dan_abramov/status/694519379191545856)

[gaearon]

We can also add an official ES6-only example, e.g. todomvc-es6. This way people who choose to stay within ES6 will have a good reference.

[RickWong]

I propose that we change all docs and examples to use the object spread operator, and add a page documenting our recommended Babel setup, as well as what the object spread operator desugars to.

That's an ideal solution. IMHO making people understanding reducers and Redux in general is the goal, and that goal is easier accomplished with object ...spread syntax examples, than with a desugared examples. Because of brevity and focus. It's also easier to write and update examples this way. As long as the project recognizes and explains the usage and set-up well.

[JamieDixon]

👍 for including object ..spread syntax. We're already moving at light speed and these kinds of decisions help drive new features in the mainstream. I think that's a great thing.

[nkt]

I guess you should use only stage-3 features in docs. So 👎 while this proposal in stage-2.

[DjebbZ]

Not until it's at least RC stage. "Forcing" people to write not-yet standard code means "forcing" them to use the tools that support them (only Babel AFAICT). Not everyone uses/likes (complex) build processes. I emphasis the quotes around "forcing", of course they could use the equivalent ES2015 (or ES5 if they like), but it requires translating from a non-standard language to a standard one first. Unnecessary complexity IMHO.

[mik01aj]

👎 . Imho it's better to wait until object spread becomes stable.

[brandon-vaughan]

👍 I think it's a great idea. With notes about what its doing and a recommended build process it makes sense. The docs aren't for copypasta use, its to learn how to use redux and recommend proper usage. Spread operators reinforce immutability and definitely improves readability to keep people focused on what matters.

[chrbala]

I didn't personally have any experience with ES2015 (etc) features until I started reading through the Redux documentation. The features used in the docs made the learning curve a bit harder, but learning it was well worth it in the end. Keep the spread operator.

[Scarysize]

I agree with @chrbala: the spread operator is an already widely used, terrific feature. And - as pointed out - increases code readability drastically. Though a hint on how to do it the ES5-way would be useful I guess. Maybe add examples in two versions (es6 and es5), pointing out the differences, so people can decide for themselves.

[johanneslumpe]

Good idea IMHO. The spread operator is already a stage 2 proposal and its usefulness by far outweighs any concerns about it not yet being "stable". 👍

[iZaL]

👍 for object ...spread

[mrspeaker]

This is an issue about documentation, so I think you should somehow weigh the response of newbies greater than those of us who've been using it for a while. Everyone who follows this on Twitter, or are +1'ing here are probably not the main consumers of documentation and can easily see where to use E6 features. Spreads-or-no-spreads in the docs is not so important for us. The docs should make it as clear as possible for new users (which of course may mean using spreads!).

[KevinDoughty]

The polyfills will never stop. There will always be new and unsupported features. Please, choose the ones you feel are appropriate by mixing ES6 and beyond, without abandoning support for plain ES5 and script tags.

[gaearon]

Writing a "Object Spread Operator" doc as the last chapter in Advanced section might be a good first step. We will show how to configure it (no need for stage 2 preset, just use es2015 + this specific plugin) and provide examples "before" and "after". We can also include a copy of one of the examples that uses this feature, e.g. tree-view-spread.

Volunteers?

[klimashkin]

Definitely for spread! Creating a poll for asking to change something always dangerous - too many conservatives. Move along!

[gaearon]

Don't forget about beginners who can't copy paste code in their projects and have no idea why the parser fails. Empathy ftw

[acdlite]

Since it's fairly common in React code, I'm for it.

[klimashkin]

Maybe it's ok to write no-spread version in a hover hint, or even better: for each snippet of code create to tabs - "modern", "es5"

[sompylasar]

RE: the beginners -- don't they use Babel already?

👍 for spread and a doc how to either use ES5 and Object.assign, or just enable ES-future-versions via Babel and write modern code.

I don't think this standard would change. Imagine you would refuse to use not-yet-standard HTML5 features. We're on the bleeding edge already with React version that starts with 0.

[sompylasar]

Modern/ES5 tabs would cause 2x maintenance overkill. Probably the modern code could be desugared automatically.

[zekedroid]

With how quickly things in the JS have been changing lately, I think the redux project's examples, and maybe even the project as a whole, could benefit from listing the active features. This is something that helped me dramatically as a beginner to the handsontable library.

But I'd go a step further and write a simple README in each example folder with the latest features being used, and their previous version/legacy counterparts. Base it off vanilla JS5 and you have a comprehensive list that could point to each source of features' repo page; so the babel features should point to the babel source, etc:

ES6 (source and list of ES6 features supported)

• ...
• let + const
• ... [spread operator]: precedes Object.assign()

Babel (source)

• babel6: precedes babel5
• more specific features implemented by .babelrc like the removal of all transforms by default

This not only helps people of all levels see the age of the example, but also points beginners to a source of all things they should learn about before taking on this project. Even though there are many many features that are constantly changing (babel5 vs babel6, react updates, es6/7 features, and redux itself) they are definitely finite and "listable".

It'd be easy to track each feature since pull requests related to upgrading/removing updated JS features would only be accepted if the feature README was updated as well.

But yes, totally for the spread operator.

[gaearon]

Let #1358 be the first (and only so far) step towards embracing object spread.
When the proposal reaches Stage 3, we will revisit this issue.

[gaearon]

A doc page exclusively on spread operator is up, thanks to @awear:
http://redux.js.org/docs/recipes/UsingObjectSpreadOperator.html