Merge pull request #28 from codeclimate/pb-oss-prep

Begin OSS prep work

Author: brynary

README.md

@@ -1,5 +1,17 @@
 # Code Climate Services
 
+A collection of classes, each responsible for integrating one external service
+with the Code Climate system.
+
+## Overview
+
+Services define `#receive_<event>` methods for any events they are interested
+in. These methods will be invoked with `@payload` set to a hash of data about
+the event being handled.
+
+The structure of this data is described below. Note that there may be additional
+keys not listed here.
+
 ## Events
 
 Attributes common to all event types:
@@ -61,6 +73,10 @@ Event-specific attributes:
 }
 ```
 
+*Note*: The reason for the top-level `warning_type` attribute is for when the
+list of vulnerabilities are of mixed warning types. In this case, the top-level
+attribute can be used in any messaging.
+
 ### Pull Request
 
 Event name: `pull_request`
@@ -80,9 +96,23 @@ Event-specific attributes:
 
 The following are not fully implemented yet.
 
-* :issue
-* :unit
-* :snapshot
+* `snapshot`
+
+## Contributing
+
+To add a new integration, you'll need to create a new `Service` subclass. Please
+use existing services as an example:
+
+- Chat service examples: `hipchat`, `campfire`
+- Issue tracker examples: `github_issues`, `lighthouse`
+
+Ensure that your class implements `#receive_test`. It must handle any exceptions
+and always return a hash of `{ ok: true|false, message: "String (HTML ok)" }`.
+
+When you open your PR, please include an image for your service.
+[Example][service_avatar].
+
+[service_avatar]: https://codeclimate.com/assets/integration_icons/campfire-9f0475f77133a3ff5267972436dead60.png
 
 ## License