Skip to content
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

Add unstable prefix to experimental APIs #18825

Merged
merged 1 commit into from
May 5, 2020

Conversation

acdlite
Copy link
Collaborator

@acdlite acdlite commented May 5, 2020

We've been shipping unprefixed experimental APIs (like createRoot and useTransition) to the Experimental release channel, with the rationale that because these APIs do not appear in any stable release, we're free to change or remove them later without breaking any downstream projects.

What we didn't consider is that downstream projects might be tempted to use feature detection:

const useTransition = React.useTransition || fallbackUseTransition;

This pattern assumes that the version of useTransition that exists in the Experimental channel today has the same API contract as the final useTransition API that we'll eventually ship to stable.

To discourage feature detection, I've added an unstable_ prefix to all of our unstable APIs.

The Facebook builds still have the unprefixed APIs, though. We will continue to support those; if we make any breaking changes, we'll migrate the internal callers like we usually do. To make testing easier, I added the unstable_-prefixed APIs to the www builds, too. That way our tests can always use the prefixed ones without gating on the release channel.

We've been shipping unprefixed experimental APIs (like `createRoot` and
`useTransition`) to the Experimental release channel, with the rationale
that because these APIs do not appear in any stable release, we're free
to change or remove them later without breaking any downstream projects.

What we didn't consider is that downstream projects might be tempted to
use feature detection:

```js
const useTransition = React.useTransition || fallbackUseTransition;
```

This pattern assumes that the version of `useTransition` that exists in
the Experimental channel today has the same API contract as the final
`useTransition` API that we'll eventually ship to stable.

To discourage feature detection, I've added an `unstable_` prefix to
all of our unstable APIs.

The Facebook builds still have the unprefixed APIs, though. We will
continue to support those; if we make any breaking changes, we'll
migrate the internal callers like we usually do. To make testing easier,
I added the `unstable_`-prefixed APIs to the www builds, too. That way
our tests can always use the prefixed ones without gating on the
release channel.
@facebook-github-bot facebook-github-bot added CLA Signed React Core Team Opened by a member of the React Core Team labels May 5, 2020
@codesandbox-ci
Copy link

codesandbox-ci bot commented May 5, 2020

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 9fe4075:

Sandbox Source
reverent-dream-uoerx Configuration

@sizebot
Copy link

sizebot commented May 5, 2020

No significant bundle size changes to report.

Size changes (experimental)

Generated by 🚫 dangerJS against 9fe4075

@sizebot
Copy link

sizebot commented May 5, 2020

No significant bundle size changes to report.

Size changes (stable)

Generated by 🚫 dangerJS against 9fe4075

@leonardodino
Copy link

created a documentation update issue:
reactjs/react.dev#2960

Please close the issue if the team think it's best to avoid this change 😄

smmoosavi added a commit to kgolezardi/Performance-Review-Web that referenced this pull request May 17, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed React Core Team Opened by a member of the React Core Team
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants