epic tomdoc

README.mkdn

@@ -7,7 +7,7 @@ How the services work
 1. A post-receive background job is submitted when someone pushes their
    commits to GitHub
 2. If the repository the commits belong to has any "Service Hooks" setup, the
-   job makes a request to `http://services-server/service_name/` with the
+   job makes a request to `http://services-server/service_name/push` with the
    following data:
     - `params[:payload]` containing all of the commit data (the same data you get using the API)
     - `params[:data]` containing the service data (username, password, room, etc)
@@ -22,11 +22,13 @@ Steps to contributing
 2. Create a new file in /services/ called `service_name.rb`, using the following
    template:
 
-        service :service_name do |data, payload|
+        class Service::ServiceName < Service
+          def receive_push
+          end
         end
 
-3. Vendor any external gems your code relies on, and make sure to include it in
-   the requires at the top of github-services.rb
+3. Vendor any external gems your code relies on, and make sure it is
+   specified in the Gemfile.
 4. Add documentation to `docs/service_name` (refer to the others for guidance)
 5. Send a pull request from your fork to [github/github-services](https://github.com/github/github-services)
 6. Once it's accepted we'll add any new necessary data fields to the GitHub
@@ -36,19 +38,6 @@ Steps to contributing
 
 A huge thanks goes out to [our many contributors](https://github.com/github/github-services/contributors)!
 
-Naming Convention
------------------
-
-If your service name is two words, the filenames and service key should
-be underscored, with words separated by an underscore.
-
-    # GitHub
-    # docs/git_hub
-    # services/git_hub.rb
-    service :git_hub do |data, payload|
-      ...
-    end
-
 Running the server locally
 --------------------------
 
@@ -58,17 +47,39 @@ Running the server locally
 4. ruby github-services.rb
 
 * Bugs in the code should be filed under the Issues tab
-* Problems with the service hooks can be filed [here](http://support.github.com/discussions/post-receive-issues)
+* Problems with the service hooks can be filed
+  [here](https://github.com/contact)
 
 How to test your service
 ------------------------
 
+You can test your service in a ruby irb console:
+
+1. Run `rake console` to start irb.
+2. Instantiate your server:
+
+        svc = Service::MyService.new(:push,
+          # Hash of configuration information.
+          {'token' => 'abc'},
+          # Hash of payload.
+          {'blah' => 'payload!'})
+
+        svc.receive_push
+
+3. The third argument is optional if you just want to use the sample
+   payload.
+
+        svc = Service::MyService.new(:push,
+          # Hash of configuration information.
+          {'token' => 'abc'})
+
+        svc.receive_push
+
+You can also test your hook with the Sinatra web service:
+
 1. Start the github-services Sinatra server with `ruby github-services.rb`. By
    default, it runs on port 8080.
 2. Edit the docs/github_payload file as necessary to test your service.  (Usually
    just editing the "data" values but leaving the "payload" alone.)
 3. Send the docs/github_payload file to your service by calling:
    `./script/deliver_payload [service-name]`
-
-NOTE: The name of the service and your docs/ file matters. If your service is RunCodeRun, your service
-and docs MUST be `run_code_run`. Good luck!

Rakefile

@@ -7,3 +7,6 @@ end
 
 task :default => :test
 
+task :console do
+  sh "irb -r ./config/load"
+end

lib/app.rb

@@ -1,4 +1,10 @@
+# The Sinatra App that handles incoming events.
 class Service::App < Sinatra::Base
+  # Hooks the given Service to a Sinatra route.
+  #
+  # svc - Service instance.
+  #
+  # Returns nothing.
   def self.service(svc)
     post "/#{svc.hook_name}/:event" do
       begin
@@ -29,12 +35,22 @@ def self.service(svc)
     "ok"
   end
 
+  # Parses the incoming payload and massages any properties.
+  #
+  # json - JSON String.
+  #
+  # Returns a Hash payload.
   def parse_payload(json)
     payload = JSON.parse(json)
     payload['ref_name'] = payload['ref'].to_s.sub(/\Arefs\/(heads|tags)\//, '')
     payload
   end
 
+  # Reports the given exception to Haystack.
+  #
+  # exception - An Exception instance.
+  #
+  # Returns nothing.
   def report_exception(exception)
     backtrace = Array(exception.backtrace)[0..500]
 

lib/events/push_helpers.rb

@@ -1,3 +1,4 @@
+# This is a set of common helpers for Push events.
 module Service::PushHelpers
   def created?
     payload['created'] or !!(payload['before'] =~ /0{40}/)