Integration Process

Schedule

We usually integrate one week chunks of Facebook changes at a time. We will use a script created by Nick to carry out most of the work of the integration. Your main task is to resolve conflicts that appear in the source, make sure the code changes make sense, and file new issues based on the changes that have been added.

Note the main goal here is to not break React Native Windows. The next goal is to be helpful in creating issues, so that we are on top of to-do items as they come in from Facebook. The final goal is to be helpful and solve small updates as they come in, if you have time.

Try to start your integration in the morning because your integration is based on a particular build of RNW. A new build is generated each day, so if you don't merge in your integration the same day you start the integration you will need to resolve some merge conflicts with RNW master to upgrade your RNW version to the latest build.

Recommendation to use the meld tool to merge.

Steps to Integrate Changes from Core:

1. Go into react-native-windows Pull Request history and find the last integration. See the range of commits that were added from the last integration.

   The commit range with have the format <old commit hash 1>…<old commit hash 2>. Take note of <old commit hash 2>. This will be the <new commit hash 1> value for the integration you are about to complete.

2. Go to react native in npm and find the release with the value <old commit hash 2>. Take note of the date of this release.

3. Find the release two weeks after the release date of <old commit hash 2>. Take note of this date and the hash value associated with the release (the hash value will be the hash after the final - in the version name). This will be <new commit hash 2>.

4. Go to Facebook/react-native and use the <new commit hash 1>…<new commit hash 2> structure to view the commit range for your integration. Browse over this commit history and identify any repository changes that may require new issues to be filed.

   Look to see if there were bugs fixed that need to also be fixed in Windows source, API changes, or new constants/object types. If these types of changes pop up, file issues. The issues should contain a link to the Facebook change and an explanation of what change should be made to stay in line with Facebook. Also tag the issue with the "Integration Follow-up" Tag.

   Note we don't yet have Fabric or Layout Animation supported, so changes related to these you can ignore and not create issues about.

5. Go to your local copy of react-native-windows. Go to your main branch, and pull in your latest changes from upstream using git pull upstream main --rebase.

6. Checkout a fresh branch and run yarn and yarn build.

7. Run yarn integrate-rn <nightly build version>, where the nightly build version is the full version name you got <new commit hash 2> from (example: yarn interate-rn 0.0.0-20220516-2016-4994b8b5d).

8. Run npx react-native-platform-override upgrade

9. Open source with code ..

10. Walk through conflicts and resolve. Note you'll have to manually search for >>>>>>>; the conflicts will not show themselves automatically. The strategy here is to go into the Facebook repo and find the commit with the change to that file. See what changes were made and why and then take a look at the current edition of the file in react-native-windows to see if the changes should be applied to the Windows copy. Sometimes the Windows copy of files is a direct copy of the react-native version, other times small sections are changed, other times the entire file is different. In the latter two cases, it may be that the changes should not be merged in because the code sections that had changes don't actually exist in the Windows copy of the file.

    Typically, if only sections of the file are adjusted for Windows you will see a // [Windows comment around the section alerting you it is a Windows change. Note: Some >>>>>> instances are intentional such as those in the E2E testing for react-native-platform-override. Be careful not to remove these.

11. After all conflicts are resolved, run yarn validate-overrides.

12. Then, run playground locally to do an initial check that RNW and playground are still working. Commit your changes, add changelog, and create a PR. Make sure PR description matches structure of past integration PR's. Should list out Facebook commit range and link. Should list out and link any issues opened from integration.

Additional Information on Scripts and Packages

integrate-rn

integrate-rn is the script used to integrate a new nightly build of react-native into react-native-windows. The script updates all react-native dependencies to the new nightly build, pulls in source code changes, and runs the react-native-platform-override packages to refresh overrides.

react-native-platform-override

react-native-platform-override is a tool to manage "platform overrides" for out of tree React Native platforms. We use this package to add, update, and remove overrides from react-native-windows. Typically these overrides occur in the JavaScript section of the codebase for sections of code we want to fork from react-native.

Troubleshooting

Errors in ReactCommon

Sometimes upstream will make a change to ReactCommon that breaks the build on Windows. In this case, here are the steps to follow to fork the ReactCommon code and restore it to a working state.

1. If the folder vnext/ReactCommon/TEMP_UntilReactCommonUpdate does not exist, add it.
2. To this directory add the files that are throwing errors during the build. Make sure to include the relative path to those files within the ReactCommon directory to their path inside TEMP_UntilReactCommonUpdate.
3. Make the edits to the broken files that are needed to restore the build.
4. Run yarn validate-overrides; this command should fail and tell you the files that need overrides add to them (should be the same as the list of files you just added to TEMP_UntilReactCommonUpdate).
5. Use npx react-native-platform-override add <path_name> to add the overrides.
6. Commit your changes.
7. Create an issue to track the removal of the forked files following fixes upstream.
8. Make a PR upstream to react-native with the required fixes. Link PR to issue tracking forked file removal.