Update Getting Started instructions.

Summary:
I am starting fresh on a new Mac and took another stab at the instructions.

- Java SDK 7 seems to work just fine.
- Adjusted Custom Android Studio installation instructions to use bare minimum required.
- Updated AVD configuration instructions with necessary changes to run AVD the first time.
- Added note on using real devices.
- Removed notes warning against use of API Level 23, these do not belong on a Getting Started guide.
- Added step to install Xcode Command Line Tools.
- Use `.profile` over `.bashrc` as the latter is shell-specific and is not loaded on login shells (e.g. new Terminal windows). `.profile` will work on bash, however, which is the default macOS shell.
- Added screenshots.

Went through steps for setting up RN for iOS as well as Android on a new Mac. Ended with apps running on the iOS Simulator and a AVD.

Generated website and verified instructions rendered correctly for each of the OS/device permutations.
Closes https://github.com/facebook/react-native/pull/12272

Differential Revision: D4637737

Pulled By: hramos

fbshipit-source-id: 5d322e4d55dbabc70f70471622a2f379ac6230cb

docs/GettingStarted.md

@@ -146,6 +146,10 @@ npm install -g react-native-cli
 
 The easiest way to install Xcode is via the [Mac App Store](https://itunes.apple.com/us/app/xcode/id497799835?mt=12). Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.
 
+You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.
+
+![Xcode Command Line Tools](img/XcodeCommandLineTools.png)
+
 <block class="mac linux windows android" />
 
 ### Android Development Environment
@@ -158,20 +162,13 @@ Setting up your development environment can be somewhat tedious if you're new to
 
 <block class="mac android" />
 
-> Android Studio requires the [Java SE Development Kit(JDK)](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html), version 8. You can type `javac -version` in a terminal to see what version you have, if any.
-
-```
-$ javac -version
-javac 1.8.0_111
-```
-
-> The version string `1.8.x_xxx` corresponds to JDK 8.
+> Android Studio requires a recent version of the [Java SE Development Kit (JDK)](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
 
 <block class="mac windows android" />
 
 #### 2. Install the AVD and HAXM
 
-Choose `Custom` installation when running Android Studio for the first time. Make sure the boxes next to all of the following are checked:
+Android Virtual Devices allow you to run Android apps on your computer without the need for an actual Android phone or tablet. Choose `Custom` installation when running Android Studio for the first time. Make sure the boxes next to all of the following are checked:
 
 - `Android SDK`
 - `Android SDK Platform`
@@ -186,7 +183,7 @@ Then, click "Next" to install all of these components.
 
 #### 2. Install the AVD and configure VM acceleration
 
-Choose `Custom` installation when running Android Studio for the first time. Make sure the boxes next to all of the following are checked:
+Android Virtual Devices allow you to run Android apps on your computer without the need for an actual Android phone or tablet. Choose `Custom` installation when running Android Studio for the first time. Make sure the boxes next to all of the following are checked:
 
 - `Android SDK`
 - `Android SDK Platform`
@@ -206,10 +203,11 @@ Select the "SDK Platforms" tab from within the SDK Manager, then check the box n
 
 - `Google APIs`
 - `Android SDK Platform 23`
-- `Intel x86 Atom System Image`
 - `Intel x86 Atom_64 System Image`
 - `Google APIs Intel x86 Atom_64 System Image`
 
+![Android SDK Manager](img/AndroidSDKManager.png)
+
 Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build Tools" entry, then make sure that `Android SDK Build-Tools 23.0.1` is selected.
 
 Finally, click "Apply" to download and install the Android SDK and related build tools.
@@ -222,7 +220,7 @@ The React Native command line interface requires the `ANDROID_HOME` environment
 
 <block class="mac android" />
 
-Add the following lines to your `~/.bashrc` (or equivalent) config file:
+Add the following lines to your `~/.profile` (or equivalent) config file:
 
 ```
 export ANDROID_HOME=${HOME}/Library/Android/sdk
@@ -230,11 +228,13 @@ export PATH=${PATH}:${ANDROID_HOME}/tools
 export PATH=${PATH}:${ANDROID_HOME}/platform-tools
 ```
 
+Type `source ~/.profile` to load the config into your current shell.
+
 > Please make sure you export the correct path for `ANDROID_HOME`. If you installed the Android SDK using Homebrew, it would be located at `/usr/local/opt/android-sdk`.
 
 <block class="linux android" />
 
-Add the following lines to your `~/.bashrc` (or equivalent) config file:
+Add the following lines to your `~/.profile` (or equivalent) config file:
 
 ```
 export ANDROID_HOME=${HOME}/Android/Sdk
@@ -242,6 +242,8 @@ export PATH=${PATH}:${ANDROID_HOME}/tools
 export PATH=${PATH}:${ANDROID_HOME}/platform-tools
 ```
 
+Type `source ~/.profile` to load the config into your current shell.
+
 > Please make sure you export the correct path for `ANDROID_HOME` if you did not install the Android SDK using Android Studio.
 
 <block class="windows android" />
@@ -276,9 +278,15 @@ You can see the list of available AVDs by opening the "AVD Manager" from within
 android avd
 ```
 
-Once in the "AVD Manager", select your AVD and click "Start...".
+Once in the "AVD Manager", select your AVD and click "Edit...". Choose "Android 6.0 - API Level 23" under Device, and "Intel Atom (x86_64)" under CPU/ABI. Click OK, then select your new AVD and click "Start...", and finally, "Launch".
 
-> Android Studio should have set up an Android Virtual Device for you during installation, but it is very common to run into an issue where Android Studio fails to install the AVD. You may follow the [Android Studio User Guide](https://developer.android.com/studio/run/managing-avds.html) to create a new AVD manually if needed.
+![Android AVD Configuration](img/AndroidAVDConfiguration.png)
+
+> It is very common to run into an issue where Android Studio fails to create a default AVD. You may follow the [Android Studio User Guide](https://developer.android.com/studio/run/managing-avds.html) to create a new AVD manually if needed.
+
+### Using a real device
+
+If you have a physical Android device, you can use it for development in place of an AVD. Plug it in to your computer using a USB cable and [enable USB debugging](https://developer.android.com/training/basics/firstapp/running-app.html) before proceeding to the next step.
 
 <block class="mac ios android" />
 
@@ -296,6 +304,8 @@ react-native run-ios
 
 You should see your new app running in the iOS Simulator shortly.
 
+![AwesomeProject on iOS](img/iOSSuccess.png)
+
 `react-native run-ios` is just one way to run your app. You can also run it directly from within Xcode or [Nuclide](https://nuclide.io/).
 
 <block class="mac android" />
@@ -308,7 +318,9 @@ cd AwesomeProject
 react-native run-android
 ```
 
-If everything is set up correctly, you should see your new app running in your AVD shortly.
+If everything is set up correctly, you should see your new app running in your Android emulator shortly.
+
+![AwesomeProject on Android](img/AndroidSuccess.png)
 
 `react-native run-android` is just one way to run your app - you can also run it directly from within Android Studio or [Nuclide](https://nuclide.io/).
 
@@ -348,7 +360,7 @@ cd AwesomeProject
 react-native start
 ```
 
-Open a new command prompt and run `react-native run-android` inside the same folder to launch the app on your AVD.
+Open a new command prompt and run `react-native run-android` inside the same folder to launch the app on your Android emulator.
 
 ```
 react-native run-android
@@ -370,11 +382,7 @@ react-native run-android
 
 If everything is set up correctly, you should see your new app running in your Android emulator shortly.
 
-<block class="windows android" />
-
-> If you're targeting API level 23, the app might crash on first launch with an error smilar to `Unable to add window android.view.ViewRootImpl$W@c51fa6 -- permission denied for this window type`. To fix this, you need to go to `System settings > Apps > Configure apps > Draw over other apps` and grant the permission for the app.
-
-NOTE: Many React Native modules haven't been tested on Marshmallow and might break. Please thoroughly test the app if you target API level 23 and file a bug report if you find that something is broken.
+![AwesomeProject on Android](img/AndroidSuccess.png)
 
 <block class="windows linux android" />
 

docs/Testing.md

@@ -8,15 +8,17 @@ next: running-on-device
 previous: debugging
 ---
 
-## Running Tests and Contributing
-
 This document is about running tests on React Native itself. If you're interested in testing a React Native app, check out the [React Native Tutorial](http://facebook.github.io/jest/docs/tutorial-react-native.html) on the Jest website.
 
-The React Native repo has several tests you can run to verify you haven't caused a regression with your PR.  These tests are run with the [Travis](http://docs.travis-ci.com/) and [CircleCI](https://circleci.com/) continuous integration systems, which will automatically annotate pull requests with the test results.
+## Running Tests and Contributing
+
+The React Native repo has several tests you can run to verify you haven't caused a regression with your PR.  These tests are run with the [Travis](https://travis-ci.org/facebook/react-native/builds) and [CircleCI](https://circleci.com/gh/facebook/react-native) continuous integration systems, which will automatically annotate pull requests with the test results.
 
 Whenever you are fixing a bug or adding new functionality to React Native, you should add a test that covers it. Depending on the change you're making, there are different types of tests that may be appropriate.
 
-## Jest Tests
+## JavaScript Tests
+
+### Jest
 
 Jest tests are JavaScript-only tests run on the command line with node. You can run the existing React Native jest tests with:
 
@@ -27,9 +29,25 @@ It's a good idea to add a Jest test when you are working on a change that only m
 
 The tests themselves live in the `__tests__` directories of the files they test.  See [`TouchableHighlight-test.js`](https://github.com/facebook/react-native/blob/master/Libraries/Components/Touchable/__tests__/TouchableHighlight-test.js) for a basic example.
 
-## Android Unit Tests
+### Flow
 
-The Android unit tests do not run in an emulator. They just use a normal Java installation. You do need to install Java 8. In particular, the default OS X Java install is insufficient.
+You should also make sure your code passes [Flow](https://flowtype.org/) tests. These can be run using:
+
+    $ cd react-native
+    $ npm run flow
+
+## Android
+
+### Unit Tests
+
+The Android unit tests do not run in an emulator. They just use a normal Java installation. The default macOS Java install is insufficient, you may need to install [Java 8 (JDK8)](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). You can type `javac -version` in a terminal to see what version you have:
+
+```
+$ javac -version
+javac 1.8.0_111
+```
+
+The version string `1.8.x_xxx` corresponds to JDK 8.
 
 You also need to install the [Buck build tool](https://buckbuild.com/setup/install.html).
 
@@ -40,7 +58,7 @@ To run the Android unit tests:
 
 It's a good idea to add an Android unit test whenever you are working on code that can be tested by Java code alone. The Android unit tests live under [`ReactAndroid/src/tests`](https://github.com/facebook/react-native/tree/master/ReactAndroid/src/test/java/com/facebook/react), so you can browse through that directory for good examples of tests.
 
-## Android Integration Tests
+### Integration Tests
 
 To run the integration tests, you need to install the Android NDK. See [Prerequisites](docs/android-building-from-source.html#prerequisites).
 
@@ -62,14 +80,46 @@ The integration tests should only take a few minutes to run on a modern develope
 
 It's a good idea to add an Android integration test whenever you are working on code that needs both JavaScript and Java to be tested in conjunction. The Android integration tests live under [`ReactAndroid/src/androidTest`](https://github.com/facebook/react-native/tree/master/ReactAndroid/src/androidTest/java/com/facebook/react/tests), so you can browse through that directory for good examples of tests.
 
-## iOS Integration Tests
+## iOS
 
-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 ReactNative environment and provides facilities to run the tests as `XCTestCase`s in Xcode (`runTest:module` is the simplest method).  `RCTTestModule` is exported to JS 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.  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.  See [`IntegrationTestHarnessTest.js`](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestHarnessTest.js), [`UIExplorerIntegrationTests.m`](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/UIExplorerIntegrationTests/UIExplorerIntegrationTests.m), and [IntegrationTestsApp.js](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestsApp.js) for example usage and integration points.
+### Integration Tests
 
-You can run integration tests locally with cmd+U in the IntegrationTest and UIExplorer apps in Xcode.
+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 ReactNative environment and provides facilities to run the tests as `XCTestCase`s in Xcode (`runTest:module` is the simplest method).  `RCTTestModule` is exported to JS as `NativeModules.TestModule`.  
 
-## iOS Screenshot/Snapshot Tests
+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.  
+
+See the following for example usage and integration points:
+
+- [`IntegrationTestHarnessTest.js`](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestHarnessTest.js)
+- [`UIExplorerIntegrationTests.m`](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/UIExplorerIntegrationTests/UIExplorerIntegrationTests.m)
+- [`IntegrationTestsApp.js`](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestsApp.js)
+
+You can run integration tests locally with cmd+U in the IntegrationTest and UIExplorer apps in Xcode, or by running the following in the command line on macOS:
+
+    $ cd react-native
+    $ ./scripts/objc-test-ios.sh
+
+> Your Xcode install will come with a variety of Simulators running the latest OS. You may need to manually create a new Simulator to match what the `XCODE_DESTINATION` param in the test script.
+
+### Screenshot/Snapshot Tests
 
 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.  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/master/IntegrationTests/SimpleSnapshotTest.js) for a basic example.
 
 If you make a change that affects a snapshot test in a PR, 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, simply change to `_runner.recordMode = YES;` in [UIExplorer/UIExplorerSnapshotTests.m](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/UIExplorerIntegrationTests/UIExplorerSnapshotTests.m#L42), re-run the failing tests, then flip record back to `NO` and submit/update your PR and wait to see if the Travis build passes.
+
+## End-to-end tests
+
+Finally, make sure end-to-end tests run successfully by executing the following script:
+
+    $ cd react-native
+    $ ./scripts/test-manual-e2e.sh
+
+## Website
+
+The React Native website is hosted on GitHub pages and is automatically generated from Markdown sources as well as comments in the JavaScript source files. It's always a good idea to check that the website is generated properly whenever you edit the docs.
+
+    $ cd website
+    $ npm install
+    $ npm start
+
+Then open http://localhost:8079/react-native/index.html in your browser.