party_foul 0.4.0 → 0.5.0

data/README.md

@@ -87,6 +87,9 @@ PartyFoul.configure do |config|
 
   # The repository for this application
   config.repo                  = 'repo_name'
+
+  # The branch for your deployed code
+  # config.branch              = 'master'
 end
 ```
 
@@ -147,9 +150,8 @@ the change in one of the [different issue renderer adapters](https://github.com/
 
 ## Authors ##
 
-[Brian Cardarella](http://twitter.com/bcardarella)
-
-[Dan McClain](http://twitter.com/_danmcclain)
+* [Brian Cardarella](http://twitter.com/bcardarella)
+* [Dan McClain](http://twitter.com/_danmcclain)
 
 [We are very thankful for the many contributors](https://github.com/dockyard/party_foul/graphs/contributors)
 

data/lib/generators/party_foul/templates/party_foul.rb

@@ -22,4 +22,7 @@ PartyFoul.configure do |config|
 
   # The repository for this application
   config.repo                  = '<%= @repo %>'
+
+  # The branch for your deployed code
+  # config.branch              = 'master'
 end

data/lib/party_foul/exception_handler.rb

@@ -1,10 +1,19 @@
 class PartyFoul::ExceptionHandler
   attr_accessor :rendered_issue
 
+  # This handler will pass the exception and env from Rack off to a processor.
+  # The default PartyFoul processor will work synchronously. Processor adapters can be written
+  # to push this logic to a background job if desired.
+  #
+  # @param [Exception, Hash]
   def self.handle(exception, env)
     PartyFoul.processor.handle(exception, env)
   end
 
+  # Makes an attempt to determine what framework is being used and will use the proper
+  # IssueRenderer.
+  #
+  # @param [Exception, Hash]
   def initialize(exception, env)
     renderer_klass = if defined?(Rails)
                        PartyFoul::RailsIssueRenderer
@@ -15,6 +24,8 @@ class PartyFoul::ExceptionHandler
     self.rendered_issue = renderer_klass.new(exception, env)
   end
 
+  # Begins to process the exception for Github Issues. Makes an attempt
+  # to find the issue. If found will update the issue. If not found will create a new issue.
   def run
     if issue = find_issue
       update_issue(issue)
@@ -23,6 +34,7 @@ class PartyFoul::ExceptionHandler
     end
   end
 
+  # Hits the Github API to find the matching issue using the fingerprint.
   def find_issue
     unless issue = PartyFoul.github.search.issues(owner: PartyFoul.owner, repo: PartyFoul.repo, state: 'open', keyword: fingerprint).issues.first
       issue = PartyFoul.github.search.issues(owner: PartyFoul.owner, repo: PartyFoul.repo, state: 'closed', keyword: fingerprint).issues.first
@@ -31,11 +43,16 @@ class PartyFoul::ExceptionHandler
     issue
   end
 
+  # Will create a new issue and a comment with the proper details. All issues are labeled as 'bug'.
   def create_issue
+    self.sha = PartyFoul.github.git_data.references.get(PartyFoul.owner, PartyFoul.repo, "heads/#{PartyFoul.branch}").object.sha
     issue = PartyFoul.github.issues.create(PartyFoul.owner, PartyFoul.repo, title: rendered_issue.title, body: rendered_issue.body, labels: ['bug'])
     PartyFoul.github.issues.comments.create(PartyFoul.owner, PartyFoul.repo, issue['number'], body: rendered_issue.comment)
   end
 
+  # Updates the given issue. If the issue is labeled as 'wontfix' nothing is done. If the issue is closed the issue is reopened and labeled as 'regression'.
+  #
+  # @param [Hashie::Mash]
   def update_issue(issue)
     unless issue.key?('labels') && issue['labels'].include?('wontfix')
       params = {body: rendered_issue.update_body(issue['body']), state: 'open'}
@@ -44,6 +61,7 @@ class PartyFoul::ExceptionHandler
         params[:labels] = ['bug', 'regression']
       end
 
+      self.sha = PartyFoul.github.git_data.references.get(PartyFoul.owner, PartyFoul.repo, "heads/#{PartyFoul.branch}").object.sha
       PartyFoul.github.issues.edit(PartyFoul.owner, PartyFoul.repo, issue['number'], params)
       PartyFoul.github.issues.comments.create(PartyFoul.owner, PartyFoul.repo, issue['number'], body: rendered_issue.comment)
     end
@@ -54,4 +72,8 @@ class PartyFoul::ExceptionHandler
   def fingerprint
     rendered_issue.fingerprint
   end
+
+  def sha=(sha)
+    rendered_issue.sha = sha
+  end
 end

data/lib/party_foul/issue_renderer.rb

@@ -1,37 +1,68 @@
 class PartyFoul::IssueRenderer
-  attr_accessor :exception, :env
+  attr_accessor :exception, :env, :sha
 
+  # A new renderer instance for Githug issues
+  #
+  # @param [Exception, Hash]
   def initialize(exception, env)
     self.exception = exception
     self.env       = env
   end
 
+  # Derived title of the issue. Must be implemented by the adapter class
+  #
+  # @return [NotImplementedError]
   def title
     raise NotImplementedError
   end
 
+  # Will compile the template for an issue body as defined in
+  # {PartyFoul.issue_template}
+  #
+  # @return [String]
   def body
     compile_template(PartyFoul.issue_template)
   end
 
+  # Will compile the template for a comment body as defined in
+  # {PartyFoul.comment_template}
   def comment
     compile_template(PartyFoul.comment_template)
   end
 
+  # Compiles the stack trace for use in the issue body. Lines in the
+  # stack trace that are part of the application will be rendered as
+  # links to the relative file and line on Github based upon
+  # {PartyFoul.web_url}, {PartyFoul.owner}, {PartyFoul.repo}, and
+  # {PartyFoul.branch}. The branch will be used at the time the
+  # exception happens to grab the SHA for that branch at that time for
+  # the purpose of linking.
+  #
+  # @return [String]
   def stack_trace
     exception.backtrace.map do |line|
       if matches = extract_file_name_and_line_number(line)
-        "<a href='#{PartyFoul.repo_url}/tree/master/#{matches[2]}#L#{matches[3]}'>#{line}</a>"
+        "<a href='#{PartyFoul.repo_url}/blob/#{sha}/#{matches[2]}#L#{matches[3]}'>#{line}</a>"
       else
         line
       end
     end.join("\n")
   end
 
+  # A SHA1 hex digested representation of the title. The fingerprint is
+  # used to create a unique value in the issue body. This value is used
+  # for seraching when matching issues happen again in the future.
+  #
+  # @return [String]
   def fingerprint
     Digest::SHA1.hexdigest(title)
   end
 
+  # Will update the issue body. The count and the time stamp will both
+  # be updated. If the format of the issue body fails to match for
+  # whatever reason the issue body will be reset.
+  #
+  # @return [String]
   def update_body(old_body)
     begin
       current_count = old_body.match(/<th>Count<\/th><td>(\d+)<\/td>/)[1].to_i
@@ -43,22 +74,39 @@ class PartyFoul::IssueRenderer
     end
   end
 
+  # The params hash at the time the exception occurred. This method is
+  # overriden for each framework adapter. It should return a hash.
+  #
+  # @return [NotImplementedError]
   def params
     raise NotImplementedError
   end
 
+  # The timestamp when the exception occurred.
+  #
+  # @return [String]
   def occurred_at
     Time.now.strftime('%B %d, %Y %H:%M:%S %z')
   end
 
+  # IP address of the client who triggered the exception
+  #
+  # @return [String]
   def ip_address
     env['REMOTE_ADDR']
   end
 
+  # The session hash for the client at the time of the exception
+  #
+  # @return [Hash]
   def session
     env['rack.session']
   end
 
+  # HTTP Headers hash from the request. Headers can be filtered out by
+  # adding matching key names to {PartyFoul.filtered_http_headers}
+  #
+  # @return [Hash]
   def http_headers
     env.keys.select { |key| key =~ /^HTTP_(\w+)/ && !(PartyFoul.filtered_http_headers || []).include?($1.split('_').map(&:capitalize).join('-')) }.sort.inject({}) do |hash, key|
       hash[key.split('HTTP_').last.split('_').map(&:capitalize).join('-')] = env[key]

data/lib/party_foul/issue_renderers/rack.rb

@@ -2,10 +2,16 @@ require 'party_foul/issue_renderer'
 
 module PartyFoul
   class RackIssueRenderer < IssueRenderer
+    # Rack params
+    #
+    # @return [Hash]
     def params
       env['QUERY_STRING']
     end
 
+    # Title for the issue comprised of (exception) "message"
+    #
+    # @return [String]
     def title
       %{(#{exception.class}) "#{exception.message}"}
     end

data/lib/party_foul/issue_renderers/rails.rb

@@ -2,11 +2,17 @@ require 'party_foul/issue_renderer'
 
 module PartyFoul
   class RailsIssueRenderer < IssueRenderer
+    # Rails params hash. Filtered parms are respected.
+    #
+    # @return [Hash]
     def params
       parameter_filter = ActionDispatch::Http::ParameterFilter.new(env["action_dispatch.parameter_filter"])
       parameter_filter.filter(env['action_dispatch.request.path_parameters'])
     end
 
+    # Title for the issue comprised of Controller#action (exception) "message"
+    #
+    # @return [String]
     def title
       %{#{env['action_controller.instance'].class}##{env['action_dispatch.request.path_parameters']['action']} (#{exception.class}) "#{exception.message}"}
     end

data/lib/party_foul/processors/sync.rb

@@ -1,4 +1,8 @@
 class PartyFoul::Processors::Sync
+  # Passes the exception and rack env data to the ExceptionHandler and
+  # runs everything synchronously.
+  #
+  # @param [Exception, Hash]
   def self.handle(exception, env)
     PartyFoul::ExceptionHandler.new(exception, env).run
   end

data/lib/party_foul/version.rb

@@ -1,3 +1,3 @@
 module PartyFoul
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/party_foul.rb

@@ -4,13 +4,27 @@ module PartyFoul
   class << self
     attr_accessor :github, :oauth_token, :endpoint, :owner, :repo,
       :ignored_exceptions, :processor, :issue_template,
-      :comment_template, :filtered_http_headers, :web_url
+      :comment_template, :filtered_http_headers, :web_url, :branch
   end
 
+  # The git branch that is used for linking in the stack trace
+  #
+  # @return [String] Defaults to 'master' if not set
+  def self.branch
+    @branch ||= 'master'
+  end
+
+  # The web url for Github. This is only interesting for Enterprise
+  # users
+  #
+  # @return [String] Defaults to 'https://github.com' if not set
   def self.web_url
     @web_url ||= 'https://github.com'
   end
 
+  # The template used for rendering the body of a new issue
+  #
+  # @return [String]
   def self.issue_template
     @issue_template ||=
     <<-TEMPLATE
@@ -26,6 +40,9 @@ Fingerprint: `:fingerprint`
     TEMPLATE
   end
 
+  # The template used for rendering the body of a new comment
+  #
+  # @return [String]
   def self.comment_template
     @comment_template ||=
     <<-TEMPLATE
@@ -39,14 +56,38 @@ Fingerprint: `:fingerprint`
     TEMPLATE
   end
 
+  # The collection of exceptions that should not be captured. Members of
+  # the collection must be string representations of the exception. For
+  # example:
+  #
+  #     # This is good
+  #     ['ActiveRecord::RecordNotFound']
+  #
+  #     # This is not
+  #     [ActiveRecord::RecordNotFound]
+  #
+  # @return [Array]
   def self.ignored_exceptions
     @ignored_exceptions || []
   end
 
+  # The url of the repository. Built using the {.web_url}, {.owner}, and {.repo}
+  # values
+  #
+  # @return [String]
   def self.repo_url
     "#{web_url}/#{owner}/#{repo}"
   end
 
+  # The configure block for PartyFoul. Use to initialize settings
+  #
+  #     PartyFoul.configure do |config|
+  #       config.owner 'dockyard'
+  #       config.repo  'test_app'
+  #       config.oauth_token = ENV['oauth_token']
+  #     end
+  #
+  # @param [Block]
   def self.configure(&block)
     yield self
     self.processor ||= PartyFoul::Processors::Sync

data/test/party_foul/configure_test.rb

@@ -14,6 +14,7 @@ describe 'Party Foul Confg' do
       config.endpoint           = 'http://api.example.com'
       config.owner              = 'test_owner'
       config.repo               = 'test_repo'
+      config.branch             = 'master'
     end
 
     PartyFoul.ignored_exceptions.must_equal ['StandardError']
@@ -23,5 +24,11 @@ describe 'Party Foul Confg' do
     PartyFoul.owner.must_equal 'test_owner'
     PartyFoul.repo.must_equal 'test_repo'
     PartyFoul.repo_url.must_equal 'http://example.com/test_owner/test_repo'
+    PartyFoul.branch.must_equal 'master'
+  end
+
+  it 'has default values' do
+    PartyFoul.web_url.must_equal 'https://github.com'
+    PartyFoul.branch.must_equal  'master'
   end
 end

data/test/party_foul/exception_handler_test.rb

@@ -8,8 +8,10 @@ describe 'Party Foul Exception Handler' do
       config.repo        = 'test_repo'
     end
 
+    PartyFoul.stubs(:branch).returns('deploy')
     PartyFoul.github.stubs(:issues).returns(mock('Issues'))
     PartyFoul.github.stubs(:search).returns(mock('Search'))
+    PartyFoul.github.git_data.references.stubs(:get)
     PartyFoul.github.issues.stubs(:create)
     PartyFoul.github.issues.stubs(:edit)
     PartyFoul.github.issues.stubs(:comments).returns(mock('Comments'))
@@ -25,6 +27,7 @@ describe 'Party Foul Exception Handler' do
       PartyFoul.github.search.stubs(:issues).with(owner: 'test_owner', repo: 'test_repo', keyword: 'test_fingerprint', state: 'open').returns(Hashie::Mash.new(issues: []))
       PartyFoul.github.search.stubs(:issues).with(owner: 'test_owner', repo: 'test_repo', keyword: 'test_fingerprint', state: 'closed').returns(Hashie::Mash.new(issues: []))
       PartyFoul.github.issues.expects(:create).with('test_owner', 'test_repo', title: 'Test Title', body: 'Test Body', :labels => ['bug']).returns(Hashie::Mash.new('number' => 1))
+      PartyFoul.github.git_data.references.expects(:get).with('test_owner', 'test_repo', 'heads/deploy').returns(Hashie::Mash.new(object: Hashie::Mash.new(sha: 'abcdefg1234567890')))
       PartyFoul.github.issues.comments.expects(:create).with('test_owner', 'test_repo', 1, body: 'Test Comment')
       PartyFoul::ExceptionHandler.new(nil, {}).run
     end
@@ -41,6 +44,7 @@ describe 'Party Foul Exception Handler' do
         PartyFoul.github.search.stubs(:issues).with(owner: 'test_owner', repo: 'test_repo', keyword: 'test_fingerprint', state: 'open').returns(Hashie::Mash.new(issues: [{title: 'Test Title', body: 'Test Body', state: 'open', number: 1}]))
         PartyFoul.github.issues.expects(:edit).with('test_owner', 'test_repo', 1, body: 'New Body', state: 'open')
         PartyFoul.github.issues.comments.expects(:create).with('test_owner', 'test_repo', 1, body: 'Test Comment')
+        PartyFoul.github.git_data.references.expects(:get).with('test_owner', 'test_repo', 'heads/deploy').returns(Hashie::Mash.new(object: Hashie::Mash.new(sha: 'abcdefg1234567890')))
         PartyFoul::ExceptionHandler.new(nil, {}).run
       end
     end
@@ -51,6 +55,7 @@ describe 'Party Foul Exception Handler' do
         PartyFoul.github.search.stubs(:issues).with(owner: 'test_owner', repo: 'test_repo', keyword: 'test_fingerprint', state: 'closed').returns(Hashie::Mash.new(issues: [{title: 'Test Title', body: 'Test Body', state: 'closed', number: 1}]))
         PartyFoul.github.issues.expects(:edit).with('test_owner', 'test_repo', 1, body: 'New Body', state: 'open', labels: ['bug', 'regression'])
         PartyFoul.github.issues.comments.expects(:create).with('test_owner', 'test_repo', 1, body: 'Test Comment')
+        PartyFoul.github.git_data.references.expects(:get).with('test_owner', 'test_repo', 'heads/deploy').returns(Hashie::Mash.new(object: Hashie::Mash.new(sha: 'abcdefg1234567890')))
         PartyFoul::ExceptionHandler.new(nil, {}).run
       end
     end
@@ -64,6 +69,7 @@ describe 'Party Foul Exception Handler' do
       PartyFoul.github.issues.expects(:create).never
       PartyFoul.github.issues.expects(:edit).never
       PartyFoul.github.issues.comments.expects(:create).never
+      PartyFoul.github.git_data.references.expects(:get).never
       PartyFoul::ExceptionHandler.new(nil, {}).run
     end
   end

data/test/test_helper.rb

@@ -21,7 +21,7 @@ module MiniTest::Expectations
 end
 
 def clean_up_party
-  %w{github oauth_token endpoint owner repo ignored_exceptions processor issue_template comment_template filtered_http_headers web_url}.each do |attr|
+  %w{github oauth_token endpoint owner repo ignored_exceptions processor issue_template comment_template filtered_http_headers web_url branch}.each do |attr|
     PartyFoul.send("#{attr}=", nil)
   end
 end

data/test/tmp/config/initializers/party_foul.rb

@@ -22,4 +22,7 @@ PartyFoul.configure do |config|
 
   # The repository for this application
   config.repo                  = 'test_repo'
+
+  # The branch for your deployed code
+  # config.branch              = 'master'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: party_foul
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-27 00:00:00.000000000 Z
+date: 2013-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: github_api
@@ -200,7 +200,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3123915090860232817
+      hash: -549281873562555121
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -209,7 +209,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3123915090860232817
+      hash: -549281873562555121
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23