16.3 release blog draft #587

bvaughn · 2018-02-05T16:30:25Z

reactjs-bot · 2018-02-05T16:34:04Z

Deploy preview for reactjs ready!

Built with commit aa9810f

https://deploy-preview-587--reactjs.netlify.com

gaearon · 2018-02-05T17:37:29Z

content/blog/2018-02-07-react-v-16-3.md

Second sentence with an exclamation point in a sequence, maybe soften one of them?

gaearon · 2018-02-05T17:39:22Z

content/blog/2018-02-07-react-v-16-3.md

Is it worth to linking to anything at all here for "asynchronous rendering"? Maybe Tomo's F8 talk. The first thought of anyone reading this will be "but I don't need asynchronous rendering". Which is maybe okay given (assumed) further communication on the topic but I wish we could give more info right here.

Okay. I had linked to something like this in an earlier draft of the Quip, but was unsure about it since we had links (below) to an "update on async rendering". I didn't want to link to that here (so early) but I was unsure about linking to an outdated doc/talk too.

I can add a link to Tom's F8 talk though. That seems reasonable.

Duplication doesn't hurt. If by the time the blog post comes out, we'll have the "update on async rendering" ready, we can link to it the first time we mention async rendering in the post too. So I mean

the React team has been working on support for [asynchronous rendering] <-- this is a link to our update

...
the rest of the post
...
[learn more about async rendering] <-- same link

It's just important that people who don't know what it is can immediately learn more without having to dig through the whole post.

gaearon · 2018-02-05T17:39:57Z

content/blog/2018-02-07-react-v-16-3.md

I'd put this section first because it's more exciting than deprecations

gaearon · 2018-02-05T17:40:27Z

content/blog/2018-02-07-react-v-16-3.md

+ "We have created an [automatic script] that prefixes the lifecycle names with the "UNSAFE_" prefix"

Also we have not established what "UNSAFE_" lifecycles are by this point. The person reading this will not know that they correspond to cWM/cWU/cWRP since those are supposed to be deprecated. It's not obvious.

I'm not sure how much to overlap with this doc and the other, more detailed one.

There's a tendency to move more and more into this one. Hm. Will think about it.

The goal is to prevent FUD spreading like fire. People who spread FUD don't research the problem, they stop at the first sentence that looks "bad". Here's an alternative wording that avoids this pitfall:

Deprecation warnings will be enabled in version 16.4, but the deprecated lifecycles will continue to work until version 17. After version 17, it will still be possible to use them, but they will be aliased with an UNSAFE_ prefix to indicate that they might cause issues. We have prepared an automated script that renames them in the existing code.

gaearon · 2018-02-05T17:40:53Z

content/blog/2018-02-07-react-v-16-3.md

