Branch Cut & RC0

info

Documents in this section go over steps to run different types of React Native release updates. Its intended audience is those in relevant release roles.

Pre-requisites

Write access to react-native repository.
Write access to hermes repository.
Write access to releases repository.
One CircleCI personal API token - see here how to set one.

1. Creating a new release branch

Create the release branch in react-native repo with the appropriate name (usually 0.XX-stable).
```
git checkout main
git pull origin main
git checkout -b 0.69-stable
```

2. Update the Hermes version

Head to the Publish Tag workflow in the Hermes repo. Click the "Run Workflow" button and input the RN stable version you are targeting (e.g. 0.69.0). You need to have write access to the facebook/hermes repo to do so or ask a Meta employee to help you on this step.

Bump the Hermes version on the release branch using this command:

# Replace <the_hermes_tag> with the tag that will look like 'hermes-2022-07-20-RNv0.70.0-bc97c5399e0789c0a323f8e1431986e207a9e8ba'
./packages/react-native/scripts/hermes/bump-hermes-version.js -t <the_hermes_tag>

Add and commit the extra file that got created at packages/react-native/sdks/hermes/.hermesversion.

3. Bump monorepo packages

Update packages in the monorepo by running yarn bump-all-updated-packages. Bear in mind that all the package bumps must be on patch level, and be on the minor you are working on. We need to publish the latest package changes so they will be included in RC0. Read more about the script and how they work here.
CI will take care of releasing the new versions on npm once you push the changes to the 0.XX-stable branch.

4. Push the branch and test the current changes

You can now push the branch you created so that others can also start testing:

git push origin 0.69-stable

Before continuing further, follow the testing guide to ensure the code doesn't have any major issues.

info

Since testing is a time consuming activity (>1 hrs) it is recommended that the release crew coordinates on the steps above then do testing on at least two separate systems in an async way.

5. Kick off the build of 0.{minor}.0-rc.0

Once you're done with the testing, you can kick-off the bump and publishing of RC0:

# This will walk you through what version you are releasing
./scripts/bump-oss-version.js --to-version 0.69.0-rc.0 --token <YOUR_CIRCLE_CI_TOKEN>

Once you have run that script, head to CircleCI and you should see under the releases workflow, a prepare-package-for-release job.
CircleCI showing publish release.
This script runs and commits any changes and triggers a deploy job, build_and_publish_npm_package.
Note: Look under "All Branches" to find the publish job. CircleCI does not give a way to search for these jobs.
Once complete you should be able to run npm view react-native and verify that under the next tag, the version is the expected release version.
```
npm view react-native
...
dist-tags:
latest: 0.68.1            next: 0.69.0-rc.0         nightly: 0.0.0-f617e022c
```
Hermes artifacts will be uploaded to the Maven repository. It might take ~20 minutes for Maven to process them.

6. Create a PR of the changelog using the generator

To generate the changelog, we rely on a dedicated tool called @rnx-kit/rn-changelog-generator that will parse the custom changelog messages that contributors write in their PRs.

# Run following with the stable release as base, and your rc.0 version
npx @rnx-kit/rn-changelog-generator --base v[LATEST_STABLE]--compare v[YOUR_RC_0] \
--repo ~/react-native --changelog ~/react-native/CHANGELOG.md

# example against 0.68.2 and 0.69.0-rc.0
npx @rnx-kit/rn-changelog-generator --base v0.68.2 --compare v0.69.0-rc.0 \
--repo ~/react-native --changelog ~/react-native/CHANGELOG.md

Create a pull request of this change to react-native repo and add the Changelog label.

Manually Adjust the Changelog

At the end of the generated Changelog, there could be two additional sections: the Failed to Parse section and the Unknown section.

The Failed to Parse section contains commits that has a ## Changelog: entry in their summary but, due to typos or other problems, the tool was not able to parse and automatically attribute them to the right section.

The Unknown section is populated with commit that landed without the ## Changelog: entry in the summary.

For both these categories, we have to manually go through the listed commits and move them to the right section, based on the actual change they introduce. The following are a set of heuristic we follow to manually update the changelog:

Commit of internal changes can be deleted from the Changelog.
- Examples: commit on BUCK files or code refactoring that do not change behaviours or interfaces
Commit which bumps dependencies should be moved to the Changed section
- For each dependency, there should be a single entry with the most recent bump. Commits that bumps the dependencies to lower versions can be removed

7. Create a GitHub Release

Create a GitHub Release with this template and check "Pre-Release" checkbox.

- <!-- TODO List out notable picks for this patch -->

---

To test it, run:

<!-- TODO Update with your version -->

npx react-native init RN069RC0 --version 0.69.0-rc.0

---

