jirametrics 2.7 → 2.11

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/index.css

@@ -2,6 +2,7 @@
   --body-background: white;
   --default-text-color: black;
   --grid-line-color: lightgray;
+  --warning-banner: yellow;
 
   --cycletime-scatterplot-overall-trendline-color: gray;
 
@@ -19,6 +20,7 @@
   --status-category-todo-color: gray;
   --status-category-inprogress-color: #2663ff;
   --status-category-done-color: #00ff00;
+  --status-category-unknown-color: black;
 
   --aging-work-bar-chart-percentage-line-color: red;
   --aging-work-bar-chart-separator-color: white;
@@ -26,8 +28,16 @@
   --throughput_chart_total_line_color: gray;
   
   --aging-work-in-progress-chart-shading-color: lightgray;
+  --aging-work-in-progress-chart-shading-50-color: #2E8BC0; // green;
+  --aging-work-in-progress-chart-shading-85-color: #ADD8E6; // yellow;
+  --aging-work-in-progress-chart-shading-98-color: #FF8A8A; // orange;
+  --aging-work-in-progress-chart-shading-100-color: #FF2E2E; // red;
+  
   --aging-work-in-progress-by-age-trend-line-color: gray;
   
+  --aging-work-table-date-in-jeopardy: yellow;
+  --aging-work-table-date-overdue: red;
+
   --hierarchy-table-inactive-item-text-color: gray;
 
   --wip-chart-completed-color: #00ff00;
@@ -99,9 +109,6 @@ table.standard {
     background-color: #eee;
   }
 }
-.quality_note_bullet {
-  color: red;
-}
 
 .chart {
   background-color: white;
@@ -119,8 +126,26 @@ div.color_block {
   border: 1px solid black;
 }
 
+ul.quality_report {
+  list-style-type: '⮕';
+  ::marker {
+    color: red;
+  }
+  li {
+    padding: 0.2em;
+  }
+}
+
+#footer {
+  text-align: center;
+  margin-top: 1em;
+  border-top: 1px solid gray;
+}
+
 @media screen and (prefers-color-scheme: dark) {
   :root {
+    --warning-banner: #9F2B00;
+
     --non-working-days-color: #2f2f2f;
     --type-story-color: #6fb86f;
     --type-task-color: #0021b3;
@@ -136,8 +161,6 @@ div.color_block {
     --dead-color: black;
     --wip-chart-active-color: #2551c1;
 
-    --aging-work-in-progress-chart-shading-color: #b4b4b4;
-
     --status-category-inprogress-color: #1c49bb;
 
     --cycletime-scatterplot-overall-trendline-color: gray;

data/lib/jirametrics/html/index.erb

@@ -23,16 +23,20 @@
       window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
         location.reload()
       })
-
     </script>
     <style>
 <%= css %>
     </style>
+    <script type="text/javascript">
+      Chart.defaults.color = getComputedStyle(document.documentElement).getPropertyValue('--default-text-color');
+    </script>
   </head>
   <body>
-    <div>
-      Page generated <%= (timezone_offset.nil? ? DateTime.now : DateTime.now.new_offset(timezone_offset)).strftime('%Y-%b-%d at %I:%M:%S%P') %>
-    </div>
+    <noscript>
+      <div style="padding: 1em; background: gray; color: white; font-size: 2em;">
+        Javascript is currently disabled and that means that almost all of the charts in this report won't render. If you'd loaded this from a folder on SharePoint then save it locally and load it again.
+      </div>
+    </noscript>
     <%= "\n" + @sections.collect { |text, type| text if type == :header }.compact.join("\n\n") %>
     <%= "\n" + @sections.collect { |text, type| text if type == :body }.compact.join("\n\n") %>
   </body>

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,9 +64,11 @@ 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
+
     html_directory = "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
     css = load_css html_directory: html_directory
     erb = ERB.new file_system.load(File.join(html_directory, 'index.erb'))
@@ -99,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
@@ -141,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
@@ -173,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
@@ -182,6 +170,7 @@ class HtmlReportConfig
 
     after_init_block&.call chart
 
+    @charts << chart
     html chart.run
   end
 
@@ -202,4 +191,24 @@ class HtmlReportConfig
   def boards
     @file_config.project_config.board_configs.collect(&:id).collect { |id| find_board id }
   end
+
+  def create_footer now: DateTime.now
+    now = now.new_offset(timezone_offset)
+    version = Gem.loaded_specs['jirametrics']&.version || 'Next'
+
+    <<~HTML
+      <section id="footer">
+        Report generated on <b>#{now.strftime('%Y-%b-%d')}</b> at <b>#{now.strftime('%I:%M:%S%P %Z')}</b>
+        with <a href="https://jirametrics.org">JiraMetrics</a> <b>v#{version}</b>
+      </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