Release Process (0.75 and later)

Note

This documents the steps to releasing a stable React Native release.

Release candidates will generally follow the same steps but have some pre and post work, depending on if you're cutting, doing a patch, or promoting a release candidate to stable.

Follow the dedicated release candidate guide for more detail.

Release steps

These steps apply when making a patch release or an incremental release candidate.

Step 1: Check out release branch locally

From your local facebook/react-native clone, check out the relevant release branch. Make sure your system is set up with the right tooling dependencies for the release. e.g. you may need to switch Node versions.

# Fetch new commits and tags (to prep for any cherry-picks)
git fetch --all --tags

# Check out release branch
git switch <release-branch> # e.g. 0.75-stable

# OR, if checking out a release branch for the first time
git switch -c <release-branch> upstream/<release-branch>

Step 2: Action cherry-picks and pull requests

New changes targeting a given release need to be replicated from main onto the release branch, via either a cherry-pick or pull request. See also Releases Support Policy.

# Make sure to update the release branch
git pull

# Cherry-pick relevant commits
git cherry-pick <commit-on-main>

Warning

For any pick requests or merge requests for Hermes, notify a Meta Release Crew member. They'll need to publish and pick the Hermes release into the release branch. Do not proceed past step 3 until the the branch has been updated with the Hermes release.

Step 3: Wait for Github Actions artifacts to build

Once all picks are complete, push your changes to the remote release branch.

git push

This will kick off a Github Action workflow called "Test All" that will build relevant artifacts (Hermes prebuilts, RNTester.apk) that will expedite local testing.

Navigate to Github Actions and wait for the build_npm_package job to complete successfully. If the job fails, try and fix the issue so that artifacts build.

Important

Release testing will only use the artifacts from the last workflow that ran on your release branch! This means that if you push more changes to your release branch, you must wait for it to complete the build_npm_package job again to use those artifacts in testing.

The takeaway here is to try and avoid pushing more commits to CI at this point. Otherwise, you'll have to wait for CI to build the assets again to use them in your testing.

See Github Actions Artifacts for more details.

Step 4: Test the release

Follow the Release Testing guide. Ideally, we should have 2 Release Crew members test the release. Coordinate with another Release Crew member to do a second pass.

There may be exceptional cases where we can bypass 2 release tests or only do selective tests, based on circumstances. Ensure a Meta Release Crew member is aware and approves.

Step 5. Create release

Starting from React Native 0.75, a new release is created using a Github Action workflow called Create Release.

The workflow requires 4 parameters:

The branch we need to use to cut the release. Make sure to set it to your stable branch. e.g.: 0.75-stable
The version we want to publish. For example, 0.75.0-rc.0.
Check the latest checkbox, if you are publishing a patch on the latest version.
The last checkbox is for a dry-run. If you need to run a release, keep it unchecked.

This runs the Create Release workflow. It'll sync package versions (publish-bumped-packages.yml), commit and publish a tag (create-release.yml):

The new tag will then launch a Publish Release (publish-release.yml) workflow which builds and publishes the react-native npm package artifact:

Step 6: Verify Release

Once all workflows above are complete, verify the following:

Verify npm publishes

Verify that react-native is published on npm with the correct tag.

npm view react-native

# Also verify that one or more subpackages are published
npm view @react-native/codegen

Init a new template app

Sanity check by initializing a new project and running for Android and iOS.

npx @react-native-community/cli@latest init ReactNative<YOUR_VERSION> --version <YOUR_VERSION>

Tip

Keep this project around somewhere incase you need to repro something on this version.

Backup: How do I manually create a template for this version?

Run the Release workflow, making sure you use the correct branch. For example with the 0.76.* releases you would use the 0.76-stable branch:

Verify Upgrade Helper is updated

The publish_release job should also trigger the rn-diff-purge GitHub action (link). This action will update the Upgrade Helper with a diff of your latest release patch. Verify your release is visible in the dropdown.

Common Issues:

Why can't I see the upgrade helper diff between last set of releases, e.g. 0.75.4 → 0.76.0-rc.3?

Cause:

rn-diff-purge has to be run in order. That means 0.75.4 must be run before 0.76.0-rc.3.

Fix:

I'm going to use the above versions as examples, replace with your affected versions.

Delete the tags:

git push --delete origin 0.75.4
git push --delete origin 0.76.0-rc.3

Delete the versions from RELEASES
Manually publish by calling the Github action in order: 0.75.4 first then 0.76.0-rc.3
Confirm this is fixed: https://react-native-community.github.io/upgrade-helper/?from=0.75.4&to=0.76.0-rc.3

Manually Publish: How do I add an entry in the Upgrade Helper for this version?

If there is a failure and you manually want to add your new tag to the `upgrade helper`, use:

export GITHUB_TOKEN=<your token>
export NEW_VERSION="v0.76.0-rc.3" # Should be prefixed with a 'v'
curl -X POST https://api.github.com/repos/react-native-community/rn-diff-purge/dispatches \
            -H "Accept: application/vnd.github.v3+json" \
            -H "Authorization: Bearer $GITHUB_TOKEN" \
            -d "{\"event_type\": \"publish\", \"client_payload\": { \"version\": \"$NEW_VERSION\" }}"

