How to promote a release

Creating a Preview Release

1. Choose the build to promote

Find a commit corresponding to a published nightly build. These commits have a message starting with "applying package updates", such as this one. This build should use a version of react-native close to the one chosen as the basis of the stable branch of RN core.

Check out this build locally. E.g. git checkout c9f39b4

2. Create a stable branch with new configuration

Run yarn promote-release --release preview --rnVersion 0.xx

This script will locally create a stable branch and update various configuration files and manifests in the repo to work correctly with the stable branch. After running the tool, a new 0.xx-stable branch should be locally checked out with changes committed.

3. Update the stable branch to a public react-native build

At this point the branch is still depending on a nightly build of react-native. Dependencies should be upgraded to the Facebook RC build closest to nightly build (e.g. 0.63.0-rc.0). This update may or may not introduce new changes. A quick way to check is to compare branches on the facebook/react-native Github repo and look for any commits before the first RC version. E.g. for 0.63, there were 5 commits cherry-picked into 0.63-stable before the first RC.

This step can be automated by using integrate-rn, such as by running yarn integrate-rn 0.64.0-rc.1.

Once we are using a stable react-native build, we should update react-native peer dependencies for react-native-windows and @office-iss/react-native-win32 to allow a range (start with ^) instead of requiring a fixed version.

4. Update PR pipeline files

Normal PRs to the main branch run checks against a subset of the build configurations run by the daily CI pipeline. This improves code velocity in main, but also risks build breaks in the unchecked configurations, which, if not addressed, risks publishing broken canary releases.

To prevent breaking stable builds, PRs to stable branches must be expanded to build all of the configurations normally built by CI. This is done by manually updating the buildMatrix object parameters in the pipeline yml files under /.ado/jobs/:

1. Look for the buildMatrix parameters, which typically contain two child nodes: BuildEnvironment: PullRequest and BuildEnvironment: Continuous
2. Replace the Matrix under BuildEnvironment: PullRequest with the Matrix from BuildEnvironment: Continuous (leave out any entries that set the UseExperimentalWinUI3 flag)
3. Commit your changes to your local branch.
4. Skip the change file check by adding npx beachball check --branch origin/$(BeachBallBranchName) --verbose 2>&1 | Tee-Object -Variable beachballOutput in setup.yml. See this commit as an example: https://github.com/microsoft/react-native-windows/commit/11543bb94420586be0523b4b49d0b8e425939a9d

5. Perform PR validation

Push your results upstream to the microsoft/react-native-windows repo as a temporary branch (e.g. assuming you've set up microsoft/react-native-windows as the upstream remote, and you want a temporary branch preview-0.64-test, use git push -u upstream 0.64-stable:preview-0.64-test). Manually run the PR pipeline against the test branch to detect any issues. It is expected that the "Check for change files" step will fail for manually triggered runs, and any missed test coverage should be run locally.

⚠ Make sure your temporary branch doesn't match the wildcard *-stable

6. Perform manual validation

Manual validation should be performed before publishing the build to ensure there aren't any showstopper issues. The validation performed is outside the scope of this document.

Details here

7. Push the build

Once ready, re-push your local branch directly to the microsoft/react-native-windows repo with the correct name (e.g. assuming the upstream remote as above, use git push -u upstream 0.64-stable). The Publish pipeline can now be manually scheduled to run on that branch for the release.

To schedule the automatic, daily CI for the branch, and the new branch to the Scheduled Triggers for the CI pipeline.

To schedule the automatic, weekly publish for the branch, add the new branch to the Scheduled Triggers for the Publish pipeline.

Promoting a Preview to Latest

1. Move the current latest release 0.XX-stable to legacy

To prevent older branches from being published as latest we need to change the tag they publish as. To do that:

1. Check out the current branch for latest (the one before preview) (i.e. git checkout 0.XX-stable)
2. Make sure your branch is up-to-date with the microsoft/react-native-windows repo
3. Create a new branch for the PR (i.e. git checkout -b promoteXX)
4. Run yarn promote-release --release legacy --rnVersion 0.XX
5. Create a PR with the generated commits to the latest branch (i.e. git push -u origin promoteXX)
6. After the PR is merged, wait for (or kick off) a new Publish run for the 0.XX-stable branch

2. Check out the preview 0.YY-stable branch

1. Check out the current branch for preview (i.e. git checkout 0.YY-stable)
2. Make sure your branch is up-to-date with the microsoft/react-native-windows repo
3. Ensure there are no pending changes to be published (changefiles in the changes directory).

   ⚠ Any changefiles targeting preview that slip through after promotion will have the wrong change type and prevent publishing changes

3. Perform manual validation

Same as above, we want to do a final check to see if there are any issues that may have slipped in.

4. Update configurations to release as latest

1. Create a new branch for the PR (i.e. git checkout -b promoteYY)
2. Run yarn promote-release --release latest --rnVersion 0.YY
3. Create a PR with the results (i.e. git push -u origin promoteYY)
4. After the PR is merged, wait for (or kick off) a new Publish run for the 0.YY-stable branch