Document common recipes for immutable updates

[gaearon]

Questions like this are very common.
facebook/react#11988 (comment)

We should have a page that explains common patterns for immutable updates for objects and arrays. It should also show how to combine these approaches for more nested fields. Finally it can link to some utilities for people who prefer them.

[nateeo]

I'd like to help out here - at least by contributing to the discussion. There is some existing documentation that covers some of these points at Reactjs.org - Immutability Helpers.

Perhaps we could start by creating a page that uses this information to explain the issues around mutability and immutable updates as well as some examples like Redux Immutable Update Patterns.

[gnapse]

I'd like to contribute too. It'd be challenging and interesting to do it while not assuming only ES6 language features. Alternatives to object and array spread notations should be covered as well.

[gaearon]

@nateeo Feel free to start, and @gnapse can help you once you have the first PR going!

[nateeo]

Put up an initial barebones draft so we can work from there! Just some thoughts:

I feel like it would be good to merge this page with https://reactjs.org/docs/update.html, which already briefly covers why people use immutable data. I've already written this draft towards people unfamiliar with immutability (but without any explanation as I would be repeating from that page), would be good to have more background.

more complex examples should probably be added, although the basics are there. I feel like complex examples would basically just serve to convince the reader to adopt a utility library.

@gnapse I had a look at some non-spread alternatives and it looked pretty horrendous - perhaps you can take the wheel there (if we need non-ES6 in the first place)

I'm eager for any feedback and will be actively working on improving from this draft!

[gnapse]

@nateeo this looks good! And I see you already covered briefly about how to approach some of these updates without ES6 features (e.g. using Object.assign). I mentioned that, because in the CONTRIBUTING.md guide from this repo, it is more or less implied that the documentation shouldn't always assume the latest and greatest of js when writing code examples. I think you covered pretty well already.

About merging this page with /docs/update.html, I'm not sure if that should be fully done, since a large portion of that page is the description of this addon that's now a library that's included in the links at the end. But yes, maybe some of it could be used, especially detailing a bit more about why mutations are bad, and why to pursue immutability. It could be a preamble before the content you already created.

If you don't mind I can draft some ideas. I can make a PR to your PR from my clone of this repo (since I can't write on your clone). Let me know what you think.

[nateeo]

Yeah I reckon we should add some brief text about when and why you'd want immutability, especially for newer devs. It'd be great if you could contribute, go ahead!

[nateeo]

Hey @gnapse how's the progress going? I'd be happy to bounce around ideas and help out if you want.

[gnapse]

Yes, sorry, got caught up last week. I did draft some ideas that I'll push in a PR to yours so we can discuss.

[nateeo]

@gnapse I think the intro is great! Should we mention how immutable data can be checked easily (object equality)?

Getting more feedback from others would be good, so we can polish this to production.