Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the contributing section docs #3221

Merged
merged 26 commits into from
Jul 22, 2022
Merged

Update the contributing section docs #3221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
daa7788
update to match the fact that for NDK we now use the side-by-side ver…
kelset Jul 21, 2022
37e329c
formatting
kelset Jul 21, 2022
b94dc6c
update the E2E section
kelset Jul 21, 2022
c1fab1a
remove references to AppVeyor since it's not there anymore
kelset Jul 21, 2022
d29d6ab
update dependencies table
kelset Jul 21, 2022
f2b2498
no need to have the names there
kelset Jul 21, 2022
2c9b9c4
formatting
kelset Jul 21, 2022
43e0cf5
reworking the testing doc
kelset Jul 21, 2022
e71081b
rework minor candidate page
kelset Jul 21, 2022
129b833
slight change in default text
kelset Jul 21, 2022
24d7576
update the doc for RC patches
kelset Jul 21, 2022
241acd3
set in the correct/logical order
kelset Jul 21, 2022
58d5aab
work on the documentation for releasing the stable minor .0
kelset Jul 21, 2022
0913b60
tweak the document for releasing a patch of a minor
kelset Jul 21, 2022
672c792
a few more tweaks
kelset Jul 21, 2022
7d09071
Update website/contributing/how-to-build-from-source.md
kelset Jul 22, 2022
1491600
fix alex
kelset Jul 22, 2022
aafc380
Merge branch 'fix-contributing-docs' of github.com:kelset/react-nativ…
kelset Jul 22, 2022
1cd15d2
Update website/contributing/release-testing.md
kelset Jul 22, 2022
3f73728
Update website/contributing/release-stable-minor.md
kelset Jul 22, 2022
7525fcd
Update website/contributing/release-stable-minor.md
kelset Jul 22, 2022
9ccbed7
Update website/contributing/release-stable-minor.md
kelset Jul 22, 2022
b9a990b
Update website/contributing/release-branch-cut-and-rc0.md
kelset Jul 22, 2022
a995faf
Update website/contributing/how-to-run-and-write-tests.md
kelset Jul 22, 2022
77eaa50
Update website/contributing/how-to-run-and-write-tests.md
kelset Jul 22, 2022
0fbdc95
add redirect
kelset Jul 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion website/contributing/contributing-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ Whenever you are ready to contribute code, check out our [step-by-step guide to

### Tests

Tests help us prevent regressions from being introduced to the codebase. The GitHub repository is continuously tested using CircleCI and Appveyor, the results of which are available through the Checks functionality on [commits](https://github.com/facebook/react-native/commits/HEAD) and pull requests.
Tests help us prevent regressions from being introduced to the codebase. The GitHub repository is continuously tested using CircleCI, the results of which are available through the Checks functionality on [commits](https://github.com/facebook/react-native/commits/HEAD) and pull requests.

You can learn more about running and writing tests on the [How to Run and Write Tests](/contributing/how-to-run-and-write-tests) page.

Expand Down
22 changes: 8 additions & 14 deletions website/contributing/how-to-build-from-source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ Assuming you have the Android SDK installed, run `android` to open the Android S

Make sure you have the following installed:

1. Android SDK version 30 (`compileSdkVersion` in [`build.gradle`](https://github.com/facebook/react-native/blob/main/ReactAndroid/build.gradle)).
2. Android NDK 21.4.7075529 (from in [`gradle.properties`](https://github.com/facebook/react-native/blob/b1120c6a6513ec24568abc6bbe60dd57ef1dec96/gradle.properties#L7), download links and installation instructions below).
1. Android SDK (find the specific version in the `compileSdkVersion` in [`build.gradle`](https://github.com/facebook/react-native/blob/main/ReactAndroid/build.gradle#L253)).
kelset marked this conversation as resolved.
Show resolved Hide resolved
Simek marked this conversation as resolved.
Show resolved Hide resolved
2. Android NDK

#### Point Gradle to your Android SDK

Expand Down Expand Up @@ -45,13 +45,7 @@ ndk.dir=/Users/your_unix_name/android-ndk/android-ndk-r20b

#### Download links for Android NDK

1. [macOS (64-bit)](https://dl.google.com/android/repository/android-ndk-r20b-darwin-x86_64.zip)
2. [Linux (64-bit)](https://dl.google.com/android/repository/android-ndk-r20b-linux-x86_64.zip)
3. [Windows (64-bit)](https://dl.google.com/android/repository/android-ndk-r20b-windows-x86_64.zip)
4. [Windows (32-bit)](https://dl.google.com/android/repository/android-ndk-r20b-windows-x86.zip)

You can find further instructions on the [official page](https://developer.android.com/ndk/index.html).
Or follow instructions to [download appropriate NDK from SDK manager](https://developer.android.com/studio/projects/install-ndk#specific-version).
You can find the instructions to install the NDK on the [official Android NDK website](https://developer.android.com/studio/projects/install-ndk).

### Building the source

Expand Down Expand Up @@ -149,9 +143,9 @@ You should be able to use the _Run_ button to run your app on a device. Android

### Additional notes

Building from source can take a long time, especially for the first build, as it needs to download ~200 MB of artifacts and compile the native code.
Building from source can take a long time, especially for the first build, as it needs to download ~200 MB of artifacts and compile the native code.

Every time you update the `react-native` version from your repo, the build directory may get deleted, and all the files are re-downloaded.
Every time you update the `react-native` version from your repo, the build directory may get deleted, and all the files are re-downloaded.
To avoid this, you might want to change your build directory path by editing the `~/.gradle/init.gradle` file:

```groovy
Expand Down Expand Up @@ -192,7 +186,7 @@ Install it in your app project package.json.

## Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue.
The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue.

Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

Expand Down Expand Up @@ -226,9 +220,9 @@ Upload the binaries from the `android` folder to maven and point your Android ap

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR.
If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR.

To start making your dependency branch, make sure you are on a `release/my-forked-release` branch, then merge any commits that you need from yourself or others into this branch.
To start making your dependency branch, make sure you are on a `release/my-forked-release` branch, then merge any commits that you need from yourself or others into this branch.

:::warning
This release branch should never be merged into any other branch.
Expand Down
2 changes: 1 addition & 1 deletion website/contributing/how-to-contribute-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Then, you can run several commands:

Tests help us prevent regressions from being introduced to the codebase. We recommend running `yarn test` or the platform-specific scripts above to make sure you don't introduce any regressions as you work on your change.

The GitHub repository is [continuously tested](/contributing/how-to-run-and-write-tests#continuous-testing) using CircleCI and Appveyor, the results of which are available through the Checks functionality on [commits](https://github.com/facebook/react-native/commits/main) and pull requests.
The GitHub repository is [continuously tested](/contributing/how-to-run-and-write-tests#continuous-testing) using CircleCI, the results of which are available through the Checks functionality on [commits](https://github.com/facebook/react-native/commits/main) and pull requests.

You can learn more about running and writing tests on the [How to Run and Write Tests](/contributing/how-to-run-and-write-tests) page.

Expand Down
30 changes: 10 additions & 20 deletions website/contributing/how-to-run-and-write-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,16 +77,7 @@ Finally, make sure end-to-end tests run successfully by executing the following
./scripts/test-manual-e2e.sh
```

End-to-end tests written in [Detox](https://github.com/wix/Detox) confirm that React Native components and APIs function correctly in the context of a running app. They run the RNTester app in the simulator and simulate a user interacting with the app.

You can run Detox end-to-end tests locally by [installing the Detox CLI](https://github.com/wix/Detox/blob/master/docs/Introduction.GettingStarted.md#step-1-install-dependencies) on macOS, then running the following in the command line:

```bash
yarn run build-ios-e2e
yarn run test-ios-e2e
```

If you work on a component or API that isn't covered by a Detox test, please consider adding one. Detox tests are stored under [`RNTester/e2e/__tests__`](https://github.com/facebook/react-native/tree/main/RNTester/e2e/__tests__).
This script will make you select to run the RNTester app (that lives within `packages/rn-tester`) or it will generate a fresh new project in `/tmp/RNTestProject`. Follow the step-by-step instructions from the script to test successfully if your changes.

## Writing Tests

Expand All @@ -101,11 +92,11 @@ The JavaScript tests can be found inside `__test__` directories, colocated next

### iOS Integration Tests

React Native provides facilities to make it easier to test integrated components that require both native and JS components to communicate across the bridge.
React Native provides facilities to make it easier to test integrated components that require both native and JS components to communicate across the bridge.

The two main components are `RCTTestRunner` and `RCTTestModule`. `RCTTestRunner` sets up the React Native environment and provides facilities to run the tests as `XCTestCase`s in Xcode (`runTest:module` is the simplest method). `RCTTestModule` is exported to JavaScript as `NativeModules.TestModule`.

The tests themselves are written in JS, and must call `TestModule.markTestCompleted()` when they are done, otherwise the test will timeout and fail.
The tests themselves are written in JS, and must call `TestModule.markTestCompleted()` when they are done, otherwise the test will timeout and fail.

Test failures are primarily indicated by throwing a JS exception. It is also possible to test error conditions with `runTest:module:initialProps:expectErrorRegex:` or `runTest:module:initialProps:expectErrorBlock:` which will expect an error to be thrown and verify the error matches the provided criteria.

Expand All @@ -123,11 +114,11 @@ See the following for example usage and integration points:

A common type of integration test is the snapshot test. These tests render a component, and verify snapshots of the screen against reference images using `TestModule.verifySnapshot()`, using the [`FBSnapshotTestCase`](https://github.com/facebook/ios-snapshot-test-case) library behind the scenes. Reference images are recorded by setting `recordMode = YES` on the `RCTTestRunner`, then running the tests.

Snapshots will differ slightly between 32 and 64 bit, and various OS versions, so it's recommended that you enforce tests are run with the [correct configuration](https://github.com/facebook/react-native/blob/main/scripts/.tests.env).
Snapshots will differ slightly between 32 and 64 bit, and various OS versions, so it's recommended that you enforce tests are run with the [correct configuration](https://github.com/facebook/react-native/blob/main/scripts/.tests.env).

It's also highly recommended that all network data be mocked out, along with other potentially troublesome dependencies. See [`SimpleSnapshotTest`](https://github.com/facebook/react-native/blob/main/IntegrationTests/SimpleSnapshotTest.js) for a basic example.

If you make a change that affects a snapshot test in a pull request, such as adding a new example case to one of the examples that is snapshotted, you'll need to re-record the snapshot reference image.
If you make a change that affects a snapshot test in a pull request, such as adding a new example case to one of the examples that is snapshotted, you'll need to re-record the snapshot reference image.

To do this, change `recordMode` flag to `_runner.recordMode = YES;` in [RNTester/RNTesterSnapshotTests.m](https://github.com/facebook/react-native/blob/136666e2e7d2bb8d3d51d599fc1384a2f68c43d3/RNTester/RNTesterIntegrationTests/RNTesterSnapshotTests.m#L29), re-run the failing tests, then flip record back to `NO` and submit/update your pull request and wait to see if the CircleCI build passes.

Expand All @@ -141,29 +132,28 @@ It's a good idea to add an Android integration test whenever you are working on

## Continuous Testing

We use [Appveyor][config-appveyor] and [CircleCI][config-circleci] to automatically run our open source tests. Appveyor and CircleCI will run these tests whenever a commit is added to a pull request, as a way to help maintainers understand whether a code change introduces a regression. The tests also run on commits to the `main` and `*-stable` branches in order to keep track of the health of these branches.
We use [CircleCI][config-circleci] to automatically run our open source tests. CircleCI will run these tests whenever a commit is added to a pull request, as a way to help maintainers understand whether a code change introduces a regression. The tests also run on commits to the `main` and `*-stable` branches in order to keep track of the health of these branches.

[config-appveyor]: https://github.com/facebook/react-native/blob/main/.appveyor/config.yml
[config-circleci]: https://github.com/facebook/react-native/blob/main/.circleci/config.yml

There's another set of tests that run within Meta's internal test infrastructure. Some of these tests are integration tests defined by internal consumers of React Native (e.g. unit tests for a React Native surface in the Facebook app).
There's another set of tests that run within Meta's internal test infrastructure. Some of these tests are integration tests defined by internal consumers of React Native (e.g. unit tests for a React Native surface in the Facebook app).

These tests run on every commit to the copy of React Native hosted on Facebook's source control. They also run when a pull request is imported to Facebook's source control.

If one of these tests fail, you'll need someone at Meta to take a look. Since pull requests can only be imported by Meta employees, whoever imported the pull request should be able to facilitate any details.

:::note
**Running CI tests locally:**
Most open source collaborators rely on CircleCI and Appveyor to see the results of these tests. If you'd rather verify your changes locally using the same configuration as CircleCI, CircleCI provides a [command line interface](https://circleci.com/docs/2.0/local-cli/) with the ability to run jobs locally.
Most open source collaborators rely on CircleCI to see the results of these tests. If you'd rather verify your changes locally using the same configuration as CircleCI, CircleCI provides a [command line interface](https://circleci.com/docs/local-cli) with the ability to run jobs locally.
:::

### F.A.Q.

#### How do I upgrade the Xcode version used in CI tests?

When upgrading to a new version of Xcode, first make sure it is [supported by CircleCI](https://circleci.com/docs/2.0/testing-ios/#supported-xcode-versions).
When upgrading to a new version of Xcode, first make sure it is [supported by CircleCI](https://circleci.com/docs/testing-ios#supported-xcode-versions).

You will also need to update the test environment config to make sure tests run on an iOS Simulator that comes installed in the CircleCI machine.
You will also need to update the test environment config to make sure tests run on an iOS Simulator that comes installed in the CircleCI machine.

This can also be found in [CircleCI's Xcode version reference](https://circleci.com/docs/2.0/testing-ios/#supported-xcode-versions) by clicking the desired version and looking under Runtimes.

Expand Down
Loading