jirametrics 2.8 → 2.10

data/lib/jirametrics/file_system.rb

@@ -31,13 +31,22 @@ class FileSystem
     File.write(filename, content)
   end
 
-  def warning message
-    log "Warning: #{message}", also_write_to_stderr: true
+  def warning message, more: nil
+    log "Warning: #{message}", more: more, also_write_to_stderr: true
   end
 
-  def log message, also_write_to_stderr: false
+  def error message, more: nil
+    log "Error: #{message}", more: more, also_write_to_stderr: true
+  end
+
+  def log message, more: nil, also_write_to_stderr: false
+    message += " See #{logfile_name} for more details about this message." if more
+
     logfile.puts message
-    $stderr.puts message if also_write_to_stderr # rubocop:disable Style/StderrPuts
+    logfile.puts more if more
+    return unless also_write_to_stderr
+
+    $stderr.puts message # rubocop:disable Style/StderrPuts
   end
 
   # In some Jira instances, a sizeable portion of the JSON is made up of empty fields. I've seen
@@ -59,4 +68,14 @@ class FileSystem
   def file_exist? filename
     File.exist? filename
   end
+
+  def deprecated message:, date:, depth: 2
+    text = +''
+    text << "Deprecated(#{date}): "
+    text << message
+    caller(1..depth).each do |line|
+      text << "\n-> Called from #{line}"
+    end
+    log text, also_write_to_stderr: true
+  end
 end

data/lib/jirametrics/groupable_issue_chart.rb

@@ -6,9 +6,7 @@ require 'jirametrics/grouping_rules'
 module GroupableIssueChart
   def init_configuration_block user_provided_block, &default_block
     instance_eval(&user_provided_block)
-    return if @group_by_block
-
-    instance_eval(&default_block)
+    instance_eval(&default_block) unless @group_by_block
   end
 
   def grouping_rules &block

data/lib/jirametrics/html/aging_work_bar_chart.erb

