[RNMobile] Improvements to Getting Started Guides (#40964)

* Update with copy from Gutenberg Mobile Gutenberg Mobile's readme had some copy in the troubleshooting section that wasn't included in Gutenberg's how-to: https://github.com/wordpress-mobile/gutenberg-mobile/edit/trunk/README.md This commit fixes that issue by updating Gutenberg's how-to with the latest from Gutenberg Mobile. * Tweak wording, update inconsistent capitalisation * Tweaks to copy and formatting With this commit, I've tidied up some of the copy, attempting to make the instructions as concise and helpful as possible. I've also set the images to the same width to tidy up the overall look of the document (the images will appear small on mobile devices, but can be tapped on to get the full image). * Set all images to fixed width, for consistency * Rearrange sections to improve overall flow - The "Unit Tests" is moved towards the bottom of the document, so that's it's closer to the instructions for integration tests. the document flows as follows: - The steps for installing Xcode are moved under the "iOS" section. - The overall flow of the document has been updated to the following: Clone Gutenberg > iOS > Android > Tests * Add details about recommended JDK * Add details about Cocoapods * Refine instructions for installing Cocoapods * Note `ffi` may already be installed Some versions of Ruby may not require the `ffi` to be manually installed, which is noted with this commit.
WordPress · May 24, 2022 · 148f835 · 148f835
1 parent 1b3391e
commit 148f835
Show file tree

Hide file tree

Showing 2 changed files with 90 additions and 78 deletions.
diff --git a/docs/contributors/code/react-native/getting-started-react-native.md b/docs/contributors/code/react-native/getting-started-react-native.md
@@ -72,6 +72,8 @@ To see a list of all of your available iOS devices, use `xcrun simctl list devic
 
 ### Troubleshooting
 
+If the Android emulator doesn't start correctly, or compiling fails with `Could not initialize class org.codehaus.groovy.runtime.InvokerHelper` or similar, it may help to double check the set up of your development environment against the latest requirements in [React Native's documentation](https://reactnative.dev/docs/environment-setup). With Android Studio, for example, you will need to configure the `ANDROID_HOME` environment variable and ensure that your version of JDK matches the latest requirements.
+
 Some times, and especially when tweaking anything in the `package.json`, Babel configuration (`.babelrc`) or the Jest configuration (`jest.config.js`), your changes might seem to not take effect as expected. On those times, you might need to stop the metro bunder process and restart it with `npm run native start:reset`. Other times, you might want to reinstall the NPM packages from scratch and the `npm run native clean:install` script can be handy.
 
 ## Developing with Visual Studio Code

diff --git a/docs/contributors/code/react-native/osx-setup-guide.md b/docs/contributors/code/react-native/osx-setup-guide.md
@@ -1,67 +1,36 @@
 # Setup guide for React Native development (macOS)
 
-Are you interested in contributing to the native mobile editor? This
-guide is a detailed walk through designed to get you up and running!
+Are you interested in contributing to the native mobile editor? This guide is a detailed walk through designed to get you up and running!
 
-Note that the following instructions here are primarily focused on the
-macOS environment. For other environments, [the React Native quickstart documentation](https://reactnative.dev/docs/environment-setup)
-has helpful pointers and steps for getting set up.
-
-## Install Xcode
-
-Install [Xcode](https://developer.apple.com/xcode/) via the app store. We'll be using
-the XCode to both compile the iOS app and use the phone simulator app.
-
-Once it has been installed from the App Store, open it by visiting `Applications > Xcode`
-
-After opening the application:
-
--   Accept the license agreement.
--   Verify that `Xcode > Preferences > Locations > Command Line Tools` points at the current Xcode version.
-
-<img src="https://developer.wordpress.org/files/2021/10/xcode-command-line-tools.png" width="500" alt="Screenshot of XCode command line tools settings.">
+Note that these instructions are primarily focused on the macOS environment. For other environments, [the React Native quickstart documentation](https://reactnative.dev/docs/environment-setup) has helpful pointers and steps for getting set up.
 
 ## Clone Gutenberg
 
-If Xcode was installed successfully, we'll also have a version of git available. (It's possible to
-update this later if we want to use a more recent version).
-
-In a terminal run:
-
 ```sh
 git clone git@github.com:WordPress/gutenberg.git
 ```
 
 ### Install node and npm
 
-If you’re working in multiple JS projects, a node version manager may make sense. A manager will let you
-switch between different node and npm versions of your choosing.
-
-Some good options are [nvm](https://github.com/nvm-sh/nvm) or [volta](https://volta.sh/).
+If you’re working in multiple JS projects, a node version manager may make sense. A manager will let you switch between different node and npm versions of your choosing.
 
-Pick one and follow the install instructions noted on their website.
+We recommend [nvm](https://github.com/nvm-sh/nvm). 
 
-Then run:
+After installing nvm, run the following from the top-level directory of the cloned project:
 
 ```sh
 nvm install 'lts/*'
 nvm alias default 'lts/*' # sets this as the default when opening a new terminal
 nvm use # switches to the project settings
 ```
 
-Or
-
-```sh
-volta install node #defaults to installing lts
-```
-
-Then install dependencies from your Gutenberg checkout folder:
+Then install dependencies:
 
 ```
 npm ci
 ```
 
-#### Do you have an older existing Gutenberg checkout?
+### Do you have an older existing Gutenberg checkout?
 
 If you have an existing Gutenberg checkout be sure to fully clean `node_modules` and re-install dependencies.
 This may help avoid errors in the future.
@@ -71,28 +40,56 @@ npm run distclean
 npm ci
 ```
 
-## Unit Tests
+## iOS
 
-Unit tests should work at this point.
+### CocoaPods
 
-```sh
-npm run native test
+[CocoaPods](https://guides.cocoapods.org/using/getting-started.html) is required to fetch React and third-party dependencies. The steps to install it vary depending on how Ruby is managed on your machine.
+
+#### System Ruby
+
+If you're using the default Ruby available with MacOS, you'll need to use the `sudo` command to install gems like Cocoapods:
+
+```
+sudo gem install cocoapods
 ```
 
-## iOS
+Note, Mac M1 is not directly compatible with Cocoapods. If you encounter issues, try running these commands to install the ffi package, which will enable pods to be installed with the proper architecture:
+
+```
+sudo arch -x86_64 gem install ffi
+arch -x86_64 pod install
+```
+
+#### Ruby Manager
+
+It may not be necessary to manually install Cocoapods or the `ffi` package if you're using a Ruby Version manager. Please refer to your chosen manager's documentation for guidance. 
+
+[`rbenv`](https://github.com/rbenv/rbenv) is the recommended manager if you're running Gutenberg from within [the WordPress iOS app](https://github.com/wordpress-mobile/WordPress-iOS) (vs. only the demo app). 
 
-The easiest way to figure out what needs to be installed is using the
-[react native doctor](https://reactnative.dev/blog/2019/11/18/react-native-doctor). From your checkout, or
-relative to `/packages/react-native-editor folder`, run:
+### Set up Xcode
+
+Install [Xcode](https://developer.apple.com/xcode/) via the app store and then open it up:
+
+-   Accept the license agreement.
+-   Verify that `Xcode > Preferences > Locations > Command Line Tools` points to the current Xcode version.
+
+<img src="https://developer.wordpress.org/files/2021/10/xcode-command-line-tools.png" width="700px" alt="Screenshot of XCode command line tools settings.">
+
+### react-native doctor
+
+[react-native doctor](https://reactnative.dev/blog/2019/11/18/react-native-doctor) can be used to identify anything that's missing from your development environment. From your Gutenberg checkout, or relative to `/packages/react-native-editor folder`, run:
 
 ```sh
 npx @react-native-community/cli doctor
 ```
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-doctor.png" width="500px" alt="Screenshot of react-native-community/cli doctor tool running in the terminal.">
+<img src="https://developer.wordpress.org/files/2021/10/react-native-doctor.png" width="700px" alt="Screenshot of react-native-community/cli doctor tool running in the terminal.">
 
 See if `doctor` can fix both "common" and "iOS" issues. (Don't worry if "Android" still has ❌s at this stage, we'll get to those later!)
 
+### Run the demo app
+
 Once all common and iOS issues are resolved, try:
 
 ```
@@ -105,37 +102,46 @@ In another terminal type:
 npm run native ios
 ```
 
-After waiting for everything to build we should see:
+After waiting for everything to build, the demo app should be running from the iOS simulator:
 
-<img src="https://developer.wordpress.org/files/2021/10/iOS-Simulator.png" alt="Screenshot of the block editor in iOS simulator." />
+<img src="https://developer.wordpress.org/files/2021/10/iOS-Simulator.png" width="700px" alt="Screenshot of the block editor in iOS simulator." />
 
 ## Android
 
-To keep things simple, let's use Android Studio for all JDK and SDK package management.
-The first step is [downloading Android Studio](https://developer.android.com/studio).
+### Java Development Kit (JDK)
 
-Next, open an existing project and select the gutenberg folder you cloned:
+The JDK recommended in [the React Native documentation](https://reactnative.dev/docs/environment-setup) is called Azul Zulu. It can be installed using [Homebrew](https://brew.sh/). To install it, run the following commands in a terminal after installing Homebrew:
 
-Click on the cube with the down arrow:
+```
+brew tap homebrew/cask-versions
+brew install --cask zulu11
+```
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-package-manager.png" alt="Screenshot highlighting where the package manager button is located in Android Studio.">
+If you already have a JDK installed on your system, it should be JDK 11 or newer.
 
-We can download SDK platforms, packages and other tools on this screen. Specific versions are
-hidden behind the "Show package details" checkbox, check it, since our build requires specific versions for E2E and
-development:
+### Set up Android Studio
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-show-package-details.png" alt="Screenshot of the package manager in Android Studio, highlighting the Show Package Details checkbox.">
+To compile the Android app, [download Android Studio](https://developer.android.com/studio). 
 
-Check all related packages from [build.gradle](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/android/build.gradle).
-Then click on "Apply" to download items. There may be other related dependencies from build.gradle files in node_modules.
-If you don’t want to dig through files, stack traces will complain of missing packages, but it does take quite a number
-of tries if you go through this route.
+Next, open an existing project and select the Gutenberg folder you cloned. 
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-editor-build-gradle.png" alt="Screenshot of the build.gradle configuration file.">
+From here, click on the cube icon that's highlighted in the following screenshot to access the SDK Manager. Another way to the SDK Manager is to navigate to `Tools > SDK Manager`:
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-sdk.png" width="500" alt="Screenshot of the package manager displaying SDK Platforms.">
+<img src="https://developer.wordpress.org/files/2021/10/react-native-package-manager.png" width="700px" alt="Screenshot highlighting where the package manager button is located in Android Studio.">
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-sdk-tools.png" width="500" alt="Screenshot of the package manager displaying SDK Tools.">
+We can download SDK platforms, packages and other tools on this screen. Specific versions are hidden behind the "Show package details" checkbox, check it, since our build requires specific versions for E2E and development:
+
+<img src="https://developer.wordpress.org/files/2021/10/react-native-show-package-details.png" width="700px" alt="Screenshot of the package manager in Android Studio, highlighting the Show Package Details checkbox.">
+
+Check all related packages from [build.gradle](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/android/build.gradle). Then click on "Apply" to download items. There may be other related dependencies from build.gradle files in node_modules.
+
+If you don’t want to dig through files, stack traces will complain of missing packages, but it does take quite a number of tries if you go through this route.
+
+<img src="https://developer.wordpress.org/files/2021/10/react-native-editor-build-gradle.png" width="700px" alt="Screenshot of the build.gradle configuration file.">
+
+<img src="https://developer.wordpress.org/files/2021/10/react-native-sdk.png" width="700px" alt="Screenshot of the package manager displaying SDK Platforms.">
+
+<img src="https://developer.wordpress.org/files/2021/10/react-native-sdk-tools.png" width="700px" alt="Screenshot of the package manager displaying SDK Tools.">
 
 ### Update Paths
 
@@ -167,26 +173,25 @@ source ~/.bash_profile
 
 If the SDK path can't be found, you can verify its location by visiting Android Studio > Preferences > System Settings > Android SDK
 
-<img src="https://developer.wordpress.org/files/2021/10/sdk-path.png" alt="Screenshot of where the SDK Path may be found in Android Studio.">
+<img src="https://developer.wordpress.org/files/2021/10/sdk-path.png" width="700px" alt="Screenshot of where the SDK Path may be found in Android Studio.">
 
 ### Create a new device image
 
 Next, let’s create a virtual device image. Click on the phone icon with an android to the bottom-right.
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-android-device-manager-button.png" alt="Screenshot of where to find the android device manager button.">
+<img src="https://developer.wordpress.org/files/2021/10/react-native-android-device-manager-button.png" width="700px" alt="Screenshot of where to find the android device manager button.">
 
 This brings up the “Android Virtual Device Manager” or (AVD). Click on “Create Virtual Device”. Pick a phone type of your choice:
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-android-select-hardware.png" alt="Screenshot of the Virtual Device Configuration setup.">
+<img src="https://developer.wordpress.org/files/2021/10/react-native-android-select-hardware.png" width="700px" alt="Screenshot of the Virtual Device Configuration setup.">
 
-Pick the target SDK version. This is the targetSdkVersion set in the
-[build.gradle](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/android/build.gradle) file.
+Pick the target SDK version. This is the targetSdkVersion set in the [build.gradle](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/android/build.gradle) file.
 
-<img src="https://developer.wordpress.org/files/2021/10/react-native-adv-system-image.png" alt="Screenshot of picking a system image in the Android Device Manager workflow.">
+<img src="https://developer.wordpress.org/files/2021/10/react-native-adv-system-image.png" width="700px" alt="Screenshot of picking a system image in the Android Device Manager workflow.">
 
 There are some advanced settings we can toggle, but these are optional. Click finish.
 
-### Putting it all together
+### Run the demo app
 
 Start metro:
 
@@ -202,7 +207,13 @@ npm run native android
 
 After a bit of a wait, we’ll see something like this:
 
-<img src="https://developer.wordpress.org/files/2021/10/android-simulator.png" alt="Screenshot of a the block editor in Android Simulator.">
+<img src="https://developer.wordpress.org/files/2021/10/android-simulator.png" width="700px" alt="Screenshot of a the block editor in Android Simulator.">
+
+## Unit Tests
+
+```sh
+npm run native test
+```
 
 ## Integration Tests
 
@@ -212,14 +223,13 @@ After a bit of a wait, we’ll see something like this:
 npx appium-doctor
 ```
 
-<img src="https://developer.wordpress.org/files/2021/10/CleanShot-2021-10-27-at-15.20.16.png" width="500px" alt="Screenshot of the appium-doctor tool running in the terminal.">
+<img src="https://developer.wordpress.org/files/2021/10/CleanShot-2021-10-27-at-15.20.16.png" width="700px" alt="Screenshot of the appium-doctor tool running in the terminal.">
 
 Resolve any required dependencies.
 
 ### iOS Integration Tests
 
-If we know we can run the iOS local environment without issue, E2Es for iOS are straightforward. Stop any running metro processes.
-This was launched previously with `npm run native start:reset`.
+If we know we can run the iOS local environment without issue, E2Es for iOS are straightforward. Stop any running metro processes. This was launched previously with `npm run native start:reset`.
 
 Then in terminal type:
 
@@ -243,7 +253,7 @@ If all things go well, it should look like:
 
 Start the virtual device first. Go back to the AVD by clicking on the phone icon, then click the green play button.
 
-<img src="https://developer.wordpress.org/files/2021/10/adv-integration.png" alt="A screenshot of how to start the Android Simulator.">
+<img src="https://developer.wordpress.org/files/2021/10/adv-integration.png" width="700px" alt="A screenshot of how to start the Android Simulator.">
 
 Make sure no metro processes are running. This was launched previously with `npm run native start:reset`.
 
@@ -261,4 +271,4 @@ npm run native test:e2e:android:local gutenberg-editor-paragraph.test.js
 
 After a bit of a wait we should see:
 
-<img src="https://developer.wordpress.org/files/2021/10/CleanShot-2021-10-27-at-15.28.22.png" alt="A screenshot of block editor integration tests in Android Simulator.">
+<img src="https://developer.wordpress.org/files/2021/10/CleanShot-2021-10-27-at-15.28.22.png" width="700px" alt="A screenshot of block editor integration tests in Android Simulator.">