Added contribute article, updated draft

Iva Koevska · Iva Koevska · commit 8da62868114f · 2014-08-28T14:37:21.000+03:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,93 @@
+Contribute to the Telerik NativeScript Command-Line Interface
+===
+
+*Help us improve the Telerik NativeScript CLI* 
+
+The Telerik NativeScript CLI lets you create, build, and deploy NativeScript-based projects on iOS and Android devices.
+
+* [Report an Issue](#bug "Learn how to report an issue")
+* [Request a Feature](#request "Learn how to submit a feature or improvement request")
+* [Contribute to the Code Base](#contribute "Learn how to submit your own improvements to the code")
+
+Report an Issue
+===
+If you find a bug in the source code or a mistake in the documentation, you can submit an issue to our [GitHub Repository][2].
+Before you submit your issue, search the archive to check if a similar issues has been logged or addressed. This will let us focus on fixing issues and adding new features.
+If your issue appears to be a bug, and hasn't been reported, open a new issue. To help us investigate your issue and respond in a timely manner, you can provide is with the following details.
+
+* **Overview of the issue:** Provide a short description of the visible symptoms. If applicable, include error messages, screen shots, and stack traces.
+* **Motivation for or use case:** Let us know how this particular issue affects your work.
+* **Telerik NativeScript version(s):** List the current version and build number of the CLI interface. You can get it by running `tns --version`. Let us know if you have not observed this behavior in earlier versions and if you consider it a regression.
+* **System configuration:** Provide us with relevant system configuration information such as operating system, network connection, proxy usage, etc. Let us know if you have been able to reproduce the issue on multiple setups.
+* **Steps to reproduce:** If applicable, submit a step-by-step walkthrough of how to reproduce the issue.
+* **Related issues:** If you discover a similar issue in our archive, give us a heads up - it might help us identify the culprit.
+* **Suggest a fix:** You are welcome to suggest a bug fix or pinpoint the line of code or the commit that you believe has introduced the issue.
+
+[Back to Top][1]
+
+Request a Feature
+===
+You can request a new feature by submitting an issue with the *enhancement* label to our [GitHub Repository][2].
+If you want to implement a new feature yourself, consider submitting it to the [GitHub Repository][2] as a Pull Request.
+
+[Back to Top][1]
+
+Contribute to the Code Base
+===
+
+Before you submit a Pull Request, consider the following guidelines.
+
+* Search <a href="https://github.com/Icenium/icenium-cli/pulls">GitHub</a> for an open or closed Pull Request that relates to your submission.
+* Make your changes in a new `git` branch. We use the <a href="http://nvie.com/posts/a-successful-git-branching-model/">Gitflow branching model</a> so you will have to branch from our develop branch.
+```bash
+    git checkout -b my-fix-branch develop
+```
+* Create your patch and include appropriate test cases.
+* Commit your changes and create a descriptive commit message (the commit message is used to generate release notes).
+```bash
+    git commit -a
+```
+* Build your changes locally.
+```bash
+    grunt
+```
+* Ensure all the tests pass.
+```bash
+    grunt test
+```
+* Push your branch to GitHub.
+```bash
+    git push origin my-fix-branch
+```
+* In GitHub, send a Pull Request to icenium-cli:develop.
+* If we suggest changes, you can modify your branch, rebase, and force a new push to your GitHub repository to update the Pull Request.
+```bash
+    git rebase develop -i
+    git push -f
+```
+
+That's it! Thank you for your contribution!
+
+When the patch is reviewed and merged, you can safely delete your branch and pull the changes from the main (upstream) repository.
+
+* Delete the remote branch on GitHub.
+```bash
+    git push origin --delete my-fix-branch
+```
+* Check out the develop branch.
+```bash
+    git checkout develop -f
+```
+* Delete the local branch.
+```bash
+    git branch -D my-fix-branch
+```
+* Update your develop branch with the latest upstream version.
+```
+    git pull --ff upstream develop
+```
+
+[Back to Top][1]
+
+[1]: #contribute-to-the-telerik-nativescript-command-line-interface
+[2]: https://github.com/NativeScript/nativescript-cli
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@ Telerik NativeScript Command-Line Interface
 ================
 [![Build Status](https://travis-ci.org/NativeScript/nativescript-cli.svg?branch=build)][2]
 
-*Create, build, and run native apps for iOS and Android using JavaScript*
+*Create, build, and run native apps for iOS and Android using JavaScript or TypeScript*
 
 The Telerik NativeScript CLI lets you create, build, and deploy NativeScript-based projects on iOS and Android devices.
 
@@ -11,7 +11,16 @@ The Telerik NativeScript CLI lets you create, build, and deploy NativeScript-bas
 * [System Requirements](#system-requirements "The hardware and software requirements for setting up and working with the Telerik NativeScript CLI")
 * [Installation](#installation "How to configure and install the Telerik NativeScript CLI")
 * [Quick Start](#quick-start "Get started with the Telerik NativeScript CLI")
-* [How to Contribute](#how-to-contribute "")
+	* [The Commands](#the-commands)
+	* [Create Project](#create-project)
+	* [Add Platforms](#add-platforms)
+	* [Develop Your Project](#develop-your-project)
+	* [Prepare for Build](#prepare-for-build)
+	* [Build Your Project](#build-your-project)
+	* [Deploy Your Project](#deploy-your-project)
+	* [Emulate Your Project](#emulate-your-project)
+* [Known Issues](#troubleshooting)
+* [How to Contribute](#how-to-contribute)
 * [License](#license)
 
 What is NativeScript
@@ -39,8 +48,8 @@ Supported Platforms
 
 With the Telerik NativeScript CLI, you can target the following mobile platforms.
 
-* Android 4.2 or later
-* iOS 7.0 or later
+* Android 4.2 or a later stable official release
+* iOS 7.0 or later stable official release
 
 [Back to Top][1]
 
@@ -63,6 +72,19 @@ You can install and run the Telerik NativeScript CLI on Windows or OS X.
 * Apache Ant 1.8 or later
 * Android SDK 19 or later
 
+If you want to develop for Android, verify that you have added the following paths in the `PATH` system environment variable.
+
+```
+Path to the bin directory in the Apache Ant installation folder
+Path to tools directory in the Android SDK installation folder
+Path to platform-tools directory in the Android SDK installation folder
+```
+
+For example:
+```
+PATH=...;...;C:\tools\apache-ant-1.9.4\bin;%localappdata%\Android\android-sdk\tools;%localappdata%\Android\android-sdk\platform-tools;
+``` 
+
 If you have installed Chocolatey, you can complete these steps to set up JDK, Apache Ant, and Android SDK.
 
 1. Run a Windows command prompt.
@@ -130,6 +152,7 @@ If you want to develop for Android, verify that you have added the following pat
 ```
 Path to the bin subdirectory in the Apache Ant installation directory
 Path to the tools subdirectory in the Android SDK installation directory
+Path to the platform-tools subdirectory in the Android SDK installation directory
 ```
 
 For example:
@@ -168,19 +191,19 @@ Quick Start
 
 ## The Commands
 
-Run `tns help` to list all available commands. Run or `tns <Command> help` to view more information about a selected command.
+Run `tns help` to list all available commands. Run or `tns <Command> --help` to view more information about a selected command.
 
 * `help` lists all available commands.
 * `create <App name> [--path <Directory>] [--appid <App ID>] [--copy-from <Directory>]` creates a new project with the specified settings.
 * `platform list` lists the current target platforms for your project.
 * `platform add <Platform>` adds a new target platform to your project.
 * `platform remove <Platform>` removes the selected platform from the target platforms of the project.
-* `prepare <Platform>` copies cross-platform and platform-specific content to the subdirectory for the selected target platform.
+* `prepare <Platform>` copies cross-platform and selected platform-specific content to the subdirectory for the target platform.
 * `build <Platform>` builds the project for the selected target platform.
 * `emulate <Platform>` builds the project for the selected target platform and runs it in the native emulator, if configured. 
 * `deploy <Platform> [--device <Device ID>]` deploys an already built application on connected device.
 * `run <Platform>` executes `prepare`, `build`, and `deploy`.
-* `list-devices` lists connected devices.
+* `list-devices` lists connected devices, including any running Android Virtual Devices.
 * `feature-usage-tracking` configures anonymous feature usage tracking.
 
 [Back to Top][1]
@@ -227,11 +250,16 @@ MyApp/
 `-- .tnsproject
 ```
 
+* The `app` directory is the development space for your application. You should modify all common and platform-specific code within this directory. When you run `prepare <Platform>`, the Telerik NativeScript CLI copies relevant content to the platform-specific folders for each target platform. 
+* The `hooks` directory is an empty directory. In a future release of the Telerik NativeScript CLI, in `hooks`, you will be able to store scripts that are automatically executed before and after a specified command.
+* The `platforms` directory is created empty. When you add a target platform to your project, the Telerik NativeScript CLI creates a new subdirectory with the platform name. The subdirectory contains the ready-to-build resources of your app. When you run `prepare <Platform>`, the Telerik NativeScript CLI copies relevant content from the `app` directory to the platform-specific subdirectory for each target platform.<br/>In the `platforms` directory, you can safely modify configuration files such as `AndroidManifest.xml` and `Info.plist`. 
+* The `tns_modules` is an empty directory. In a future release of the Telerik NativeScript CLI, in `tns_modules`, you will be able to add custom Telerik NativeScript modules to extend the functionality of the basic framework.
+
 [Back to Top][1]
 
 ## Add Platforms
 
-After you have created your project, you can start adding target platforms to it. To be able to build your project into an application package for a selected target platform, you need to add the platform to your project. Currently, you can target Android and iOS with your NativeScript projects.
+After you have created your project, you can start adding target platforms to it. To be able to build your project into an application package for a selected target platform, you need to add the platform to your project first. Currently, you can target Android and iOS with your NativeScript projects.
 
 Navigate to the directory that contains your newly created project and run the following commands.
 
@@ -240,7 +268,7 @@ tns platform add android
 tns platform add ios
 ```
 
-`platform add` creates the `android` and the `ios` subdirectories in the `platforms` directory. These subdirectories have the platform-specific project structure required for native development with the platform. 
+`platform add` creates the `android` and the `ios` subdirectories in the `platforms` directory. These subdirectories have the platform-specific project structure required for native development with the native SDKs for the platform. 
 
 ```
 ...
@@ -266,13 +294,47 @@ platforms/
 ...
 ```
 
+For more information about the structure of Android native projects, see [Android Projects](http://developer.android.com/tools/projects/index.html#ApplicationProjects).
+For more information about the structure iOS native projects, see [Code Organization in Xcode Projects](http://akosma.com/2009/07/28/code-organization-in-xcode-projects/).
+
 [Back to Top][1]
 
 ## Develop Your Project
 
-Develop your project in the `app` directory in the root of the project. Avoid making changes to the platform-specific subdirectories in `platforms`. The Telerik NativeScript CLI overrides such changes during the `prepare` operation.
+* [Development with NativeScript](#development-with-nativescript)
+* [Development in app](#development-in-app)
+* [Development in platforms](#development-in-platforms)
+* [Development in hooks](#development-in-hooks)
+* [Development in tns_modules](#development-in-tns-modules)
+
+### Development with NativeScript
+
+For more information about working with Telerik NativeScript, see the following resources.
+
+* [The Telerik NativeScript Documentation Wiki][6]
+* [The Telerik NativeScript API Reference][7]
+
+### Development in `app`
 
-You can use platform-specific files to provide customized functionality and design for each target platform. To indicate that a file is platform-specific, make sure that the file name is in the following format: `name.ios.extension` or `name.android.extension`. For example: `main.ios.js` or `main.android.js`. You can develop shared functionality or design in common files. To indicate that a file is common, make sure that the file name does not contain a `.android.` or `.ios.` string.
+The `app` directory in the root of the project is the development space for your project. Place all your common and platform-specific code in this directory. When you run `prepare <Platform>`, the Telerik NativeScript CLI copies relevant content to the platform-specific folders for each target platform. 
+
+In the `app` directory, you can use **platform-specific files** to provide customized functionality and design for each target platform. To indicate that a file is platform-specific, make sure that the file name is in the following format: `name.ios.extension` or `name.android.extension`. For example: `main.ios.js` or `main.android.js`. 
+
+You can develop shared functionality or design in common files. To indicate that a file is common, make sure that the file name does not contain a `.android.` or `.ios.` string.
+
+### Development in `platforms`
+
+In `platforms`, you can safely modify files which are part of the native project structure and do not have a corresponding source located in the `app` directory in the root. For example, `AndroidManifest.xml` and `Info.plist`.
+
+Do not modify files and resources that have a corresponding file in the `app` directory in the root, such as application scripts, icons, and splash screens. The Telerik NativeScript CLI overrides such files during the `prepare <Platform>` operation with the content from `app`.
+
+### Development in `hooks`
+
+In this version of the Telerik NativeScript CLI, you cannot create and use hooks.
+
+### Development in `tns_modules`
+
+In this version of the Telerik NativeScript CLI, you cannot create and use custom Telerik NativeScript modules to extend the functionality of the framework.
 
 [Back to Top][1]
 
@@ -285,11 +347,11 @@ tns prepare android
 tns prepare ios
 ```
 
-`prepare <Platform>` takes content from `app`, analyzes it and copies it to the platform-specific subdirectory in `platforms`. This operation copies common content and platform-specific content that applies only to the selected platform. This ensures that your Android or iOS application will contain the correct assets.
+`prepare <Platform>` takes content from `app`, analyzes it and copies it to the platform-specific subdirectory in `platforms`. This operation copies common and relevant platform-specific content that applies to the selected platform. This ensures that your Android or iOS application contain only the correct assets.
 
-Keep in mind that `prepare` overrides any changes made to the platform-specific subdirectory in `platforms`. To develop platform-specific functionality and design for your native apps, use platform-specific files in the `app` directory.
+Keep in mind that `prepare` overrides changes made to the platform-specific subdirectory in `platforms`. For more information, see [Development in platforms](#development-in-platforms).
 
-> **IMPORTANT:** Always run `prepare <Platform>` before running `build <Platform>` or `deploy <Platform>`. This ensures that the Telerik NativeScript CLI will build an application package that contains your latest code and resources.
+> **IMPORTANT:** Always run `prepare <Platform>` before running `build <Platform>` or `deploy <Platform>`. This ensures that the Telerik NativeScript CLI will build an application package with your latest code and resources.
 
 [Back to Top][1]
 
@@ -322,7 +384,7 @@ To verify that the Telerik NativeScript CLI recognizes your connected devices, r
 tns list-devices
 ```
 
-The Telerik NativeScript CLI lists all connected physical devices and running virtual Android devices managed by the Android Virtual Device manager.
+The Telerik NativeScript CLI lists all connected physical devices and running Android Virtual Devices.
 
 After you have listed the available devices, you can deploy your app on all devices from the selected target platform.
 
@@ -332,7 +394,7 @@ tns deploy android
 tns deploy ios
 ```
 
-The Telerik NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally. After the build is complete, the Telerik NativeScript CLI downloads and installs the application package on your connected devices. The app does not run automatically on the device.
+The Telerik NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally. After the build is complete, the Telerik NativeScript CLI downloads and installs the application package on your connected devices. The app does not run automatically on the device. To run the app, tap the app icon.
 
 > **IMPORTANT:** To deploy your app on iOS devices, you need to configure a valid pair of certificate and provisioning profile for code signing your application package. For more information, see [iOS Code Signing - A Complete Walkthrough](http://seventhsoulmountain.blogspot.com/2013/09/ios-code-sign-in-complete-walkthrough.html).
 
@@ -349,12 +411,32 @@ tns emulate ios
 
 This operation launches the native device emulator for the selected target platform and runs your project in the virtual device.
 
-For Android, the Telerik NativeScript CLI runs your app in the earliest created virtual device. Before running your app in the Android native emulator, make sure that you have configured at least one virtual device in the Android Virtual Device manager.
+For Android, the Telerik NativeScript CLI runs your app in the earliest created virtual device or the currently running Android Virtual Device. Before running your app in the Android native emulator, make sure that you have configured at least one virtual device in the Android Virtual Device manager.
 
 For iOS, the Telerik NativeScript CLI runs your app in the iOS Simulator.
 
 [Back to Top][1]
 
+Known Issues
+===
+
+* On OS X systems with Xcode 6, you cannot run your app in the native iOS emulator.
+* You can run your app only in the earliest created Android Virtual Device or the currently running Android Virtual Device.<br/>**Workaround:** Run your app on a selected virtual device from the `deploy` command.
+	1. Run the following command, to start the Android Virtual Device manager.
+
+		```Shell
+		android avd
+		```
+	1. Select the virtual device on which you want to run your app and click **Start**.
+	1. Click **Launch** and wait for the device to load.
+	1. In a new command prompt, run the following command.
+	
+		```Shell
+		tns run android --device <Device ID>
+		```
+
+		Where `<Device ID>` is the index or name of the device as listed by `tns list-devices`.
+
 How to Contribute
 ===
 
