Skip to content

Integration Process

Jump to bottom
Yajur Grover edited this page Dec 5, 2024 · 28 revisions

Schedule 2024

Integration month Driver
January Chiara
February Yajur
March Tatiana
April Marlene
May Chiara
June Yajur
July Tatiana
August Marlene
September Chiara
October Yajur
November Tatiana
December Chiara

We usually integrate one week chunks of Facebook changes at a time. We will use a script 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 integrate-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. Also leave the conflict in flowconfig.windows.conflict. 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 (It's a good idea to start this PR as a Draft first to make sure all our tests pass).

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.

Protocols

For integrations, our goal is to fall no more than one month behind the latest nightly build of React Native. In order to prevent falling behind, here are a couple pieces of protocol we like to follow:

  1. If we are caught up on integrations (i.e. RNW main is using the latest RN nightly build), the dev should integrate the next chunk 7 days later. In other words, when integrations are caught up we should be integrating a one week chunk of RN commits, weekly.
  2. If we are not caught up on integrations (i.e. RNW main is using a RN nightly build version that is >7 days behind the latest build), the dev should integrate of 14 days (can be less if only behind by 10 days for example). In other words, when integrations are not caught up we should be integrating larger chunks of RN commits. Once an integration is merged, the dev should immediately begin another integration until we are caught up with upstream.
  3. While working on an integration, the integration should be the devs primary focus until the integration is merged. The longer the time taken to complete an integration the more days we have to catch up on later.
  4. As a general rule of thumb if an integration is taking a dev longer that 7 days to complete, the dev should send an email to key developers on the team to ask for help and gather ideas. If the integration is taking longer than 10 days to complete, the dev should begin to search for the breaking commit. See below for more information on binary searching for the breaking commit.
  5. If you encounter an issue caused by code upstream which is breaking Windows behavior, reach out to the React Native maintainers on the Discord channel. Note, sometimes a break from upstream had already been fixed in a more recent RN Nightly build. If this is the case, just extend the integration to that nightly build version.

Searching for a Breaking Commit

When working on an integration, there are some breaks that are hard to track down from debugging the repo alone. If you have been working on an integration for 10 days and cannot find the culprit of an issue, the next step is to begin to track down the offending commit. To do this you will want to use binary search to integrate different nightly builds until you locate the nightly build which introduces the issue. This process can help you debug as the commit range is much smaller and you can concentrate on only the changes made on a particular day.

Troubleshooting

Overriding Files / 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. Edits should be surrounded by // [Windows #issuenumber ... code ... // Windows] comments to help the next developer.
  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. Create an issue to track the removal of the forked files following fixes upstream. The issue at minimum should have the integration where the override was introduced and the PR from upstream that created the issue. Make sure to link this issue in the override.json and imbedded it into the override file as a comment
  7. Commit your changes.
  8. Make a PR upstream to react-native with the required fixes. Link PR to issue tracking forked file removal.

Failing Policheck?

Due to internal tools, please see team OneNote for steps to update binaries if on the RNW team or contact someone from the RNW team

Other Common Errors

Flow
  • Wrong version of Flow. The config specifies version ^0.207.0 but this is version 0.206.0 x Error detected while running 'flow-check'. This means the integration tool didn't upgrade flow correctly. You'll have to manually search for the old version and replace it with the new version and re-run yarn!
VS Linker Errors

  • Seeing a LNK2019 or LNK2001 Error that looks like this? EventTarget.obj : error LNK2019: unresolved external symbol "public: class facebook::jsi::Value __thiscall facebook::react::InstanceHandle::getInstanceHandle(class facebook::jsi::Runtime &)const " (?getInstanceHandle@InstanceHandle@react@facebook@@QBE?AVValue@jsi@3@AAVRuntime@53@@Z) referenced in function "public: void __thiscall facebook::react::EventTarget::retain(class facebook::jsi::Runtime &)const " (?retain@EventTarget@react@facebook@@QBEXAAVRuntime@jsi@3@@Z)ShadowNode.obj : error LNK2001: unresolved external symbol "public: class facebook::jsi::Value __thiscall facebook::react::InstanceHandle::getInstanceHandle(class facebook::jsi::Runtime &)const " (?getInstanceHandle@InstanceHandle@react@facebook@@QBE?AVValue@jsi@3@AAVRuntime@53@@Z). This usually means that RN added a file to ReactCommon upstream and we need to add it to vnext\Shared\Shared.vcxitems

  • Seeing a LNK2019 or LNK2001 in the Desktop-ReactNative project that looks like this? react-native-win32.exp(0,0): Error LNK2001: unresolved external symbol "public: virtual void __cdecl facebook::react::Instance::JSCallInvoker::invokeAsync(class std::function<void __cdecl(void)> &&)" (?invokeAsync@JSCallInvoker@Instance@react@facebook@@UEAAX$$QEAV?$function@$$A6AXXZ@std@@@Z). Try copying this portion of the error message ?invokeAsync@JSCallInvoker@Instance@react@facebook@@UEAAX$$QEAV?$function@$$A6AXXZ@std@@@Z and adding it to the vnext/Desktop.DLL/react-native-win32.x64.def and vnext/Desktop.DLL/react-native-win32.x86.def files.

JSI Changes
  1. Update node-jsi-api repo (all projects on RNW use the JSI from this repo) https://github.com/microsoft/node-api-jsi. Corresponding PRs: https://github.com/microsoft/node-api-jsi/pull/7/files and https://github.com/microsoft/node-api-jsi/pull/8/files
  2. Update RNW to use new published node-jsi-api repo
  3. Update RNW JSI files to include new JSI changes. See: https://github.com/microsoft/react-native-windows/pull/12571/commits/fde68834cbb9e8289b9d3f6f371c0d516ab7fd0e
  4. Upgrade RNW JSI_Version to the new version from node-jsi-api repo: https://github.com/microsoft/react-native-windows/pull/12571/commits/58414e2f8ceaecabc59957b1c22f968b50f3a82f

Note: This is all from the work Vlad did on this integration, if he's in the office, ask him for help! :)

JSI Change instructions as discussed on 10/16/2024
Steps to take
Supported JSI implementations
  • JSI for Node-API
  • JSI for V8
  • JSI for Chakra
  • JSI for JsiAbi
What we can do better in future?
  • Keep only JSI for Node-API
  • Ask Meta to support JSI versions
Current JSI related components in RNW
                        +------------------+
                        |  JSI for JsiAbi  |
                        +------------------+
                                  |
                                  V
                        +------------------+
                        |      JsiAbi      |
                        +------------------+
                                  |
            +---------------------+---------------------+
            |                     |                     |
            V                     V                     V
  +------------------+  +------------------+  +------------------+
  | JSI for Node-API |  |  JSI for Chakra  |  |    JSI for V8    |
  +------------------+  +------------------+  +------------------+
            |                     |                     |
            V                     V                     V
  +------------------+  +------------------+  +------------------+
  |  Hermes Node-API |  |      Charka      |  |        V8        |
  +------------------+  +------------------+  +------------------+
Reducing JSI related components in future
                        +------------------+
                        | JSI for Node-API |
                        +------------------+
                                  |
                       +----------+----------+
                       |                     |
                       V                     V
              +------------------+  +------------------+
              |  Hermes Node-API |  |   V8 Node-API    |
              +------------------+  +------------------+
Clone this wiki locally