Skip to content

Latest commit

 

History

History
131 lines (93 loc) · 9.79 KB

CONTRIBUTING.md

File metadata and controls

131 lines (93 loc) · 9.79 KB
Raw

Contributing to Expo

Thanks so much for coming to help! Currently we review PRs for packages/, docs/, templates/, guides/, apps/, and markdown files. Because the native clients (ios/, android/) are difficult to setup and require API tokens, not much progress can be made externally (but you can always try!). We've moved most of the fun code out of the client anyways to support the bare-workflow; this means that you'll do the majority of your native testing in a bare Expo project.

As you might imagine web code is very easy to test and contribute to, so that's all on the table! You may find that some of the web features you're looking for are actually in the expo-cli repo.

📦 Download and Setup

  1. Fork this repository to your own GitHub account and then clone it to your local device. (git remote add upstream [email protected]:expo/expo.git 😉)

  2. Run the setup script with: npm run setup:native (if you just want to contribute to the docs, you can run npm run setup:docs). This command does the following for you:

    • Downloads submodules (like react-native) with git submodule update --init
    • Fetches files with git lfs, which we use for big native libraries like Google Mobile Vision. Note: you must have git lfs already installed.
    • Ensures Yarn is installed
    • Ensures your computer is set up for React Native (will install the Android NDK if it's not present)
    • Downloads the Node packages (yarn install)

  3. Navigate to the bare sandbox project cd apps/bare-expo

  4. Run the project on any platform (maybe start with web; it's the fastest! 😁)

    • Web: yarn web
    • iOS: yarn ios
    • Android: yarn android

If this didn't work for you as described, please open an issue.

✍️ Editing Packages

All of our packages (including Foundation Unimodules) can be found in the packages/ directory. These packages are automatically linked to the projects in the apps/ directory (meaning any iOS, Android, web, or API changes can be tested from apps/bare-expo/). bare-expo is a bare workflow Expo app that acts as a runner for the other projects in the apps/ directory.

  • native-component-list: This is where you can write demos or tests that require physical interaction (a good playground for testing).
  • test-suite: You can write your E2E tests in here. When pushed to the remote, CI will run this project with Device Farm for Android, Detox for iOS, and Puppeteer for web!

All modules should adhere to the style guides which can be found here:

  1. Navigate to a package you want to edit. Ex: cd packages/expo-constants
  2. Start the TypeScript build in watch mode: yarn build
  3. Edit code in that package's src/ directory
  4. Play with your changes on a simulator or device through bare-expo:
    • Add or modify a file named after the API you're working on. Ex: apps/test-suite/tests/Constants.js
    • Run the code from the bare-expo project with yarn <android | ios | web> or test the code with yarn test:<ios | web>
  5. You can edit a package's native code directly from its respective folder in the packages/ directory or by opening bare-expo in a native editor:
    • Android Studio: yarn edit:android
    • Xcode: yarn edit:ios
    • Remember to rebuild the native project whenever you make a native change

Extra Credit

  • The React Native dev tools are currently disabled in our fork #5602. You can hack around this by cloning React Native outside this repo, then copying the contents react-native/React/DevSupport into expo/react-native-lab/react-native/React/DevSupport (this will only enable the shake gesture, CMD+R won't work yet).
  • We use a fork of react-native in this repo; this fork is located at react-native-lab/react-native (you can make changes or cherry-picks from here if you want). It diverges the minimal amount necessary from the react-native version in its package.json.
  • All of the package's build/ code should be committed. This is because it is simpler to reproduce issues if all contributors are running the same code and so we don't need to rebuild dozen of packages locally on every git pull or git checkout operation.
  • We use a unified set of basic Bash scripts and configs called expo-module-scripts to ensure everything runs smoothly (TypeScript, Babel, Jest, etc...).

⏱ Testing Your Changes

You'll need write about how you tested your changes in the PR under the Test Plan section.

The best way to get your changes merged is to build good tests for them! We have three different kinds of tests: unit-tests, automated E2E tests, and demos (adding tests that you notice are missing is a great way to become my friend 🥳)!

✅ Unit Testing

  1. Create a test for your feature in the appropriate package's src/__tests__ directory (if the file doesn't exist already, create it with the *-test.ts or *-test.tsx extension).
  2. Run the test with yarn test and ensure it handles all platforms (iOS, Android, and web). If the feature doesn't support a platform, then you can exclude it by putting your test in a file with a platform extension like: -test.ios.ts, -test.native.ts, -test.web.ts...
  3. You can also test platforms one at a time by pressing X and selecting the platform you want to test!

🏁 E2E Testing

  1. Write your tests in apps/test-suite/tests
    • These tests are written with a non-feature-complete version of Jasmine that runs on the Android and iOS clients, so no special features like snapshot testing will be available.
    • If you created a new test file, be sure to add it in apps/test-suite/TestUtils.js. This is where you can do platform exclusion. Use global.DETOX to test for iOS tests, and ExponentTest.isInCI to test for Android Device Farm.
  2. Run your tests locally from the bare-expo directory with yarn test:ios, or yarn test:web.
    • For the moment Android Detox is not set up, but you can still run the project in an emulator or on a device to test it.
    • It's important you test locally because native CI tests can be fragile, take a while to finish, and be frustrating when they fail.
    • When testing for web, you can set headless: false in the apps/bare-expo/jest-puppeteer.config.js to watch the tests live. You can also execute await jestPuppeteer.debug(); in apps/bare-expo/e2e/TestSuite-test.web.js to pause the tests and debug them!
  3. Remember to try and get your feature running on as many platforms as possible.

Thanks again for helping to make sure that Expo is stable for everyone!

📚 Updating Documentation

Our docs are made with Next.js. They're located in the docs/ directory. For more information look at the docs/readme.md.

TL;DR:

  1. Navigate to the docs/ directory and run yarn.
  2. Start the project with yarn dev (make sure you don't have another server running on port 3000).
  3. Navigate to the docs you want to edit: cd docs/pages/versions/unversioned/
  4. If you update an older version, ensure the relevant changes are copied into unversioned/

📝 Writing a Commit Message

If this is your first time committing to a large public repo, you could look through this neat tutorial: "How to Write a Git Commit Message"

Commit messages are most useful when formatted like so: [platform][api] Title. For example if you fix a bug in the package expo-video for iOS, you could write: [ios][video] Fixed black screen bug that appears on older devices.

🔎 Before Submitting

To help keep CI green, please make sure of the following:

  • Remember to add a concise description of the change to CHANGELOG.md. This is especially helpful for breaking changes!
  • If you modified anything in packages/:
    • You transpiled the TypeScript with yarn build in the directory of whichever package you modified.
    • Run yarn lint --fix to fix the formatting of the code. Ensure that yarn lint succeeds without errors or warnings.
    • Run yarn test to ensure all existing tests pass for that package, along with any new tests you would've written.
    • All console.logs or commented out code blocks are removed! :]
  • If you edited the docs/:
    • Any change to the current SDK version should also be in the unversioned copy as well. Example:
      • You fixed a typo in docs/pages/versions/vXX.0.0/sdk/app-auth.md
      • Ensure you copy that change to: docs/pages/versions/unversioned/sdk/app-auth.md
    • You don't need to run the docs tests locally. Just ensure the links you include aren't broken, and the format is correct!

Extra Credit

  • Our CI tests will finish early if you didn't make changes to certain directories. If you want to get results faster then you should make changes to docs/ in one PR, and changes to anything else in another!