-
Notifications
You must be signed in to change notification settings - Fork 7.7k
16.3 release blog draft #587
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Deploy preview for reactjs ready! Built with commit aa9810f |
|
||
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! | ||
|
||
Read on to learn more about the release! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Second sentence with an exclamation point in a sequence, maybe soften one of them?
|
||
This release includes a new class component lifecycle (`getDerivedStateFromProps`), a new `StrictMode` component, and an official context 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
[Learn more about the `StrictMode` component here.](#) | ||
|
||
## Official Context API |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd put this section first because it's more exciting than deprecations
|
||
> **Note:** | ||
> | ||
> Deprecation warnings will be enabled in version 16.4, **but the deprecated lifecycles will continue to work until version 17**. After version 17, only the new "UNSAFE_" lifecycles will work. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+
"We have created an [automatic script] that prefixes the lifecycle names with the "UNSAFE_" prefix"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Odd punctuation: leaks- (somethin
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should have been an em dash. Will fix.
|
||
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. | ||
|
||
Many of these issues are exacerbated by a subset of the component lifecycles (`componentWillMount`, `componentWillReceiveProps`, and `componentWillUpdate`). For this reason, we have decided to deprecate those methods. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe:
Many of these issues are exacerbated by a subset of the component lifecycles (
componentWillMount
,componentWillReceiveProps
, andcomponentWillUpdate
). 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.
> | ||
> `StrictMode` checks are run in development mode only; they do not impact the production build. | ||
|
||
Although it is not possible for strict mode to catch all problems (eg mutation), it can help with many. If you see warnings in strict mode, those things will likely cause bugs for async rendering. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"e.g."
> `StrictMode` checks are run in development mode only; they do not impact the production build. | ||
|
||
Although it is not possible for strict mode to catch all problems (eg mutation), it can help with many. If you see warnings in strict mode, those things will likely cause bugs for async rendering. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think mentioning "mutation" as a problem is going to seriously worry MobX users. What is our messaging here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure. I can soften this? ("certain types of mutations")
|
||
Although it is not possible for strict mode to catch all problems (eg mutation), it can help with many. If you see warnings in strict mode, those things will likely cause bugs for async rendering. | ||
|
||
In version 16.3, `StrictMode` helps with two things: identifying unsafe lifecycles and detecting unexpected side effects. Additional functionality will be added with future releases of React. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"for async rendering" — we still haven't explained what it is and why anyone should care
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Added a section about the |
@@ -3,7 +3,7 @@ title: "React v16.3.0: New lifecycles and context" | |||
author: [bvaughn] | |||
--- | |||
|
|||
This release includes a new class component lifecycle (`getDerivedStateFromProps`), a new `StrictMode` component, and an official context API! | |||
This release includes a new class component lifecycle (`getDerivedStateFromProps`), a new `StrictMode` component, an official context API, and a better way for managing refs! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
“Better” might imply you have to convert from functional refs.
Maybe “and a new ergonomic ref API”.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I dig it.
|
||
Version 16.3 adds a new option for managing refs that offers the convenience of a string ref without any of the downsides: | ||
`embed:16-3-release-blog-create-ref.js` | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
@@ -0,0 +1,19 @@ | |||
class MyComponent extends React.Component { | |||
// highlight-next-line | |||
_divRef = React.createRef(); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: we don’t use the underscore convention elsewhere in the docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Gotcha. Long time habit.
9b65182
to
ab62e88
Compare
Rebased on master with the new Prettier config width. |
|
||
## 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! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Hm. I already changed the only occurrence of "deprecated lifecycles" to "legacy lifecycles". Do you see one I missed? |
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" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Solid post.
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/some changes will be/some long-term changes will be/ maybe?
|
||
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! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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!
|
||
> **Note** | ||
> | ||
> The old context API will keep working for all React 16 minor releases, so you will have time to migrate. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"all React 16.x releases"? In case "minor" isn't universally clear.
|
||
## 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! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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."
> 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. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What's the upgrade path? Is there a codemod?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. 😄
> | ||
> 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/After version 17/Even in version 17/
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Love it.
Context updates
Thanks Alex. I've merged your PR into this branch. |
content/docs/context.md
Outdated
super(props); | ||
this.state = {type:'desktop'}; | ||
} | ||
## Caveats |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll add this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Context comes before the Higher-Order Components reference page, but I'll cross link.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, cyclical dependencies are pretty much unavoidable in the "Advanced" section
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. |
content/docs/state-and-lifecycle.md
Outdated
@@ -251,7 +251,7 @@ Note how we save the timer ID right on `this`. | |||
|
|||
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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sounds good.
The above sentence can also change to
While
this.props
is set up by React itself andthis.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).
content/docs/context.md
Outdated
@@ -134,6 +136,16 @@ One issue with the render prop API is that refs don't automatically get passed t | |||
|
|||
## Caveats | |||
|
|||
### `Consumer` Inline Function as a Child | |||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Bye bye
@@ -0,0 +1,15 @@ | |||
class Example extends React.Component { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Bye
@@ -0,0 +1,15 @@ | |||
class Example extends React.Component { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Bye
Formatted 16.3 release blog post link
Formatted "strict mode"
Formatted "Refs and the DOM"
Formatted "Forwarding Refs"
Formatted
React.forwardRef
API referenceFormatted HOC caveats section
Formatted Context API docs