@@ -38,22 +38,13 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
     plugins: {
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
 
           <% if percentage_line_x %>
           line: {
             type: 'line',
-            xMin: '<%= percentage_line_x %>',
-            xMax: '<%= percentage_line_x %>',
+            scaleID: 'x',
+            value: '<%= percentage_line_x %>',
             borderColor: <%= CssVariable.new('--aging-work-bar-chart-percentage-line-color').to_json %>,
             borderWidth: 1,
             drawTime: 'afterDraw'

data/lib/jirametrics/html/aging_work_table.erb

@@ -40,7 +40,7 @@
             </div>
           <% end %>
         </td>
-        <td><%= format_status issue.status.name, board: issue.board %></td>
+        <td><%= format_status issue.status, board: issue.board %></td>
         <td><%= fix_versions_text(issue) %></td>
         <% if any_scrum_boards %>
           <td><%= sprints_text(issue) %></td>

data/lib/jirametrics/html/cycletime_histogram.erb

@@ -1,6 +1,57 @@
 <div class="chart">
   <canvas id="<%= chart_id %>" width="<%= canvas_width %>" height="<%= canvas_height %>"></canvas>
 </div>
+<%
+if show_stats 
+  link_id = next_id
+  issues_id = next_id
+%>
+[<a id='<%= link_id %>' href="#" onclick='expand_collapse("<%= link_id %>", "<%= issues_id %>"); return false;'>Show details</a>]
+<div id="<%= issues_id %>" style="display: none;">
+  <div>
+     <table class="standard">
+      <tr>
+        <th>Issue Type</th>
+        <th>Min</th>
+        <th>Max</th>
+        <th>Avg</th>
+        <th>Mode</th>
+        <% percentiles.each do |p| %>
+           <th><%= p %>th</th>
+        <% end %>
+      </tr>
+      <% the_stats.each do |k, v| %>
+          <tr>
+            <td><%= k %></td>
+            <td style="text-align: right;"><%= v[:min] %></td>
+            <td style="text-align: right;"><%= v[:max] %></td>
+            <td style="text-align: right;"><%= sprintf('%.2f', v[:average]) %></td>
+            <td><%= v[:mode].join(', ') %></td>
+            <% percentiles.each do |p| %>
+               <td style="text-align: right;"><%= v[:percentiles][p] %></td>
+            <% end %>
+          </tr>
+       <% end %>
+     </table>
+  </div>
+  <div>
+    <p>These statistics help understand the <i>"shape"</i> of the cycletime histogram distribution, to help us with predictions.</p>
+    <ul>
+      <li><b>Min & Max:</b> the observed spread for the data set. Useful to judge how wide the variation is. </li>
+      <li><b>Average:</b> the arithmetic mean of the data set. Useful as a <i>"typical representative"</i> of the complete set.</li>
+      <li><b>Mode:</b> the most repeated value(s) in the data set. This is the value we're most likely to remember. </li>
+      <li><b>Percentiles:</b> they partition the data set. If X is the Nth percentile, it means that N% of cycletime values are X or less. Typical percentiles of interest are:</li>
+      <ul>
+        <li><b>50%</b>: also known as the <b>Median</b>. Useful to establish short feedback loops, to monitor that it's not drifting to the right.</li>
+        <li><b>85%</b>: useful to establish service level expectations, accounting for rare events..</li>
+        <li><b>98% (or higher)</b>: useful to gauge worst case expectations..</li>
+      </ul>
+    </ul>
+  </div>
+</div>
+<%
+end
+%>
 <script>
 new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
 {
@@ -21,6 +72,8 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
         grid: {
           color: <%= CssVariable['--grid-line-color'].to_json %>
         },
+        min: 0,
+        offset: false, // Gets rid of the ugly padding on left.
       },
       y: {
         stacked: true,
@@ -34,6 +87,27 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
       }
     },
     plugins: {
+      annotation: {
+        annotations: {
+          <%
+            results = the_stats[:all][:percentiles]
+            results.each do |percentile, value|
+          %>
+          percentile<%= percentile.to_s %>: {
+            type: 'line',
+            scaleID: 'x',
+            value: <%= value %>,
+            borderWidth: 1,
+            drawTime: 'beforeDatasetsDraw',
+            label: {
+              enabled: true,
+              content: '<%= "#{percentile}%" %>',
+              position: 'start',
+            }
+          },
+          <% end %>
+        },
+      },
       tooltip: {
         callbacks: {
           label: function(context) {

data/lib/jirametrics/html/cycletime_scatterplot.erb

@@ -53,16 +53,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       autocolors: false,
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
 
           <% @percentage_lines.each_with_index do |args, index| %>
           <%   percent, color = args %>

data/lib/jirametrics/html/daily_wip_chart.erb

@@ -50,16 +50,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
       },
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       },
       legend: {

data/lib/jirametrics/html/expedited_chart.erb

@@ -55,16 +55,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       autocolors: false,
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       }
     }

data/lib/jirametrics/html/hierarchy_table.erb

@@ -22,7 +22,7 @@
           </span>
         </td>
         <td><span style="color: <%= color %>; font-style: italic;"><%= issue.summary[0..80] %></span></td>
-        <td><%= format_status issue.status.name, board: issue.board %></td>
+        <td><%= format_status issue.status, board: issue.board %></td>
       </tr>
     <% end %>
   </tbody>

data/lib/jirametrics/html/sprint_burndown.erb

@@ -56,16 +56,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       },
       annotation: {
         annotations: {
-          <% holidays().each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       }
     }

data/lib/jirametrics/html/throughput_chart.erb

@@ -52,16 +52,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       },
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       }
     }

data/lib/jirametrics/html_report_config.rb

@@ -5,16 +5,15 @@ require 'jirametrics/self_or_issue_dispatcher'
 
 class HtmlReportConfig
   include SelfOrIssueDispatcher
-  include DiscardChangesBefore
 
-  attr_reader :file_config, :sections
+  attr_reader :file_config, :sections, :charts
 
   def self.define_chart name:, classname:, deprecated_warning: nil, deprecated_date: nil
     lines = []
     lines << "def #{name} &block"
     lines << '  block = ->(_) {} unless block'
     if deprecated_warning
-      lines << "  deprecated date: #{deprecated_date.inspect}, message: #{deprecated_warning.inspect}"
+      lines << "  file_system.deprecated date: #{deprecated_date.inspect}, message: #{deprecated_warning.inspect}"
     end
     lines << "  execute_chart #{classname}.new(block)"
     lines << 'end'
@@ -43,14 +42,15 @@ class HtmlReportConfig
   def initialize file_config:, block:
     @file_config = file_config
     @block = block
