Update docs, scripts

README.md

@@ -1,5 +1,7 @@
 ![MetaMask logo](logo.png?raw=true)
+
 # MetaMask
+
 [![CircleCI](https://circleci.com/gh/MetaMask/metamask-mobile/tree/develop.svg?style=shield)](https://circleci.com/gh/MetaMask/metamask-mobile/tree/develop)
 
 MetaMask is a mobile web browser that provides easy access to websites that use the [Ethereum](https://ethereum.org/) blockchain.
@@ -10,57 +12,156 @@ To learn how to develop MetaMask-compatible applications, visit our [Developer D
 
 ## MetaMask Mobile
 
-### Building locally
+### Building Locally
+
 The code is built using React-Native and running code locally requires a Mac or Linux OS.
 
 - Install [Node.js](https://nodejs.org) **version 10 (latest stable) and yarn@1 (latest)**
-    - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you.
+  - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you.
 
-- Before starting, you need to install React Native dependencies:
-    - [MacOs](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-1)
-    - [Linux](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-2)
-- Now clone this repo and then install all our dependencies.
+- Install the shared React Native dependencies (`React Native CLI`, _not_ `Expo CLI`)
+  - [macOS](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-1)
+  - [Linux](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-2)
+
+- _MetaMask Only:_ Rename the `.*.env.example` files (remove the `.example`) in the root of the project and fill in the appropriate values for each key. Get the values from another MetaMask Mobile developer.
+
+- Clone this repo and install our dependencies:
 
 ```bash
+git clone ...
 cd metamask-mobile
-yarn install
+yarn install # this will run a lengthy postinstall flow
 ```
-- Rename the `.*.env.example` files (remove the `.example`) in the root of the project and fill in the appropriate values for each key.
 
-- Running the app on Android:
+- Then, in one terminal, run:
+
+```bash
+yarn watch
+```
 
-You will need the `secret-tool` (a part of [libsecret-tools](https://launchpad.net/ubuntu/bionic/+package/libsecret-tools) package on Debian/Ubuntu based distributions) binary on your machine. You'll also want to have the android SDK; the easiest way to do that is by installing [Android Studio](https://developer.android.com/studio). Additionally, you'll need to install the Google Play Licencing Library via the SDK Manager in Android Studio.
+#### Android
+
+- Install the Android SDK, via [Android Studio](https://developer.android.com/studio).
+  - _MetaMask Only:_ To create production builds, you need to install Google Play Licensing Library via the SDK Manager in Android Studio.
+- Linux only:
+  - Ensure that you have the `secret-tool` binary on your machine.
+    - Part of the [libsecret-tools](https://launchpad.net/ubuntu/bionic/+package/libsecret-tools) package on Debian/Ubuntu based distributions.
+- Install the correct emulator
+  - Follow the instructions at:
+    - [React Native Getting Started - Android](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-1) _(React Native CLI Quickstart -> [your OS] -> Android)_
+    - More details can be found [on the Android Developer site](https://developer.android.com/studio/run/emulator)
+  - You should use the following:
+    - **Android OS Version:** Latest, unless told otherwise
+    - **Device:** Google Pixel 3
+- Finally, start the emulator from Android Studio, and run:
 
 ```bash
 yarn start:android
 ```
 
-- Running the app on iOS:
+#### iOS
+
+- Install the iOS dependencies
+  - [React Native Getting Started - iOS](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-1) _(React Native CLI Quickstart -> [your OS] -> iOS)_
+    - You do **not** need CocoaPods
+- Install the correct simulator
+  - **iOS OS Version:** Latest, unless told otherwise
+  - **Device:** iPhone 11 Pro
 
 ```bash
 yarn start:ios
 ```
 
-### Running tests:
- - Unit test:
+#### Build Troubleshooting
+
+Unfortunately, the build system may fail to pick up local changes, such as installing new NPM packages or `yarn link`ing a dependency.
+If the app is behaving strangely or not picking up your local changes, it may be due to build issues.
+To ensure that you're starting with a clean slate, close all emulators/simulators, stop the `yarn watch` process, and run:
+
+```bash
+yarn clean
+
+# if you're going to `yarn link` any packages,
+# do that here, before the next command
+
+yarn watch:clean
+
+# ...and then, in another terminal
+
+yarn start:ios
+
+# or
+
+yarn start:android
 ```
+
+If `yarn link` fails after going through these steps, try directly `yarn add`ing the local files instead.
+
+### Debugging
+
+First, make sure you have the following running:
+
+- `yarn watch`
+- Your Android emulator or iOS simulator
+- `yarn start:android` or `yarn start:ios`
+
+Next, check that the React Native Debugger is working:
+
+- Open your emulator or simulator, and select `Debug JS Remotely` from its menu
+  - You can also try to navigate to this URL in Chrome: http://localhost:8081/debugger-ui/
+- If that doesn't take you to the React Native Debugger, something is wrong
+
+#### Debugging iOS (macOS Only)
+
+For more details, see [this page](https://medium.com/@mattcroak718/debugging-your-iphone-mobile-web-app-using-safari-development-tools-71240657c487).
+
+- You should be able to inspect the mobile app using the console in the React Native Debugger tab
+- To debug a website (dapp) in the browser:
+  - Navigate to the website in the app's browser
+  - Open Safari
+    - Go to: _Preferences -> Advanced_ and select `Show Develop menu in menu bar`
+  - Select `Develop` in the menu bar
+    - Find your simulator in the second section from the top
+    - Select the relevant WebView from the list
+      - The simulator will highlight the WebView when you hover over it in Safari
+
+#### Debugging Android
+
+For more details, see [this page](https://developers.google.com/web/tools/chrome-devtools/remote-debugging/webviews).
+
+- You should be able to inspect the mobile app using the console in the React Native Debugger tab
+- To debug a website (dapp) in the browser:
+  - Navigate to the website in the app's browser
+  - Go to chrome://inspect
+  - Select the relevant WebView under **Remote Target**
+
+#### Miscellaneous
+
+- [Troubleshooting for React Native](https://facebook.github.io/react-native/docs/troubleshooting#content)
+
+### Running Tests
+
+- Unit tests:
+
+```bash
 yarn test:unit
 ```
- - E2E Tests (iOS)
-```
+
+- E2E tests (iOS)
+
+```bash
 yarn test:e2e:ios
 ```
- - E2E Tests (Android)
-```
+
+- E2E tests (Android)
+
+```bash
 yarn test:e2e:android
 ```
 
 ### Architecture
-To get a better understanding of the internal architecture of this app take a look at [this diagram](https://github.com/MetaMask/metamask-mobile/blob/develop/architecture.svg)
-
-### Troubleshooting
 
-Visit [Troubleshooting for React Native](https://facebook.github.io/react-native/docs/troubleshooting#content)
+To get a better understanding of the internal architecture of this app take a look at [this diagram](https://github.com/MetaMask/metamask-mobile/blob/develop/architecture.svg).
 
 ## License
 

package.json

@@ -3,8 +3,12 @@
   "version": "0.2.13",
   "private": true,
   "scripts": {
-    "restart-packager-clean": "watchman watch-del-all && rm -rf $TMPDIR/react-* && yarn start -- --reset-cache",
-    "start": "node node_modules/react-native/local-cli/cli.js start",
+    "watch": "node node_modules/react-native/local-cli/cli.js start",
+    "watch:clean": "watchman watch-del-all && rm -rf $TMPDIR/react-* && yarn watch -- --reset-cache",
+    "clean:ios": "rm -rf ios/build",
+    "clean:android": "rm -rf android/build",
+    "clean:node": "rm -rf node_modules && yarn install",
+    "clean": "yarn clean:ios && yarn clean:android && yarn clean:node && yarn install",
     "lint": "eslint '**/*.js' --ignore-path=.prettierignore",
     "lint:fix": "eslint '**/*.js' --fix --ignore-path=.prettierignore",
     "format": "prettier '**/*.{js,json}' --write",