Skip to content

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

Merged
merged 118 commits into from
Mar 29, 2018
Merged

Conversation

bvaughn
Copy link
Contributor

@bvaughn bvaughn commented Feb 5, 2018

@reactjs-bot
Copy link

reactjs-bot commented Feb 5, 2018

Deploy preview for reactjs ready!

Built with commit aa9810f

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


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!
Copy link
Member

@gaearon gaearon Feb 5, 2018

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.
Copy link
Member

@gaearon gaearon Feb 5, 2018

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.

Copy link
Contributor Author

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.

Copy link
Member

@gaearon gaearon Feb 5, 2018

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
Copy link
Member

@gaearon gaearon Feb 5, 2018

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.
Copy link
Member

@gaearon gaearon Feb 5, 2018

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"

Copy link
Member

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.

Copy link
Contributor Author

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.

Copy link
Member

@gaearon gaearon Feb 5, 2018

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.

Copy link
Contributor Author

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.
Copy link
Member

Choose a reason for hiding this comment

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

Odd punctuation: leaks- (somethin

Copy link
Contributor Author

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.
Copy link
Member

@gaearon gaearon Feb 5, 2018

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, 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.

>
> `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.
Copy link
Member

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.

Copy link
Member

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?

Copy link
Contributor Author

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.
Copy link
Member

@gaearon gaearon Feb 5, 2018

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

Copy link
Contributor Author

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.

@bvaughn
Copy link
Contributor Author

bvaughn commented Feb 6, 2018

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

@@ -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!
Copy link
Member

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”.

Copy link
Contributor Author

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`

Copy link
Member

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();
Copy link
Member

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Gotcha. Long time habit.

@bvaughn bvaughn mentioned this pull request Feb 6, 2018
2 tasks
@bvaughn bvaughn force-pushed the 16.3-release-blog-post branch from 9b65182 to ab62e88 Compare February 7, 2018 17:25
@bvaughn
Copy link
Contributor Author

bvaughn commented Feb 7, 2018

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!
Copy link
Member

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.

Copy link
Member

@gaearon gaearon left a 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.

@bvaughn
Copy link
Contributor Author

bvaughn commented Feb 12, 2018

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
Copy link
Contributor Author

bvaughn commented Feb 12, 2018

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"

Copy link
Member

@sophiebits sophiebits left a 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.
Copy link
Member

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!
Copy link
Member

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?

Copy link
Contributor Author

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?

Copy link
Contributor Author

@bvaughn bvaughn Feb 13, 2018

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.
Copy link
Member

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!
Copy link
Member

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.

Copy link
Member

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?

Copy link
Contributor Author

@bvaughn bvaughn Feb 13, 2018

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.

Copy link
Member

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.

Copy link
Contributor Author

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.
Copy link
Member

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.
Copy link
Member

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Love it.

@bvaughn bvaughn added the 16.3 label Feb 22, 2018
@alexkrolick
Copy link
Collaborator

@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.

@bvaughn
Copy link
Contributor Author

bvaughn commented Mar 23, 2018

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

super(props);
this.state = {type:'desktop'};
}
## Caveats
Copy link
Member

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'll add this.

Copy link
Contributor Author

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.

Copy link
Member

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

@bvaughn
Copy link
Contributor Author

bvaughn commented Mar 29, 2018

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.

@@ -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).
Copy link
Member

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?

Copy link
Contributor Author

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?

Copy link
Member

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 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).

@@ -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

Copy link
Member

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 {
Copy link
Member

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 {
Copy link
Member

Choose a reason for hiding this comment

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

Bye

@bvaughn bvaughn merged commit b618684 into reactjs:master Mar 29, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

10 participants