-    @sections = []
+    @sections = [] # Where we store the chunks of text that will be assembled into the HTML
+    @charts = [] # Where we store all the charts we executed so we can assert against them.
   end
 
   def cycletime label = nil, &block
     @file_config.project_config.all_boards.each_value do |board|
       raise 'Multiple cycletimes not supported' if board.cycletime
 
-      board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block)
+      board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block, file_system: file_system)
     end
   end
 
@@ -64,7 +64,7 @@ class HtmlReportConfig
 
     # The quality report has to be generated last because otherwise cycletime won't have been
     # set. Then we have to rotate it to the first position so it's at the top of the report.
-    execute_chart DataQualityReport.new(@original_issue_times || {})
+    execute_chart DataQualityReport.new(file_config.project_config.discarded_changes_data)
     @sections.rotate!(-1)
 
     html create_footer
@@ -101,9 +101,8 @@ class HtmlReportConfig
     base_css
   end
 
-  def board_id id = nil
-    @board_id = id unless id.nil?
-    @board_id
+  def board_id id
+    @board_id = id
   end
 
   def timezone_offset
@@ -143,19 +142,6 @@ class HtmlReportConfig
     end
   end
 
-  def discard_changes_before_hook issues_cutoff_times
-    # raise 'Cycletime must be defined before using discard_changes_before' unless @cycletime
-
-    @original_issue_times = {}
-    issues_cutoff_times.each do |issue, cutoff_time|
-      started = issue.board.cycletime.started_stopped_times(issue).first
-      if started && started <= cutoff_time
-        # We only need to log this if data was discarded
-        @original_issue_times[issue] = { cutoff_time: cutoff_time, started_time: started }
-      end
-    end
-  end
-
   def dependency_chart &block
     execute_chart DependencyChart.new block
   end
@@ -175,7 +161,7 @@ class HtmlReportConfig
     chart.settings = settings
 
     chart.all_boards = project_config.all_boards
-    chart.board_id = find_board_id if chart.respond_to? :board_id=
+    chart.board_id = find_board_id
     chart.holiday_dates = project_config.exporter.holiday_dates
 
     time_range = @file_config.project_config.time_range
@@ -184,6 +170,7 @@ class HtmlReportConfig
 
     after_init_block&.call chart
 
+    @charts << chart
     html chart.run
   end
 
@@ -216,4 +203,12 @@ class HtmlReportConfig
       </section>
     HTML
   end
+
+  def discard_changes_before status_becomes: nil, &block
+    file_system.deprecated(
+      date: '2025-01-09',
+      message: 'discard_changes_before is now only supported at the project level'
+    )
+    file_config.project_config.discard_changes_before status_becomes: status_becomes, &block
+  end
 end

data/lib/jirametrics/issue.rb

@@ -13,7 +13,12 @@ class Issue
     @changes = []
     @board = board
 
+    # We only check for this here because if a board isn't passed in then things will fail much
+    # later and be hard to find. Let's find out early.
     raise "No board for issue #{key}" if board.nil?
+
+    # There are cases where we create an Issue of fragments like linked issues and those won't have
+    # changelogs.
     return unless @raw['changelog']
 
     load_history_into_changes
@@ -93,9 +98,7 @@ class Issue
 
   def still_in
     result = nil
-    @changes.each do |change|
-      next unless change.status?
-
+    status_changes.each do |change|
       current_status_matched = yield change
 
       if current_status_matched && result.nil?
@@ -117,63 +120,71 @@ class Issue
 
   # If it ever entered one of these categories and it's still there then what was the last time it entered
   def still_in_status_category *category_names
+    category_ids = find_status_category_ids_by_names category_names
+
     still_in do |change|
-      status = find_status_by_id change.value_id, name: change.value
-      category_names.include?(status.category.name) || category_names.include?(status.category.id)
+      status = find_or_create_status id: change.value_id, name: change.value
+      category_ids.include? status.category.id
     end
   end
 
   def most_recent_status_change
+    # We artificially insert a status change to represent creation so by definition there will always be at least one.
     changes.reverse.find { |change| change.status? }
   end
 
   # Are we currently in this status? If yes, then return the most recent status change.
   def currently_in_status *status_names
     change = most_recent_status_change
