Contributing guidelines & docs (#1542)

* add basic contributing guidelines to docs

* some English and formatting

* Add badges to README.md

* docs - how to run on android

* markdown formatting

* Add troubleshooting of old node

* Fix formattting

* Fix markdown and troubleshooting

CONTRIBUTING.md

@@ -1,22 +1,8 @@
 # Contributing
-## Folder Structure
 
-| Folder | Description |
-| ------ | ----------- |
-| `lib` | The project itself composed of: |
-| `lib/android` | android sources and unit tests |
-| `lib/ios` | iOS sources and unit tests |
-| `lib/src` | javascript sources and unit tests |
-| `lib/src/index.js` | the entry point for `import Navigation from 'react-native-navigation'` |
-| `e2e` | [detox](https://github.com/wix/detox) iOS e2e tests (in the future, once detox supports it, we will have android e2e here as well) |
-| `AndroidE2E` | Android e2e tests using native uiautomator (until detox for android is ready) |
-| `playground` | The end-user project all e2e tests run against. Contains its own `src`, `android` and `ios`. Does not have its own package.json, depends on the local `<root>/lib` in order not to go through npm. |
-| `integration` | misc javascript integration tests |
-| `scripts` | all scripts |
-
-## Running locally
+Thanks for you interest in helping out! We'd love your contributions, and there's plenty of work to be done regardless of your skill level. Before you start, you'll need to have some things installed in your environment so that you can run locally.
 
-### Environment requirements
+## Environment Requirements
 
 * Mac OSX
 * Latest stable XCode
@@ -57,7 +43,71 @@ export CODE_SIGNING_REQUIRED=NO
 brew tap facebook/fb && brew install fbsimctl
 ```
 
-### Scripts
+## Basics - Getting Started
+
+Got your environment set up? Go ahead and clone the repo. (Fork it first so you can open a PR when you're ready.)
+
+Then:
+
+1. Install dependencies:
+
+    ```
+    yarn install
+    ```
+
+1. Run the playground project in Android and iOS so that you can get a feel for the project.
+  
+    1. `yarn start` to get the package running in a terminal, leave it open
+
+    1. iOS: `yarn xcode` & run the project from XCode
+    
+    1. Android: Open the app in Android Studio and click `Run`   
+
+1. Run the tests. Before you start changing things, make sure everything works.
+
+     ```
+     yarn test-all
+     ```
+
+## Troubleshooting
+
+* If the tests fail with an error like `Ineligible destinations for the "ReactNativeNavigation" scheme`, double check that you have the latest XCode installed.
+* If the tests fail because an Android emulator isn't available (something like `com.android.builder.testing.api.DeviceException: No connected devices!`), start the Android project from Android Studio and leave the emulator running, then try again.
+* If the tests fail with an error such as: 
+
+```js
+
+ beforeEach(async () => {
+                   ^
+SyntaxError: Unexpected token (
+
+```
+    
+You probably have an old node version which doesn't support async functions. Update your node using nvm according to the instructions above.
+
+## Workflow
+This project is driven by tests. Before implementing any feature or fixing any bug, a failing test (e2e or unit or both) should be added, depending on the environment of where the fix should be implemented. For example, for an API change, a failing e2e should be written. For a small bug fix in Android, for example, a unit test in Android should be added.
+
+This will ensure good quality throughout the life of the project and will avoid unexpected breakages.
+
+No PR will be accepted without adequate test coverage.
+
+## Folder Structure
+
+| Folder | Description |
+| ------ | ----------- |
+| `lib` | The project itself composed of: |
+| `lib/android` | android sources and unit tests |
+| `lib/ios` | iOS sources and unit tests |
+| `lib/src` | javascript sources and unit tests |
+| `lib/src/index.js` | the entry point for `import Navigation from 'react-native-navigation'` |
+| `e2e` | [detox](https://github.com/wix/detox) iOS e2e tests (in the future, once detox supports it, we will have android e2e here as well) |
+| `AndroidE2E` | Android e2e tests using native uiautomator (until detox for android is ready) |
+| `playground` | The end-user project all e2e tests run against. Contains its own `src`, `android` and `ios`. Does not have its own package.json, depends on the local `<root>/lib` in order not to go through npm. |
+| `integration` | misc javascript integration tests |
+| `scripts` | all scripts |
+
+## Scripts
 
 | Command | Description |
 | ------- | ----------- |
@@ -75,12 +125,3 @@ brew tap facebook/fb && brew install fbsimctl
 | `yarn test-e2e-android` | runs the android e2e suite (with uiautomator) in debug/release on running devices/emulators <br> **Options:** `-- [release] [just com.TestClass#testMethod]` |
 | `yarn test-all` | runs all tests in parallel |
 
-## Workflow
-This project is driven by tests. Before implementing any feature or fixing any bug, a failing test (e2e or unit or both) should be added, depending on the environment of where the fix should be implemented. For example, for an API change, a failing e2e should be written. For a small bug fix in Android, for example, a unit test in Android should be added.
-
-This will ensure good quality throughout the life of the project and will avoid unexpected breakages.
-
-No PR will be accepted without adequate test coverage.
-
-To run the tests, use the scripts above.
-

README.md

@@ -1,3 +1,8 @@
+[![NPM Version](https://img.shields.io/npm/v/react-native-navigation.svg?style=flat)](https://www.npmjs.com/package/react-native-navigation)
+[![NPM Downloads](https://img.shields.io/npm/dm/react-native-navigation.svg?style=flat)](https://www.npmjs.com/package/react-native-navigation)
+[![Build Status](https://travis-ci.org/wix/react-native-navigation.svg?branch=v2)](https://travis-ci.org/wix/react-native-navigation)
+[![Join us on Discord](https://img.shields.io/badge/discord-react--native--navigation-738bd7.svg?style=flat)](https://discord.gg/DhkZjq2)
+
 #  React Native Navigation v2 (WIP)
 We are rebuilding react-native-navigation
 
@@ -5,19 +10,19 @@ We are rebuilding react-native-navigation
 - [Where is it standing now?](#where-is-it-standing-now)
 - [Getting Started](#getting-started-with-v2)
 - [Usage](#usage)
+- [Contributing](CONTRIBUTING.md)
 
 ## Why Rebuild react-native-navigation?
 
-### A New Improved Core Architecture
-react-native-navigation has a few issues which are unsolvable in it’s current architecture. <br>
-These issues originate from the same problem: you cannot specify on which screen you wish to make an action. Whenever you want to push a screen, show a modal or any other action, the action defaults to originate from your current screen. This covers most use cases but there are some edge cases: <br>
+### A New & Improved Core Architecture
+react-native-navigation has a few issues which are unsolvable in its current architecture. These issues stem from the same problem: you cannot specify on which screen you wish to make an action. Whenever you want to push a screen, show a modal or any other action, the action defaults to originate from your current screen. In most cases this is fine, but becoms problematic in specific edge cases. For example: <br>
 * What if you want to update your navbar icons and the user pops the screen? Your icons might update on the wrong screen.
 * What if you want to push a screen as a result of a redux action?
 
 There are ways to solve some of these problems in v1 but they are not straightforward. We want to change that.
 
 #### New API
-To solve this problem in v2, every screen receives as a prop it’s containerId. Whenever you want to perform an action from that screen you need to pass the containerId to the function:
+To solve this problem in v2, every screen receives its `containerId` as a prop. Whenever you want to perform an action from that screen you need to pass the `containerId` to the function:
 ```js
 Navigator.pop(this.props.containerId)
 ```
@@ -29,9 +34,9 @@ v2 is written with contributors in mind from day one.
 v2 is written in Test Driven Development. We have a test for every feature including features that are not implemented yet. This makes accepting pull requests extremely easy: If our tests pass, your pull request is accepted.
 
 
-## Where is it standing now?
-v2 currently supports most of react-native-navigation’s basic functions but it is still behind v1.
-Here is the full comparison of features between v1 and v2 (will be updated regulary):
+## Current Status
+v2 currently supports most of react-native-navigation’s basic functionality but it is still behind v1.
+Here is the full comparison of features between v1 and v2 (will be updated regularly):
 ### Top Level API
 
 |    API              | v1  | v2 |
@@ -71,7 +76,7 @@ Here is the full comparison of features between v1 and v2 (will be updated regul
 
 ### Styles
 
-Note:  properties who begin with 'navBar' in v1 are now named 'topBar' to avoid confusion with the android native bottom nav bar.
+Note:  v1 properties with names beginning with 'navBar' are replaced in v2 with properties beginning with 'topBar' to avoid confusion with the Android native bottom nav bar.
 
 |                       | v1  | v2 iOS | v2 Android |
 |-----------------------|-----|--------|------------|