Merge branch 'refs/heads/github/master' into github/develop

2 files changed, 28 insertions, 14 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d28d6b7cb5..db408b7e9f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,15 +1,25 @@
-# Contributing to sdl_core
+# Contributing to SDL Projects
 
-Third party contributions are essential for making this repository great. However, we do have a few guidelines we need contributors to follow.
+Third party contributions are essential for making SDL great. However, we do have a few guidelines we need contributors to follow.
+
+### Issues
+If writing a bug report, please make sure <a href="http://yourbugreportneedsmore.info" target="_blank">it has enough info</a>. Include all relevant information.
+
+If requesting a feature, understand that we appreciate the input! However, it may not immediately fit our roadmap, and it may take a while for us to get to your request.
 
 ### Gitflow
-We use Gitflow as our branch management system. Please read up on it [here](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). The main points you should know are:
+We use <a href="http://nvie.com/posts/a-successful-git-branching-model/">Gitflow</a> as our branch management system. Please follow gitflow's guidelines while contributing to any SDL project.
 
+### Pull Requests
+* Please follow the repository's for all code and documentation.
 * All feature branches should be based on `develop` and have the format `feature/branch_name`.
-* Minor bug fixes should be based on `master` and have the format `hotfix/branch_name`.
-* All commits should involve logical units. Please do not put all changed code in one commit, unless it is a very minor change.
-* Work in progress pull requests should have "[WIP]" in front of the Pull Request title. When you are ready to merge, remove this tag and @mention `smartdevicelink/developers` to get it scheduled for review.
-* If applicable, follow [this Pull Request's format](https://github.com/smartdevicelink/SmartDeviceLink-iOS/pull/45).
+* Minor bug fixes, that is bug fixes that do not change, add, or remove any public API, should be based on `master` and have the format `hotfix/branch_name`.
+* All pull requests should implement a single feature or fix a single bug. Pull Requests that involve multiple changes (it is our discretion what precisely this means) will be rejected with a reason.
+* All commits should separated into logical units, i.e. unrelated changes should be in different commits within a pull request.
+* Work in progress pull requests should have "[WIP]" in front of the Pull Request title. When you believe the pull request is ready to merge, remove this tag and @mention the appropriate SDL team to schedule a review.
+* All new code *must* include unit tests. Bug fixes should have a test that fails previously and now passes. All new features should be covered. If your code does not have tests, or regresses old tests, it will be rejected.
+* A great example of a <a href="https://github.com/smartdevicelink/SmartDeviceLink-iOS/pull/45" "_target>pull request can be found here</a>.
 
 ### Contributor's License Agreement (CLA)
-Coming Soon! Unfortunately, we cannot accept third party contributions until this is ready. We are working quickly on the CLA as we have contributions waiting! (A good problem to have)
+In order to accept Pull Requests from contributors, you must first sign [the Contributor's License Agreement](https://docs.google.com/forms/d/1VNR8EUd5b46cQ7uNbCq1fJmnu0askNpUp5dudLKRGpU/viewform). If you need to make a change to information that you entered, [please contact us](mailto:justin@livio.io).
+
diff --git a/README.md b/README.md
index e8cf625b3e..8d8b6079c6 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,12 @@
+##### Note: Please use the [develop](https://github.com/smartdevicelink/sdl_core/tree/develop) or [release candidate](https://github.com/smartdevicelink/sdl_core/tree/release/4.0.0) branches of sdl_core for the most stable versions.
+
 # SmartDeviceLink (SDL)
 
-SmartDeviceLink is a way to connect applications on a smart phone to a vehicle so they can be controlled by a vehicle's head unit (radio interface).  There are three main pieces to SDL - [core](https://github.com/smartdevicelink/sdl_core) (head unit), [mobile libraries](https://github.com/smartdevicelink/sdl_android), and the [server](https://github.com/smartdevicelink/sdl_server).
+SmartDeviceLink (SDL) is a standard set of protocols and messages that connect applications on a smartphone to a vehicle head unit. This messaging enables a consumer to interact with their application using common in-vehicle interfaces such as a touch screen display, embedded voice recognition, steering wheel controls and various vehicle knobs and buttons. There are three main components that make up the SDL ecosystem.
+
+  * The [Core](https://github.com/smartdevicelink/sdl_core) component is the software which Vehicle Manufacturers (OEMs)  implement in their vehicle head units. Integrating this component into their head unit and HMI based on a set of guidelines and templates enables access to various smartphone applications.
+  * The optional [SDL Server](https://github.com/smartdevicelink/sdl_server) can be used by Vehicle OEMs to update application policies and gather usage information for connected applications.
+  * The [iOS](https://github.com/smartdevicelink/sdl_ios) and [Android](https://github.com/smartdevicelink/sdl_android) libraries are implemented by app developers into their applications to enable command and control via the connected head unit.
 
 Pull Requests Welcome!
 
@@ -9,16 +15,14 @@ Pull Requests Welcome!
   * [Software Architecture Document](https://app.box.com/s/v5ymu5kathzkwfx8iigxxdpr7d5a2xhh)
   * [Transport Manager Programming Guide](https://app.box.com/s/1pjquttvmhf19uujtw4x4fv4t1leqasa)
   * [Software Detailed Design](https://app.box.com/s/ohgrvemtx39f8hfea1ab676xxrzvyx1y)
-  * [Integration Guidelines](https://app.box.com/s/uikmmpeozq6j902uzl1he43n6ct010jp)
+  * [Integration Guidelines](https://app.box.com/s/jkj51mkaa5uganbhjxmtv06lbs8hapa9)
 
 ## SDL Core
 
-The Core component of SDL is meant to run on a vehicle's computing system. It connects to a consumer's smartphone over a variety of transports such as Bluetooth, USB, Android AOA, and TCP. Transport adapters can be written to extend the capabilities of Core's transport manager. Once a smartphone is connected over a preferred transport applications on the mobile phone that implement the mobile libraries can begin to communicate with the vehicle. First, the Core component queries the phone to understand which applications are compatible. The user interface shows the list of compatible applications to the driver. When the user selects an application, it is sent an HMI_STATUS level of FULL (all applications start with a BACKGROUND status). Once an application has the FULL status, it is allowed to populate a template, defined by the vehicle manufacturer, with content such as metadata, artwork, buttons and even supported grammars for voice commands (voice recognition engine not included).
-
-The communication between the Core component and the mobile phone is based on JSON RPC. The communication between the Core component and the user interface is also via JSON RPC. The current code base includes an HTML5 user interface that was released by Ford Motor Company for the My Ford Touch system. The core component can also be configured to support QT5 and DBus, and includes a QT interface as well.
+The Core component of SDL runs on a vehicle's computing system (head unit). Core’s primary responsibility is to pass messages between connected smartphone applications and the vehicle HMI, and pass notifications from the vehicle to those applications. It can connect a smartphone to a vehicle's head unit via a variety of transport protocols such as Bluetooth, USB, Android AOA, and TCP. Once a connection is established, Core discovers compatible applications and displays them to the driver for interaction via voice or display. The core component is implemented into the vehicle HMI based on the integration guidelines above. The core component is configured to follow a set of policies defined in a policy database and updated by a [policy server](https://www.github.com/smartdevicelink/sdl_server). The messaging between a connected application and core is defined by the [Mobile API](https://github.com/smartdevicelink/sdl_core/blob/master/src/components/interfaces/MOBILE_API.xml) and the messaging between sdl core and the vehicle is defined by the [HMI API](https://github.com/smartdevicelink/sdl_core/blob/master/src/components/interfaces/HMI_API.xml).
 
 ## Project Status
-We're ramping up our efforts to get SmartDeviceLink developed and maintained directly in the open. For the Mobile libraries, we're expecting better integration soon, SDL Core is slightly more complicated. We are currently working on generating documentation, creating a developer portal, an open forum, interface requirements, HMI guidelines, Mobile validation, and everything else that we've been asked for to renew the community's interest in this project. From a technical standpoint, SDL is stable, and the most work is being put into making it a more robust solution for app connectivity. We are, however, definitely looking for and interested in other people and company's contributions to SDL whether it be feature based, bug fixes, healthy conversation, or even just suggestions for improvement.
+We're ramping up our efforts to get SmartDeviceLink developed and maintained directly in the open. For the Mobile libraries, we're expecting better integration soon, SDL Core is slightly more complicated. We are currently working on generating documentation, creating a developer portal, an open forum, Mobile validation, and everything else that we've been asked for to renew the community's interest in this project. From a technical standpoint, SDL is stable, and the most work is being put into making it a more robust solution for app connectivity. We are, however, definitely looking for and interested in other people and company's contributions to SDL whether it be feature based, bug fixes, healthy conversation, or even just suggestions for improvement.
 
 # Getting Started
 A quick guide to installing, configuring, and running an instance of the SDL Core on a linux OS.