Verify assets have been uploaded to Maven

Verify release assets are uploaded to Maven for your release.

Note, this may take a moment to update. Later, we will link to some of these artifacts in the release notes.

https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/<YOUR_VERSION>/react-native-artifacts-<YOUR_VERSION>-hermes-framework-dSYM-debug.tar.gz
https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/<YOUR_VERSION>/react-native-artifacts-<YOUR_VERSION>-hermes-framework-dSYM-release.tar.gz

Backup: Script to verify this?

export NEW_VERSION="v0.76.0-rc.3" # Should be prefixed with a 'v'
export VERSION=${NEW_VERSION#v}
curl -I https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/$VERSION/react-native-artifacts-$VERSION-hermes-framework-dSYM-debug.tar.gz
curl -I https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/$VERSION/react-native-artifacts-$VERSION-hermes-framework-dSYM-release.tar.gz

Step 7: Generate the changelog PR

Now we need to update the CHANGELOG.md file at the react-native repo root.

Note

Changelog commits must be submitted to the main branch.

export NEW_VERSION="v0.76.0-rc.3" # Should be prefixed with a 'v'
# Check out `main` branch
git switch main

# Pull new tags
git fetch --all --tags
git pull

# Generate the changelog
npx @rnx-kit/rn-changelog-generator \
  --base v<LATEST_STABLE_OR_RC>\
  --compare $NEW_VERSION \
  --repo . \
  --changelog ./CHANGELOG.md
  --token $GITHUB_TOKEN

You'll likely need to reformat the generated CHANGELOG.md changes and reorder the heading to keep the latest release ordering. Once done, create a PR with your changes against main.

Step 8: Create the GitHub Release

Create a new GitHub release.

Set the release tag to the newly created tag.
Set the title to the release version (without preceding "v").
Set release type:
- Select "Set as a pre-release" if you releasing a release candidate.
- Select "Set as the latest release" if you releasing a patch for the latest version.
Copy and paste the following template and update TODOs.

<!-- TODO Copy and paste your formatted Changelog generated here. -->

---

<!-- TODO Update these links for your release version -->
Hermes dSYMS:
- [Debug](https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/<YOUR_VERSION>/react-native-artifacts-<YOUR_VERSION>-hermes-framework-dSYM-debug.tar.gz)
- [Release](https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/<YOUR_VERSION>/react-native-artifacts-<YOUR_VERSION>-hermes-framework-dSYM-release.tar.gz)

---

You can file issues or pick requests against this release [here](https://github.com/reactwg/react-native-releases/issues/new/choose).

---

To help you upgrade to this version, you can use the [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) ⚛️.

---

View the whole changelog in the [CHANGELOG.md file](https://github.com/facebook/react-native/blob/main/CHANGELOG.md).

Step 9: Communicate Release

Send a message in the Core Contributors Discord #release-coordination channel about the new release.

📢 0.X.Y release is out!

📦 https://github.com/facebook/react-native/releases/tag/v0.X.Y
📝 https://github.com/facebook/react-native/pull/<your-changelog-pr>

Step 10: Update Podfile.lock on the release branch

Everytime we release a new version, there is a new hermes-engine version published. We need to update packages/rn-tester to use this new version. This is in preparation for the next release from this branch.

# Check out release branch
git switch <release-branch>

# Pull new changes (should include release commit from CI)
git reset --hard origin/<release-branch>

# Head to rn-tester package and update pods
rm -rf packages/react-native-codegen/lib
(cd packages/rn-tester && bundle exec pod update hermes-engine --no-repo-update)

# Commit only changes to packages/rn-tester/Podfile.lock
git add packages/rn-tester/Podfile.lock
git commit -m "Update Podfile.lock" -m "Changelog: [Internal]"
git push

Step 11: Update GitHub Project

Make sure you've updated the status of completed and ongoing tasks in the relevant GitHub project. Unresolved items can be assigned to the following release.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

guide-release-process-0.75.md

guide-release-process-0.75.md

Release Process (0.75 and later)

Release steps

Step 1: Check out release branch locally

Step 2: Action cherry-picks and pull requests

Step 3: Wait for Github Actions artifacts to build

Step 4: Test the release

Step 5. Create release

Step 6: Verify Release

Verify npm publishes

Init a new template app

Verify Upgrade Helper is updated

Cause:

Fix:

Verify assets have been uploaded to Maven

Step 7: Generate the changelog PR

Step 8: Create the GitHub Release

Step 9: Communicate Release

Step 10: Update Podfile.lock on the release branch

Step 11: Update GitHub Project

Files

guide-release-process-0.75.md

Latest commit

History

guide-release-process-0.75.md

File metadata and controls

Release Process (0.75 and later)

Release steps

Step 1: Check out release branch locally

Step 2: Action cherry-picks and pull requests

Step 3: Wait for Github Actions artifacts to build

Step 4: Test the release

Step 5. Create release

Step 6: Verify Release

Verify npm publishes

Init a new template app

Verify Upgrade Helper is updated

Cause:

Fix:

Verify assets have been uploaded to Maven

Step 7: Generate the changelog PR

Step 8: Create the GitHub Release

Step 9: Communicate Release

Step 10: Update Podfile.lock on the release branch

Step 11: Update GitHub Project