- You can participate in the conversation on the status of this release in the [working group](https://github.com/reactwg/react-native-releases/discussions).

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

- See changes from this release in the [changelog PR](https://github.com/facebook/react-native/labels/%F0%9F%93%9D%20Changelog)

---

### Help us testing 🧪

<!-- TODO Add the call to action for something specific that we want folks to test -->

Let us know how it went by posting a comment in the [working group discussion](https://github.com/reactwg/react-native-releases/discussions)! Please specify with system you tried it on (ex. macos, windows).

**Bonus points:** It would be even better if you could swap things around: instead of using a fresh new app, use a more complex one - or use a different library that is already leveraging the new architecture!

8. Upload prebuilt Hermes binary

In the publish_release CI workflow, the build_hermes_macos step produces a tmp/hermes/output/hermes-runtime-darwin-vx.y.z.tar.gz artifact, for example here are the artifacts for 0.69.0 release. Download it and attach it to the GitHub release.

9. Create a tracking discussion post

Create a "Road to <YOUR_MINOR_VERSION>" discussion post in the react-native-releases working group:

<!-- Title: Road to <YOUR_VERSION> -->

The branch cut has happened.

## Notice

<!-- TODO update the version -->

- [Current release candidate: 0.69.0-rc.0][current-release]
- Have an issue with current release candidate? [File an issue][issue-form] and we will triage.
- Have a pick request for this release? Does it fall under our [pick request qualifications][release-faq]? If so please create a PR against the release branch and comment with the PR link
- If you are release testing, copy and fill a [test checklist](/contributing/release-testing#test-checklist).

#### Highlighted Changes in this release

<!-- Add stand-out changes in this release, and link to changelog PR.  -->

- Checkout this [Changelog PR][changelog-pr]

## [Release Process][release-processes]

#### Checklist

- [ ] [Changelog PR][changelog-pr]
- [ ] Start a Google doc of blog post for release ([start from this skeleton](https://docs.google.com/document/d/1MP6AT-SX_qBrngOKRDbDoUIc_U2qhWq5L4dqgkLkd5Y/edit?usp=sharing)) and invite contributors of release highlights to expand
- [ ] Follow up on [release dependencies][release-dependencies]
  > When ready to publish stable
- [ ] Ship changelog
- [ ] Ship blog post
- [ ] Prepare typescript PR (see https://github.com/DefinitelyTyped/DefinitelyTyped/pull/60929)
- [ ] Make PR to `react-native-website` with the new version cut ([see docs](https://github.com/facebook/react-native-website#cutting-a-new-version))

#### Retrospective Topics

<!-- List out pain points, issues to investigate that are not release-blocking to follow up on -->

-

## Release Status

### Tracking 0.69.0-rc.1

#### Blocking issues for releasing 0.69.0-rc.1

-

#### Picks for 0.69.0-rc.1

-

<!--
once an RC is released, wrap this section like so

<details>
<summary>
Tracking 0.69.0-rc.1 (released ✅)
</summary>
#### Blocking issues for releasing 0.69.0-rc.1

-

#### Picks for 0.69.0-rc.1

-
</details>
-->

[changelog-pr]: https://github.com/facebook/react-native/labels/%F0%9F%93%9D%20Changelog
[current-release]: https://github.com/facebook/react-native/releases
[changelog-wiki]: https://reactnative.dev/contributing/changelogs-in-pull-requests
[release-dependencies]: https://reactnative.dev/contributing/release-dependencies
[release-faq]: https://reactnative.dev/contributing/release-faq
[issue-form]: https://github.com/facebook/react-native/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Cpre-release&template=release_blocker_form.yml
[releases]: https://github.com/facebook/react-native/releases
[release-processes]: https://reactnative.dev/contributing/overview
[upgrade-helper]: https://reactnative.dev/contributing/updating-upgrade-helper

After creating it, make sure to link it in the relevant GitHub Release you created above, and to pin it in the discussion repo.

10. Verify that Upgrade Helper GitHub action has fired

You should see a new publish job here.
Once it has finished, you should be able to see that the Upgrade Helper presents the option to target the new RC0.
If not, check out the guide on how to update Upgrade Helper.

11. Broadcast that release candidate is out

Once all the steps above have been completed, it's time to signal to the community that RC0 is available for testing! Do so in the following channels:

@reactnative on twitter
RN Discord #releases-coordination

12. Bump minor version of all monorepo packages in `main`

The packages in the react-native monorepo must always be one minor version ahead of the latest or RC version (e.g. if you have cut 0.72-stable, main needs to be in 0.73.x. Once you're done with releasing the initial RC0, you should:

Create a new branch in react-native from main in your own fork.
Run yarn bump-all-updated-packages --release-branch-cutoff to bump the minor versions of all packages.
Create a PR targeting main in react-native with the commit created by the previous command.

Pre-requisites​

1. Creating a new release branch​

2. Update the Hermes version​

3. Bump monorepo packages​

4. Push the branch and test the current changes​

5. Kick off the build of 0.{minor}.0-rc.0​

6. Create a PR of the changelog using the generator​

Manually Adjust the Changelog​

7. Create a GitHub Release​

8. Upload prebuilt Hermes binary​

9. Create a tracking discussion post​

10. Verify that Upgrade Helper GitHub action has fired​

11. Broadcast that release candidate is out​

12. Bump minor version of all monorepo packages in main​