Odd punctuation: leaks- (somethin

Should have been an em dash. Will fix.

gaearon · 2018-02-05T17:43:59Z

content/blog/2018-02-07-react-v-16-3.md

Maybe:

Many of these issues are exacerbated by a subset of the component lifecycles (componentWillMount, componentWillReceiveProps, and componentWillUpdate). They also happen to be the same methods that people get most confused about. For these reasons, we are going to deprecate those methods in favor of better alternatives.

We recognize that many components use those methods, so the deprecations won’t happen overnight. At Facebook, we maintain more than 50 thousand React components, and we can't tell our engineers to rewrite them either. The migration path will be as gradual as possible, and we will provide escape hatches.

gaearon · 2018-02-05T17:47:05Z

content/blog/2018-02-07-react-v-16-3.md

gaearon · 2018-02-05T17:47:25Z

content/blog/2018-02-07-react-v-16-3.md

I think mentioning "mutation" as a problem is going to seriously worry MobX users. What is our messaging here?

Not sure. I can soften this? ("certain types of mutations")

gaearon · 2018-02-05T17:47:44Z

content/blog/2018-02-07-react-v-16-3.md

"for async rendering" — we still haven't explained what it is and why anyone should care

There will be an "update on async rendering" blog post released along with this that this will link into. I intentionally don't want to put too much about that into this, because I want this to be a digestible summary. I can add a link.

bvaughn · 2018-02-06T18:49:06Z

Added a section about the createRef API and update the StrictMode section to mention the string ref detection.

gaearon · 2018-02-06T18:56:55Z

content/blog/2018-02-07-react-v-16-3.md

“Better” might imply you have to convert from functional refs.

Maybe “and a new ergonomic ref API”.

gaearon · 2018-02-06T19:00:47Z

content/blog/2018-02-07-react-v-16-3.md

I would still add

Callback refs will continue to be supported alongside this API for the foreseeable future. You don’t need to change the code using callback refs to the new API. Callback refs are slightly more flexible so they will stay as an advanced feature.

gaearon · 2018-02-06T19:01:15Z

examples/16-3-release-blog-create-ref.js

Nit: we don’t use the underscore convention elsewhere in the docs.

Gotcha. Long time habit.

bvaughn · 2018-02-07T17:26:15Z

Rebased on master with the new Prettier config width.

gaearon · 2018-02-12T17:42:29Z

content/blog/2018-02-07-react-v-16-3.md

+
+## Official Context API
+
+For many years, React has offered an experimental API for context. Although it was a powerful tool, our advice was mostly to [avoid using it](/docs/context.html#why-not-to-use-context) because of potential problems with the API. We've always intended to replace the experimental API with a better one, and as of version 16.3- we've finally done that!


This can read as if the minor version breaks the old API (the concern is valid even if we say we respect semver because we always positioned context as "unsafe").

I would change it to:

We've always intended to replace the experimental API with a better one, and as of version 16.3 the new API is available! The old context API will keep working in all React 16 minor releases so you will have time to migrate.

gaearon

Aside from my last comment this looks good to me.

I'd still prefer if we said "legacy lifecycles" rather than "deprecated lifecycles" until we actually enable the deprecation warnings. I don't feel strongly about this so deferring to your judgement.

bvaughn · 2018-02-12T18:02:54Z

I'd still prefer if we said "legacy lifecycles" rather than "deprecated lifecycles" until we actually enable the deprecation warnings. I don't feel strongly about this so deferring to your judgement.

Hm. I already changed the only occurrence of "deprecated lifecycles" to "legacy lifecycles". Do you see one I missed?

bvaughn · 2018-02-12T18:03:25Z

Oh whoops, I was searching the other branch. Nevermind 😄

I replaced 2 of the "deprecated" references with "legacy", leaving only "we are going to deprecate those methods"

sophiebits

Solid post.

sophiebits · 2018-02-13T03:41:21Z

content/blog/2018-02-07-react-v-16-3.md

+
+This release includes a new class component lifecycle (`getDerivedStateFromProps`), a new `StrictMode` component, an official context API, and a new ergonomic ref API!
+
+For the past few months, the React team has been working on support for [asynchronous rendering](#). We are excited about the new features this will enable, and we've learned that some changes will be required to the way we write React components.


s/some changes will be/some long-term changes will be/ maybe?

sophiebits · 2018-02-13T03:42:00Z

content/blog/2018-02-07-react-v-16-3.md

+
+For the past few months, the React team has been working on support for [asynchronous rendering](#). We are excited about the new features this will enable, and we've learned that some changes will be required to the way we write React components.
+
+We're releasing version 16.3 primarily so that open source maintainers can start incorporating these changes into their libraries well in advance of the next major release. **However, you should not feel pressured to make changes to your application code yet.** We respect semver and will not ship breaking changes in a minor version!


Honestly this paragraph right here reads to me as a little alarmist since you haven't even told me what you're changing. Can we move this down into the lifecycle section maybe?

I think some reassurance that we won't break anything in a minor release belongs near the top, where people are most likely to see it.

Maybe I can shorten and soften the wording slightly to make it less alarmist?

Maybe something more like this:

For the past few months, the React team has been working on support for asynchronous rendering. We are excited about the new features it will enable.

We’ve also learned that some long-term changes will be required to the way we write React components. However, we respect semver and will not ship breaking changes in a minor version!

sophiebits · 2018-02-13T03:56:32Z

content/blog/2018-02-07-react-v-16-3.md

+
+> **Note**
+>
+> The old context API will keep working for all React 16 minor releases, so you will have time to migrate.


"all React 16.x releases"? In case "minor" isn't universally clear.

sophiebits · 2018-02-13T03:57:31Z

content/blog/2018-02-07-react-v-16-3.md

+
+## Official Context API
+
+For many years, React has offered an experimental API for context. Although it was a powerful tool, our advice was mostly to [avoid using it](/docs/context.html#why-not-to-use-context) because of potential problems with the API. We've always intended to replace the experimental API with a better one, and as of version 16.3 the new API is available!


Most of the why not context was actually focused on people using it as an alternative for props and it was discouraged because it can make code hard to follow, not because of its instability. Can we just say like "Although it was a powerful tool, its use was discouraged, in part because the API had inherent problems in its design from the start, and we always intended to replace the experimental API with a better one. In version 16.3, we're introducing a new context API that supports static type checking and deep updates as well as being more efficient."

sophiebits · 2018-02-13T03:58:50Z

content/blog/2018-02-07-react-v-16-3.md

+> Callback refs will continue to be supported in addition to the new `createRef` API.
+>
+> You don't need to replace callback refs in your components. They are slightly more flexible, so they will remain as an advanced feature.
+


What's the upgrade path? Is there a codemod?

No codemod. I proposed one initially, but a codemod couldn't properly handle this case:

class App extends React.Component { render() { return ( <OtherComponent renderThing={() => <div ref='refThatShouldBelongToOtherComponentInstance' /> } /> ); } }

I guess we could still write a codemod that bailed out on that case, but it didn't seem like there was a lot of support for one when I mentioned it during last week's sync.

Sorry if I was unclear; I am very supportive of the codemod that handles simple cases correctly, as long as it's solid in the bailouts.

I wasn't thinking of you specifically, just the general impression I got was a lack of interest.

I'm not necessarily volunteering to do it myself, but I'll add it to the quip as a non-16.3-release-blocking step. 😄

sophiebits · 2018-02-13T03:59:52Z

content/blog/2018-02-07-react-v-16-3.md

+>
+> Deprecation warnings will be enabled in version 16.4, **but the legacy lifecycles will continue to work until version 17**.
+>
+> After version 17, it will still be possible to use them, but they will be aliased with an "UNSAFE_" prefix to indicate that they might cause issues. We have also prepared an [automated script to rename them](https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles) in existing code.


s/After version 17/Even in version 17/

sophiebits · 2018-02-13T04:00:41Z

content/blog/2018-02-07-react-v-16-3.md

+
+React's class component API has been around for years with little change. However, as we add support for more advanced features (such as [error boundaries](/docs/react-component.html#componentdidcatch) and the upcoming [async rendering mode](#)) we stretch this model in ways that it was not originally intended.
+
+For example, with the current API, it is too easy to block the initial render with non-essential logic. In part this is because there are too many ways to accomplish a given task, and it can be unclear which is best. We've observed that the interrupting behavior of error handling is often not taken into consideration and can result in memory leaks—(something that will also impact the upcoming async rendering mode). The current class component API also complicates other efforts, like our work on a React compiler.


remove em dash

work on a React compiler -> "work on prototyping a React compiler"? don't want people to get hopes up too much. link it to https://twitter.com/trueadm/status/944908776896978946 too tho?

alexkrolick · 2018-03-23T21:02:15Z

@bvaughn @gaearon Think I covered this round of context comments at bvaughn#5

Feel free to just edit directly - you have a better sense of where it needs to go.

Context updates

bvaughn · 2018-03-23T21:09:56Z

Thanks Alex. I've merged your PR into this branch.

gaearon · 2018-03-24T13:32:12Z

content/docs/context.md

-    super(props);
-    this.state = {type:'desktop'};
-  }
+## Caveats


Before Caveats, I think we should also add a section that explains how to create a higher order component for consuming context. This is a common sentiment and I think we should proactively address it: https://twitter.com/DankoKozar/status/977469702204162048?s=20

I'll add this.

Context comes before the Higher-Order Components reference page, but I'll cross link.

Yeah, cyclical dependencies are pretty much unavoidable in the "Advanced" section

… example

bvaughn · 2018-03-29T15:43:04Z

I tweaked the note about what belongs in state. In general, I think we might want to consider re-writing this section in the near future- to reduce the endorsement of putting values on the instance (since this causes async trickiness). I don't consider that a 16.3 blocker though.

gaearon · 2018-03-29T15:54:34Z

content/docs/state-and-lifecycle.md

 While `this.props` is set up by React itself and `this.state` has a special meaning, you are free to add additional fields to the class manually if you need to store something that is not used for the visual output.

-If you don't use something in `render()`, it shouldn't be in the state.
+State is generally used to store values that are referenced by `render()` (for visual output) or by `getDerivedStateFromProps()` (to compare next and previous props values).


By this point the user doesn’t know what getDerivedStateFromProps is. I don’t think it’s necessary to introduce it here. It just creates a sense of uneasiness (“did I miss something? Do I need to read the doc on it now?”) and potentially point the reader into a wrong direction (learning to sync props before learning to lift them up).

I understand what you were trying to do but maybe there’s another way?

That's fair. I had considered linking to the docs page for the method but that would take people out of the flow.

Maybe just delete the note entirely?

Sounds good.

The above sentence can also change to

While this.props is set up by React itself and this.state has a special meaning, you are free to add additional fields to the class manually if you need to store something that doesn’t participate in the data flow (like a timer ID).

This reverts commit 032576c.

This reverts commit 691cd45.

gaearon · 2018-03-29T18:06:52Z

content/docs/context.md

 ## Caveats

+### `Consumer` Inline Function as a Child
+


gaearon · 2018-03-29T18:09:06Z

examples/context/consumer-cached-function-as-a-child.js

@@ -0,0 +1,15 @@
+class Example extends React.Component {


gaearon · 2018-03-29T18:09:10Z

examples/context/consumer-inline-function-as-a-child.js

@@ -0,0 +1,15 @@
+class Example extends React.Component {


facebook-github-bot added the CLA Signed label Feb 5, 2018

gaearon reviewed Feb 5, 2018

View reviewed changes

gaearon reviewed Feb 6, 2018

View reviewed changes

bvaughn mentioned this pull request Feb 6, 2018

An update on async rendering #596

Merged

2 tasks

bvaughn added 7 commits February 7, 2018 09:24

Initial draft for 16.3 release blog

444896e

Wording changes in response to PR feedback

141de66

Added entry for createRef API

ce57928

Added note about string ref API to strict mode section

da29d89

Small wording nit

a55480b

Minor edits in response to PR feedback

935d2a1

Formatted example

ab62e88

bvaughn force-pushed the 16.3-release-blog-post branch from 9b65182 to ab62e88 Compare February 7, 2018 17:25

This was referenced Feb 10, 2018

Replace deprecated / async-unsafe lifecycles bvaughn/react-virtualized#1008

Closed

Replace deprecated / async-unsafe lifecycles bvaughn/react-virtualized#1009

Merged

gaearon reviewed Feb 12, 2018

View reviewed changes

gaearon approved these changes Feb 12, 2018

View reviewed changes

Wordsmithing in response to PR feedback

08d444e

sophiebits reviewed Feb 13, 2018

View reviewed changes

bvaughn and others added 5 commits February 13, 2018 11:15

Incorporated Sophie's PR feedback

5a1d653

Added example of before/after context API

8494428

Removed context-before example

c08533a

Wordsmith nit

33ff167

Added React.createRef doc

c09a284

bvaughn added the 16.3 label Feb 22, 2018

address feedback

ee78358

alexkrolick added 4 commits March 23, 2018 13:20

Replace divs with some fake components

920b4f4

Add caveats section

349446d

Prettier

b0e8604

Fix syntax

8437e37

Merge pull request #5 from alexkrolick/16.3-release-blog-post

587ad93

Context updates

gaearon reviewed Mar 24, 2018

View reviewed changes

bvaughn added 7 commits March 24, 2018 08:58

Added DevTools naming consideration to React.forwardRef reference doc…

f11a149

… example

Added context HOC example to reference

bd06bbc

Merge branch 'master' into 16.3-release-blog-post

b7b97c0

Linked to async blog post

6d77836

Renamed blog post

e5cf31a

Merge branch 'master' into 16.3-release-blog-post

a29098e

Tweaked message about what goes into state

57eb7cc

gaearon reviewed Mar 29, 2018

View reviewed changes

bvaughn added 5 commits March 29, 2018 09:13

Tweaked state-and-lifecycle wording more

28b2b76

Added inline child function caveat to Context docs

691cd45

Prettier

032576c

Revert "Prettier"

797a792

This reverts commit 032576c.

Revert "Added inline child function caveat to Context docs"

3a36a40

This reverts commit 691cd45.

gaearon reviewed Mar 29, 2018

View reviewed changes

content/docs/context.md Outdated

## Caveats

### `Consumer` Inline Function as a Child

Copy link

Member

gaearon Mar 29, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bye bye

gaearon reviewed Mar 29, 2018

View reviewed changes

bvaughn added 5 commits March 29, 2018 11:18

Cross-link to async update post

e5ca13e

Missing 'we'

992a756

Tweaked link to Context API

5a587d1

Fixed link

ac1d767

Fixed some links and improved a recommendation

aa9810f

bvaughn merged commit b618684 into reactjs:master Mar 29, 2018


		## Official Context API

		For many years, React has offered an experimental API for context. Although it was a powerful tool, our advice was mostly to [avoid using it](/docs/context.html#why-not-to-use-context) because of potential problems with the API. We've always intended to replace the experimental API with a better one, and as of version 16.3- we've finally done that!


		This release includes a new class component lifecycle (`getDerivedStateFromProps`), a new `StrictMode` component, an official context API, and a new ergonomic ref API!

		For the past few months, the React team has been working on support for [asynchronous rendering](#). We are excited about the new features this will enable, and we've learned that some changes will be required to the way we write React components.


		For the past few months, the React team has been working on support for [asynchronous rendering](#). We are excited about the new features this will enable, and we've learned that some changes will be required to the way we write React components.

		We're releasing version 16.3 primarily so that open source maintainers can start incorporating these changes into their libraries well in advance of the next major release. However, you should not feel pressured to make changes to your application code yet. We respect semver and will not ship breaking changes in a minor version!


		React's class component API has been around for years with little change. However, as we add support for more advanced features (such as [error boundaries](/docs/react-component.html#componentdidcatch) and the upcoming [async rendering mode](#)) we stretch this model in ways that it was not originally intended.

		For example, with the current API, it is too easy to block the initial render with non-essential logic. In part this is because there are too many ways to accomplish a given task, and it can be unclear which is best. We've observed that the interrupting behavior of error handling is often not taken into consideration and can result in memory leaks—(something that will also impact the upcoming async rendering mode). The current class component API also complicates other efforts, like our work on a React compiler.

16.3 release blog draft #587

16.3 release blog draft #587

Uh oh!

Conversation

bvaughn commented Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

reactjs-bot commented Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gaearon Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bvaughn commented Feb 6, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bvaughn commented Feb 7, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon left a comment

Choose a reason for hiding this comment

bvaughn commented Feb 5, 2018 •

edited

Loading

reactjs-bot commented Feb 5, 2018 •

edited

Loading

gaearon Feb 5, 2018 •

edited

Loading

gaearon Feb 5, 2018 •

edited

Loading

gaearon Feb 5, 2018 •

edited

Loading

gaearon Feb 5, 2018 •

edited

Loading

gaearon Feb 5, 2018 •

edited

Loading

gaearon Feb 5, 2018 •

edited

Loading

gaearon Feb 5, 2018 •

edited

Loading

gaearon Feb 5, 2018 •

edited

Loading

bvaughn commented Feb 12, 2018 •

edited

Loading

bvaughn Feb 13, 2018 •

edited

Loading

bvaughn Feb 13, 2018 •

edited

Loading