| 1 | # React Release Scripts |
| 2 | |
| 3 | This document describes how to prepare and publish a release manually, using the command line. |
| 4 | |
| 5 | However, most of our releases are actually *prereleases* that get continuously shipped via CI. Our automated prerelease channels are preferred whenever possible, because if they accidentally break, it won't affect production users. |
| 6 | |
| 7 | Before proceeding, consider your motivation: |
| 8 | |
| 9 | - **"I want to share experimental features with collaborators."** After your code lands in GitHub (behind an experimental feature flag), it will be automatically published via CI within the next weekday. So usually, all you have to do is wait. |
| 10 | - **"But I want to publish it now!"** You can [trigger the CI job to run automatically](#trigger-an-automated-prerelease). |
| 11 | - **"I want to publish a stable release with a real version number"** Refer to the ["Publishing a Stable Release"](#publishing-a-stable-release) section. If this is your first time running a stable release, consult with another team member before proceeding. |
| 12 | - **"I have some special use case that's not explicitly mentioned here."** Read the rest of this document, and consult with another team member before proceeding. |
| 13 | |
| 14 | # Process |
| 15 | |
| 16 | If this is your first time running the release scripts, go to the `scripts/release` directory and run `yarn` to install the dependencies. |
| 17 | |
| 18 | The release process consists of several phases, each one represented by one of the scripts below. |
| 19 | |
| 20 | A typical release cycle goes like this: |
| 21 | 1. When a commit is pushed to the React repo, [GitHub Actions](https://github.com/facebook/react/actions) will build all release bundles and run unit tests against both the source code and the built bundles. |
| 22 | 2. Each weekday, an automated CI cron job publishes prereleases to the `canary` and `experimental` channels, from tip of the main branch. |
| 23 | You can also [trigger an automated prerelease via the GitHub UI](#trigger-an-automated-prerelease), instead of waiting until the next time the cron job runs. |
| 24 | 3. Finally, a "canary" release can be [**promoted to stable**](#publishing-a-stable-release)<sup>1</sup> (This process is always manual.) |
| 25 | |
| 26 | ## Trigger an Automated Prerelease |
| 27 | |
| 28 | If your code lands in the main branch, it will be automatically published to the prerelease channels within the next weekday. However, if you want to immediately publish a prerelease, you can trigger the job to run immediately via the GitHub UI: |
| 29 | |
| 30 | 1. Wait for the commit you want to release to finish its [(Runtime) Build and Test workflow](https://github.com/facebook/react/actions/workflows/runtime_build_and_test.yml), as the prerelease script needs to download the build from that workflow. |
| 31 | 2. Copy the full git sha of whichever commit you are trying to release |
| 32 | 3. Go to https://github.com/facebook/react/actions/workflows/runtime_release_from_ci.yml |
| 33 | 4. Paste the git sha into the "Run workflow" dropdown |
| 34 | 5. Let the job finish and it will be released on npm |
| 35 | |
| 36 | This will grab the specified revision on the main branch and publish it to the Next and Experimental channels. |
| 37 | |
| 38 | |
| 39 | ## Publishing an Experimental Release |
| 40 | |
| 41 | Same as for a prerelease except choose `experimental-only` as the type |
| 42 | |
| 43 | ## Publishing Without Tags |
| 44 | |
| 45 | The sections below include meaningful `--tags` in the instructions. However, keep in mind that **the `--tags` arguments is optional**, and you can omit it if you don't want to tag the release on npm at all. This can be useful when preparing breaking changes. |
| 46 | |
| 47 | ## Publishing a Stable Release |
| 48 | |
| 49 | Stable releases should always be created from the "canary" channel. This encourages better testing of the actual release artifacts and reduces the chance of unintended changes accidentally being included in a stable release. |
| 50 | |
| 51 | Before promoting, make sure the versions have been bumped: |
| 52 | |
| 53 | 1. [ReactVersions.js](../../ReactVersions.js) |
| 54 | 1. `package.json` files for each package |
| 55 | 1. [packages/shared/ReactVersion.js](../../packages/shared/ReactVersion.js) |
| 56 | |
| 57 | Once the "canary" release has been tested and verified, you can promote it to stable by running the [Publish release](./actions/workflows/runtime_release_from_ci.yml) GitHub Action workflow. This workflow will prepare the release artifacts and publish them to NPM as either `stable-latest` (e.g. for `react@latest`) or `stable-backport` for an older release line that shouldn't move `@latest` (published under the `@backport` dist-tag instead). |
| 58 | |
| 59 | > [!IMPORTANT] |
| 60 | > The designated commit must be able to build in CI. If runtime_build_and_test.yml fails for that commit, the release workflow will also fail. |
| 61 | |
| 62 | ### Backport |
| 63 | |
| 64 | 1. Pick a commit from `main` which you want to backport |
| 65 | 1. Choose which release you want to backport it to |
| 66 | 1. Find or create a branch for that release following our release branch naming convention `releases/**/*` e.g. `releases/19.1.x` |
| 67 | 1. Make sure versions (`ReactVersions.js`, `ReactVersion.js`, `package.json`) are set to an unreleased version |
| 68 | 1. Cherry-pick desired commits |
| 69 | 1. Push to branch |
| 70 | 1. [Publish release](./actions/workflows/runtime_release_from_ci.yml) |
| 71 | - `workflow_from` is the newly pushed commit containing cherry-picked changes, |
| 72 | - `type` is either `stable-latest` (e.g. for `react@latest`) or `stable-backport` for an older release line that shouldn't move `@latest` (published under the `@backport` dist-tag instead). |
| 73 | 1. For stable releases the workflow will prepare everything for an automated publish. However, the final publish step will require manual approval in the GitHub Actions UI. |