-    return false if change.nil?
 
     change if change.current_status_matches(*status_names)
   end
 
   # Are we currently in this status category? If yes, then return the most recent status change.
   def currently_in_status_category *category_names
+    category_ids = find_status_category_ids_by_names category_names
+
     change = most_recent_status_change
-    return false if change.nil?
 
-    status = find_status_by_id change.value_id, name: change.value
-    change if status && category_names.include?(status.category.name)
+    status = find_or_create_status id: change.value_id, name: change.value
+    change if status && category_ids.include?(status.category.id)
   end
 
-  def find_status_by_id id, name: nil
+  def find_or_create_status id:, name:
     status = board.possible_statuses.find_by_id(id)
-    return status if status
 
-    status = board.possible_statuses.fabricate_status_for id: id, name: name
+    unless status
+      # Have to pull this list before the call to fabricate or else the warning will incorrectly
+      # list this status as one it actually found
+      found_statuses = board.possible_statuses.to_s
+
+      status = board.possible_statuses.fabricate_status_for id: id, name: name
 
-    message = +'The history for issue '
-    message << key
-    message << ' references a status ('
-    message << name.inspect << ':' if name
-    message << id.to_s
-    message << ') that can\'t be found in ['
-    message << board.possible_statuses.collect(&:to_s).join(', ')
-    message << "]. We are guessing that this belongs to the #{status.category} status category "
-    message << 'and that may be wrong. See https://jirametrics.org/faq/#q1 for more details'
-    board.project_config.file_system.warning message
+      message = +'The history for issue '
+      message << key
+      message << ' references the status ('
+      message << "#{name.inspect}:#{id.inspect}"
+      message << ') that can\'t be found. We are guessing that this belongs to the '
+      message << status.category.to_s
+      message << ' status category but that may be wrong. See https://jirametrics.org/faq/#q1 for more '
+      message << 'details on defining statuses.'
+      board.project_config.file_system.warning message, more: "The statuses we did find are: #{found_statuses}"
+    end
 
     status
   end
 
   def first_status_change_after_created
-    @changes.find { |change| change.status? && change.artificial? == false }
+    status_changes.find { |change| change.artificial? == false }
   end
 
   def first_time_in_status_category *category_names
-    @changes.each do |change|
-      next unless change.status?
+    category_ids = find_status_category_ids_by_names category_names
 
-      category = find_status_by_id(change.value_id).category.name
-      return change if category_names.include? category
+    status_changes.each do |change|
+      to_status = find_or_create_status(id: change.value_id, name: change.value)
+      id = to_status.category.id
+      return change if category_ids.include? id
     end
     nil
   end
@@ -645,6 +656,10 @@ class Issue
     end
   end
 
+  def status_changes
+    @changes.select { |change| change.status? }
+  end
+
   private
 
   def assemble_author raw
@@ -720,4 +735,13 @@ class Issue
       'toString' => first_status
     }
   end
+
+  def find_status_category_ids_by_names category_names
+    category_names.filter_map do |name|
+      list = board.possible_statuses.find_all_categories_by_name name
+      raise "No status categories found for name: #{name}" if list.empty?
+
+      list
+    end.flatten.collect(&:id)
+  end
 end

data/lib/jirametrics/jira_gateway.rb

@@ -14,9 +14,15 @@ class JiraGateway
   def call_url relative_url:
     command = make_curl_command url: "#{@jira_url}#{relative_url}"
     result = call_command command
-    JSON.parse result
-  rescue => e # rubocop:disable Style/RescueStandardError
-    raise "Error #{e.message.inspect} when parsing result: #{result.inspect}"
+    begin
+      json = JSON.parse(result)
+    rescue # rubocop:disable Style/RescueStandardError
+      raise "Error when parsing result: #{result.inspect}"
+    end
+
+    raise "Download failed with: #{JSON.pretty_generate(json)}" unless json_successful?(json)
+
+    json
   end
 
   def call_command command
@@ -61,4 +67,11 @@ class JiraGateway
     command << " --url \"#{url}\""
     command
   end
+
+  def json_successful? json
+    return false if json.is_a?(Hash) && (json['error'] || json['errorMessages'] || json['errorMessage'])
+    return false if json.is_a?(Array) && json.first == 'errorMessage'
+
+    true
+  end
 end