RFC 6: Deprecate unsafe lifecycles

[bvaughn]

This codemod corresponds with reactjs/rfcs/pull/6, reactjs/react-codemod/pull/195, and #12036.

Proposed Release Plan

• 16.3: Add new lifecycles.
• 16.4: Warn about old lifecycles being deprecated. (Enable warnAboutDeprecatedLifecycles feature flag).
• 17.0: Remove deprecated lifecycles.

The minor version numbers for 16 are just examples. The main point is to note that we plan to release this change over two minor updates, to give libraries a chance to update without noisy deprecation warnings.

Differences from RFC

This proposal differs from the original RFC in a couple of ways. I have updated the RFC to reflect these changes, but they are also listed below:

• getDerivedStateFromNextProps has been renamed to getDerivedStateFromProps (reactjs/rfcs/pull/6/commits/8f6c20e)
• getDerivedStateFromProps will be called after instantiation. In this case, prevState will either be null or the value set in the constructor. Any state returned from getDerivedStateFromProps will be merged into the previous state, overriding it. (reactjs/rfcs/pull/6/commits/e05e317)
• getDerivedStateFromProps will not accept a prevProps parameter. Its signature will be: static getDerivedStateFromProps(props: Props, prevState: State | null): PartialState | null (reactjs/rfcs/pull/6/commits/e05e317)
• The unsafe_* prefix will actually be UNSAFE_* (capitalized) to make it more noticeable. (reactjs/rfcs/pull/6/commits/7042a2a)

Open Questions

• Is it okay that some inline comments (eg here) and strings (eg here and here) still refer to the old lifecycle names:
  Decision: Yes. These can be incrementally replaced if necessary.
• Should startPhaseTimer calls use new lifecycle prefix?
  Decision: No, the old names are okay.
• Should invariants referencing the old lifecycle name (sans prefix) be updated?
  Tentative decision: No. The meaning of these messages is clear enough that this is not worth the pain it would cause WRT white-listing.
• Is it worth releasing an update to create-react-class/factory so:
  It's aware of the new lifecyle methods?
  Tentative decision: Yes. This is fairly low-effort and worth the cost to keep create-react-class working. (PR RFC 6: createReactClass updates #12036)
• Should we release an update to 15 with the new UNSAFE_* lifecycle hooks as well?
  Decision: No. Instead, we will release a backwards-compatible polyfill for library authors. (See reactjs/react-lifecycles-compat.)

Remaining Work

• Invoke either either old lifecycles or new unsafe_* ones (e709e30)
• Add deprecation warnings for old lifecycle names (e709e30)
• Create codemod (Add rename-unsafe-lifecycles codemod reactjs/react-codemod#195) and rename lifecycles (28a0e4b, f0e6f62, d9e0d48)
• Update NativeMethodsMixin with new lifecycle hooks (8679926)
• Manually audit repo and update comments and inline strings
• Rename unsafe_ to uppercase UNSAFE_. (8d0e001)
• Implement new static getDerivedStateFromProps method.
  • For server-side rendering (5d51854, 035c220)
  • For shallow renderer (1047182)
  • For all other renderers via ReactFiberClassComponent (b71ca93)
• Verify we have new test coverage for all of the following:
  • Ensure the old lifecycles are invoked and log the correct warnings (5d51854, 035c220, 1047182, b71ca93)
  • Cover the new static getDerivedStateFromProps method (5d51854, 035c220, 1047182, b71ca93)
  • Verify that we warn about misspelled UNSAFE_componentWillReceiveProps (09c39d0)
  • gDSFP works for createReactClass components (286df77, 68f2fe7)
• Add DEV warning to functional components that define a static getDerivedStateFromProps method (re this comment). (b699543)
• Put lifecycle deprecation warnings behind a feature flag. (This will enable us to do a minor release that adds the new UNSAFE_* methods, but without any warnings, giving the ecosystem time to upgrade without noise.) (2d9f75d)

Follow Up Work

• Coalesce warnings for deprecated lifecycle hooks #12044: Coalesce warnings for deprecated lifecycle hooks and print single message after reconciliation (rather than one per component-type)
• Update debugRenderPhaseSideEffects behavior #12046: Update debugRenderPhaseSideEffects behavior.
• Write reactjs.org blog posts:
  • Write blog post about new async UNSAFE_ and static lifecycles #12047: For 16.3: Letting people know how to prepare for upcoming 16.4 release
    • App developers should run codemod.
    • Library maintainers should move code to render.
  • Write blog post showing recommended, async-safe coding patterns #12048: For 16.4+: Show examples of how to use the new API, pointing out tricky things to avoid (eg setTimeout calls to setState), etc.

[TrySound]

@bvaughn Would be good to have a warning on SFC with static getDerivedStateFromProps.
reactjs/rfcs#6 (comment)

[jquense]

Ya! I know we talk about this on every depreciation but...this will affect every react component, releasing on a minor means CI is going to break for folks and the burden to fix quickly will be on lib maintainers unless they want to deal with a flood of issues about the depreciation warnings. The most graceful approach for maintainers would be to deprecate in 17 and remove in 18

[gaearon]

We do talk about this every time. :-)

Last time we settled on making those warnings yellow rather than red. It is up to you to decide whether console.warn should fail the build. You can also filter specific warnings if you want to.

In this case we also plan to not include the deprecations in the first minor, give time to major libraries to update without noise, and later enable them. (As written in the RFC)

I don't think what you propose is feasible. We can't stretch this work into two years. (And our release cycle is roughly yearly.)

[jquense]

Yeah sorry, I don't mean to keep rehashing this, during the v15 deprecation we also said the goal was to try and have faster major release cycles post v16 so we weren't waiting two years rm warnings, did that plan get squashed?

Again, respectfully, I'm sorry to rehash but I also feel the result of this as a maintainer of many react things and it's the most unpleasant part of working in the React OSS ecosystem for me

[gaearon]

I totally understand that.

I think an important thing to consider here is the incentives. I don't think we can just tell people to update their component, and not get something in return in the next major. It feels like empty effort.

Even if we released majors faster, React 17-that-just-deprecates-some-methods wouldn’t be an exciting upgrade. We haven’t been in this situation before because every major release of React included significant improvements and/or new capabilities that made the migration worth it.

If React 17 is not appealing on its own merits, we risk fragmenting the ecosystem where a much higher percentage of people decides not to upgrade and wait out until making those changes is truly worth it. And at that point you have pretty much the same situation as now, except that there was an extra churning major release in the middle.

Unfortunately pretty much all of the things that we’re working on to make React 17 exciting need those changes. And we need to start this migration as early as we can because we know those hooks are problematic and get in the way.

Of course we could call the upcoming 16.3 a “17.0”. But I don’t see the point. The projects using 16 today will keep working. If it’s just about CIs, again, this is completely avoidable and depends on your CI setup. If it’s about the migration cost, we understand it but don’t see a way to avoid it.

[rizoom]

Any rough estimates for React 17 release date? Thanks.

[gaearon]

@rizoom You can see the history of last major releases by our blog and extrapolate. Generally it takes from 8 months to a year to do a major release.

[bvaughn]

Yeah, @jamsch. That was mentioned in the RFC, but here is a more complete example in a blog post I'm working on:

https://deploy-preview-596--reactjs.netlify.com/blog/2018/02/07/update-on-async-rendering.html#updating-state-based-on-props