|
| 1 | +# Release Process (0.74 and later) |
| 2 | + |
| 3 | +> [!Note] |
| 4 | +> This documents the steps to releasing a stable React Native release. |
| 5 | +> |
| 6 | +> 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. |
| 7 | +> |
| 8 | +> Follow the dedicated release candidate [guide](./guide-release-candidate.md) for more detail. |
| 9 | +
|
| 10 | +## Release steps |
| 11 | + |
| 12 | +These steps apply when making a patch release or an incremental release candidate. |
| 13 | + |
| 14 | +### Step 1: Check out release branch locally |
| 15 | + |
| 16 | +From your local `facebook/react-native` clone, check out the relevant [release branch](./glossary.md#release-branch). Make sure your system is set up with the right [tooling dependencies](./support.md#external-dependencies-supported) for the release. e.g. you may need to switch Node versions. |
| 17 | + |
| 18 | +```sh |
| 19 | +# Fetch new commits and tags (to prep for any cherry-picks) |
| 20 | +git fetch --all --tags |
| 21 | + |
| 22 | +# Check out release branch |
| 23 | +git switch <release-branch> # e.g. 0.74-stable |
| 24 | + |
| 25 | +# OR, if checking out a release branch for the first time |
| 26 | +git switch -c <release-branch> upstream/<release-branch> |
| 27 | +``` |
| 28 | + |
| 29 | +### Step 2: Action cherry-picks and pull requests |
| 30 | + |
| 31 | +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](./support.md#release-issues-and-pick-request-escalation). |
| 32 | + |
| 33 | +```bash |
| 34 | +# Make sure to update the release branch |
| 35 | +git pull |
| 36 | + |
| 37 | +# Cherry-pick relevant commits |
| 38 | +git cherry-pick <commit-on-main> |
| 39 | +``` |
| 40 | + |
| 41 | +> [!Warning] |
| 42 | +> 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](./guide-hermes-release.md) into the release branch. Do not proceed past step 3 until the the branch has been updated with the Hermes release. |
| 43 | +
|
| 44 | +### Step 3: Wait for CircleCI artifacts to build |
| 45 | + |
| 46 | +Once all picks are complete, push your changes to the remote release branch. |
| 47 | + |
| 48 | +``` |
| 49 | +git push |
| 50 | +``` |
| 51 | + |
| 52 | +This will kick off a CircleCI workflow that will build relevant artifacts (Hermes prebuilts, `RNTester.apk`) that will expedite local testing. |
| 53 | + |
| 54 | +[Navigate to CircleCI](https://app.circleci.com/pipelines/github/facebook/react-native) and wait for the `build_npm_package` job to complete successfully. If the job fails, try and fix the issue so that artifacts build. |
| 55 | + |
| 56 | +> [!Important] |
| 57 | +> 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. |
| 58 | +> |
| 59 | +> 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. |
| 60 | +> |
| 61 | +> See [CircleCI Artifacts](./gotchas.md#circleci-artifacts) for more details. |
| 62 | +
|
| 63 | +### Step 4: Test the release |
| 64 | + |
| 65 | +Follow the [Release Testing guide](./guide-release-testing.md). Ideally, we should have 2 Release Crew members test the release. Coordinate with another Release Crew member to do a second pass. |
| 66 | + |
| 67 | +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. |
| 68 | + |
| 69 | +### Step 5. Create release (WIP update images) |
| 70 | + |
| 71 | +```sh |
| 72 | +yarn trigger-react-native-release \ |
| 73 | + --to-version <YOUR_RELEASE_VERSION> # e.g. 0.74.1, 0.75.0-rc.1 |
| 74 | + --token <YOUR_CIRCLE_CI_TOKEN> |
| 75 | +``` |
| 76 | + |
| 77 | +The script will ask what npm tag you want to use: |
| 78 | +- Select `latest` if you are publishing a patch on the [latest version](./glossary.md#latest-version). |
| 79 | +- Select `<your-version>-stable` if publishing a patch on any other [stable version](./glossary.md#stable-version). |
| 80 | +- The script should use `next` if you publishing a [release candidate](./glossary.md#release-candidate). |
| 81 | + |
| 82 | +The script will then output a link to the created CI workflow. |
| 83 | + |
| 84 | +<img src="../assets/release_process_jobs.png" width="600" /> |
| 85 | + |
| 86 | +1. `create_release` – Writes a release commit and tag, which will trigger the `publish_release` and `publish_bumped_packages` workflows. |
| 87 | +3. `publish_bumped_packages` – Publishes all workspace packages (excluding `react-native`) to npm. |
| 88 | +2. `publish_release` – Builds `react-native` package artifacts and publishes to npm. |
| 89 | + |
| 90 | +> [!Tip] |
| 91 | +> Look under "All Branches" filter to find the `publish_release` job. CircleCI locates this job outside of a given branch. |
| 92 | +
|
| 93 | +### Step 6: Verify Release (WIP update images) |
| 94 | + |
| 95 | +Once all workflows above are complete, verify the following: |
| 96 | + |
| 97 | +#### Verify npm publishes |
| 98 | + |
| 99 | +Verify that `react-native` is published on npm with the correct tag. |
| 100 | + |
| 101 | +```sh |
| 102 | +npm view react-native |
| 103 | + |
| 104 | +# Also verify that one or more subpackages are published |
| 105 | +npm view @react-native/codegen |
| 106 | +``` |
| 107 | + |
| 108 | +#### Init a new template app |
| 109 | + |
| 110 | +Sanity check by initializing a new project and running for Android and iOS. |
| 111 | + |
| 112 | +``` |
| 113 | +npx react-native@next init ReactNative<YOUR_VERSION> --version <YOUR_VERSION> |
| 114 | +``` |
| 115 | + |
| 116 | +> [!Tip] |
| 117 | +> Keep this project around somewhere incase you need to repro something on this version. |
| 118 | +
|
| 119 | +#### Verify Upgrade Helper is updated |
| 120 | + |
| 121 | +The `publish_release` job should also trigger the `rn-diff-purge` GitHub action ([link](https://github.com/react-native-community/rn-diff-purge/actions/workflows/new_release.yml)). This action will update the [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) with a diff of your latest release patch. Verify your release is visible in the dropdown. |
| 122 | + |
| 123 | +<img alt="Upgrade helper" src="../assets/upgrade_helper.png" width="600" /> |
| 124 | + |
| 125 | +#### Verify assets have been uploaded to Maven |
| 126 | + |
| 127 | +Verify release assets are uploaded to [Maven](https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts) for your release. |
| 128 | + |
| 129 | +Note, this may take a moment to update. Later, we will link to some of these artifacts in the release notes. |
| 130 | + |
| 131 | +- `https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/<YOUR_VERSION>/react-native-artifacts-<YOUR_VERSION>-hermes-framework-dSYM-debug.tar.gz` |
| 132 | +- `https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/<YOUR_VERSION>/react-native-artifacts-<YOUR_VERSION>-hermes-framework-dSYM-release.tar.gz` |
| 133 | + |
| 134 | +### Step 7: Generate the changelog PR |
| 135 | + |
| 136 | +Now we need to update the [`CHANGELOG.md`](https://github.com/facebook/react-native/blob/main/CHANGELOG.md) file at the `react-native` repo root. This is generated using [`@rnx-kit/rn-changelog-generator`](https://github.com/microsoft/rnx-kit/tree/main/incubator/rn-changelog-generator). |
| 137 | + |
| 138 | +> [!Note] |
| 139 | +> Changelog commits must be submitted to the `main` branch. |
| 140 | +
|
| 141 | +```sh |
| 142 | +# Check out `main` branch |
| 143 | +git switch main |
| 144 | + |
| 145 | +# Pull new tags |
| 146 | +git fetch --all --tags |
| 147 | + |
| 148 | +# Generate the changelog |
| 149 | +npx @rnx-kit/rn-changelog-generator \ |
| 150 | + --base v<LATEST_STABLE_OR_RC>\ |
| 151 | + --compare v<YOUR_NEW_VERSION> \ |
| 152 | + --repo . \ |
| 153 | + --changelog ./CHANGELOG.md |
| 154 | +``` |
| 155 | + |
| 156 | +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`. |
| 157 | + |
| 158 | +### Step 8: Create the GitHub Release |
| 159 | + |
| 160 | +Create a new [GitHub release](https://github.com/facebook/react-native/releases). |
| 161 | + |
| 162 | +- Set the release tag to the newly created tag. |
| 163 | +- Set the title to the release version (without preceding "v"). |
| 164 | +- Set release type: |
| 165 | + - Select "Set as a pre-release" if you releasing a release candidate. |
| 166 | + - Select "Set as the latest release" if you releasing a patch for the [latest version](./glossary.md#latest-version). |
| 167 | +- Copy and paste the following template and update TODOs. |
| 168 | + |
| 169 | +```md |
| 170 | +<!-- TODO Copy and paste your formatted Changelog generated here. --> |
| 171 | + |
| 172 | +--- |
| 173 | + |
| 174 | +<!-- TODO Update these links for your release version --> |
| 175 | +Hermes dSYMS: |
| 176 | +- [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) |
| 177 | +- [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) |
| 178 | + |
| 179 | +--- |
| 180 | + |
| 181 | +You can file issues or pick requests against this release [here](https://github.com/reactwg/react-native-releases/issues/new/choose). |
| 182 | + |
| 183 | +--- |
| 184 | + |
| 185 | +To help you upgrade to this version, you can use the [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) ⚛️. |
| 186 | + |
| 187 | +--- |
| 188 | + |
| 189 | +View the whole changelog in the [CHANGELOG.md file](https://github.com/facebook/react-native/blob/main/CHANGELOG.md). |
| 190 | +``` |
| 191 | + |
| 192 | +### Step 9: Communicate Release |
| 193 | + |
| 194 | +Send a message in the Core Contributors Discord `#release-coordination` channel about the new release. |
| 195 | + |
| 196 | +```md |
| 197 | +📢 0.X.Y release is out! |
| 198 | + |
| 199 | +📦 https://github.com/facebook/react-native/releases/tag/v0.X.Y |
| 200 | +📝 https://github.com/facebook/react-native/pull/<your-changelog-pr> |
| 201 | +``` |
| 202 | + |
| 203 | +### Step 10: Update Podfile.lock on the release branch |
| 204 | + |
| 205 | +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. |
| 206 | + |
| 207 | +```bash |
| 208 | +# Check out release branch |
| 209 | +git switch <release-branch> |
| 210 | + |
| 211 | +# Pull new changes (should include release commit from CI) |
| 212 | +git pull |
| 213 | + |
| 214 | +# Head to rn-tester package and update pods |
| 215 | +cd packages/rn-tester |
| 216 | +bundle exec pod update hermes-engine --no-repo-update |
| 217 | + |
| 218 | +# Should contain updated packages/rn-tester/Podfile.lock |
| 219 | +git commit -a -m "Update Podfile.lock" -m "Changelog: [Internal]" |
| 220 | +git push |
| 221 | +``` |
| 222 | + |
| 223 | +### Step 11: Update GitHub Project |
| 224 | + |
| 225 | +Make sure you've updated the status of completed and ongoing tasks in the relevant [GitHub project](https://github.com/reactwg/react-native-releases/projects?query=is%3Aopen). Unresolved items can be assigned to the following release. |
| 226 | + |
0 commit comments