jirametrics 3.3 → 3.4

data/lib/jirametrics/estimate_accuracy_chart.rb

@@ -14,17 +14,24 @@ class EstimateAccuracyChart < ChartBase
         The #{color_block '--estimate-accuracy-chart-completed-fill-color'} completed dots indicate
         cycletimes.
         <% if @has_aging_data %>
-          The #{color_block '--estimate-accuracy-chart-active-fill-color'} aging dots
+          The #{color_block '--estimate-accuracy-chart-active-fill-color'} aging arrows
           (click on the legend to turn them on) show the current
-          age of items, which will give you a hint as to where they might end up. If they're already
-          far to the right then you know you have a problem.
+          age of items, which will give you a hint as to where they might end up. They point right
+          because those items haven't finished yet, so every one of them will keep moving that way
+          until it does. If they're already far to the right then you know you have a problem.
         <% end %>
       </div>
       <% if @correlation_coefficient %>
         <div class="p">
           The completed items here have a correlation coefficient of <b><%= @correlation_coefficient.round(3) %></b>.
           The closer it is to +1, the stronger the positive correlation. The closer it is to -1,
-          the stronger the negative collalation. Zero would mean no correlation at all.
+          the stronger the negative correlation. Zero would mean no correlation at all.
+        </div>
+      <% elsif @estimates_are_numeric == false %>
+        <div class="p">
+          There's no correlation coefficient here because these estimates are categories rather than
+          numbers. Working one out means measuring the gaps between values, and there's no defined
+          gap between one category and the next, so any number we showed you would be invented.
         </div>
       <% end %>
     HTML
@@ -46,14 +53,15 @@ class EstimateAccuracyChart < ChartBase
     end
     data_sets = scan_issues
 
-    return '' if data_sets.empty?
+    return render_no_data if data_sets.empty?
 
     wrap_and_render(binding, __FILE__)
   end
 
   def scan_issues
     completed_hash, aging_hash = split_into_completed_and_aging issues: issues
-    @correlation_coefficient = correlation_coefficient(completed_hash) unless completed_hash.empty?
+    @estimates_are_numeric = numeric_estimates? completed_hash
+    @correlation_coefficient = correlation_coefficient(completed_hash) if @estimates_are_numeric
     estimation_units = current_board.estimation_configuration.units
     @has_aging_data = !aging_hash.empty?
 
@@ -77,7 +85,7 @@ class EstimateAccuracyChart < ChartBase
         {
           'x' => cycle_time,
           'y' => estimate,
-          'r' => values.size * 2,
+          'r' => bubble_radius(values.size),
           'title' => title
         }
       end
@@ -90,11 +98,23 @@ class EstimateAccuracyChart < ChartBase
         'showLine' => false,
         'backgroundColor' => fill_color,
         'borderColor' => border_color,
-        'hidden' => starts_hidden
+        'hidden' => starts_hidden,
+        # The active series is drawn as right pointing arrows rather than discs, because its
+        # cycletime is a lower bound that keeps growing. The erb needs to know which one that is.
+        'still_in_progress' => completed_or_active == 'active'
       }
     end
   end
 
+  # Chart.js sizes a bubble by its radius but the eye reads it by area, so the radius has
+  # to go as the square root of the count. This multiplier is the radius of a single issue
+  # and everything else scales up from there.
+  SINGLE_ISSUE_RADIUS = 4
+
+  def bubble_radius issue_count
+    (SINGLE_ISSUE_RADIUS * Math.sqrt(issue_count)).round 1
+  end
+
   def estimate_label estimate:, estimation_units:
     if @y_axis_type == 'linear'
       if estimation_units == :story_points
@@ -183,6 +203,15 @@ class EstimateAccuracyChart < ChartBase
 
   # Correlation coefficient is calculated using the Pearson Correlation Coefficient
   # r = Σ((xi - x̄)(yi - ȳ)) / sqrt(Σ(xi - x̄)² · Σ(yi - ȳ)²)
+  # A Pearson coefficient is arithmetic on the distances between values, so it needs a scale where
+  # those distances mean something. T-shirt sizes are ordered but not spaced: nothing says the gap
+  # from M to L matches the gap from S to M. Summing them used to raise and take the export with it.
+  def numeric_estimates? completed_hash
+    return false if completed_hash.empty?
+
+    completed_hash.keys.all? { |estimate, _cycle_time| estimate.is_a? Numeric }
+  end
+
   def correlation_coefficient completed_hash
     list1 = []
     list2 = []

data/lib/jirametrics/expedited_chart.rb

@@ -24,12 +24,13 @@ class ExpeditedChart < ChartBase
     super()
 
     header_text 'Expedited work'
+    no_data_text '<%= render_header %><div>There is no expedited work in this time period.</div>'
     description_text <<-HTML
       <div class="p">
         This chart only shows issues that have been expedited at some point. We care about these as
         any form of expedited work will affect the entire system and will slow down non-expedited work.
         Refer to this article on
-        <a href="https://improvingflow.com/2021/06/16/classes-of-service.html">classes of service</a>
+        <a href="https://blog.mikebowler.ca/2021/06/16/classes-of-service/">classes of service</a>
         for a longer explanation on why we want to avoid expedited work.
       </div>
       <div class="p">
@@ -49,11 +50,9 @@ class ExpeditedChart < ChartBase
       make_expedite_lines_data_set(issue: issue, expedite_data: prepare_expedite_data(issue))
     end
 
-    if data_sets.empty?
-      '<h1 class="foldable">Expedited work</h1><div>There is no expedited work in this time period.</div>'
-    else
-      wrap_and_render(binding, __FILE__)
-    end
+    return render_no_data if data_sets.empty?
+
+    wrap_and_render(binding, __FILE__)
   end
 
   def prepare_expedite_data issue

data/lib/jirametrics/exporter.rb

@@ -6,6 +6,30 @@ class Exporter
   attr_reader :project_configs
   attr_accessor :file_system
 
+  # Nothing in examples/ is loaded with the rest of the library, because an example is something you
+  # opt into rather than something the product provides. Each file there defines the method named
+  # after it. Derived from the directory rather than listed, so a new example is covered by existing.
+  EXAMPLE_NAMES = Dir[File.join(__dir__, 'examples', '*.rb')]
+    .collect { |file| File.basename(file, '.rb').to_sym }
+    .freeze
+
+  # Deliberately method_missing rather than stub methods that the real ones overwrite. Stubs depend
+  # on this file loading before the example, which require_all does not guarantee, and when it lost
+  # that race the stub replaced the working method.
+  def method_missing name, *args, **keywords, &block
+    return super unless EXAMPLE_NAMES.include? name
+
+    raise "#{name} is an example rather than part of jirametrics, so your config has to ask for " \
+      "it. Add this line to the top of your config file:\n\n" \
+      "  require 'jirametrics/examples/#{name}'\n"
+  end
+
+  # These are not things we respond to. Calling one raises, so respond_to? should say false and the
+  # message above should be the only way anyone learns they exist.
+  def respond_to_missing? name, include_private = false
+    super
+  end
+
   def self.logfile_name
     @logfile_name ||= 'jirametrics.log'
   end

data/lib/jirametrics/flow_efficiency_scatterplot.rb

@@ -12,10 +12,11 @@ class FlowEfficiencyScatterplot < ChartBase
     super()
 
     header_text 'Flow Efficiency'
+    no_data_text '<%= render_header %><div>No data matched the selected criteria. Nothing to show.</div>'
     description_text <<-HTML
       <div class="p">
         This chart shows the active time against the the total time spent on a ticket.
-        <a href="https://improvingflow.com/2024/07/06/flow-efficiency.html">Flow  efficiency</a> is the ratio
+        <a href="https://blog.mikebowler.ca/2024/07/06/flow-efficiency/">Flow  efficiency</a> is the ratio
         between these two numbers.
       </div>
       <div class="p">
@@ -63,10 +64,7 @@ class FlowEfficiencyScatterplot < ChartBase
       create_dataset(issues: issues, label: rules.label, color: rules.color)
     end
 
-    if data_sets.empty?
-      return "<h1 class='foldable'>#{@header_text}</h1>" \
-        '<div>No data matched the selected criteria. Nothing to show.</div>'
-    end
+    return render_no_data if data_sets.empty?
 
     wrap_and_render(binding, __FILE__)
   end

data/lib/jirametrics/html/aging_work_in_progress_chart.erb

@@ -42,21 +42,24 @@ new Chart(document.getElementById(<%= chart_id.inspect %>).getContext('2d'),
           z: 1 // draw the grid lines on top of the bars
         },
         stacked: false,
-        max: <%= (@max_age * 1.1).to_i %>
+        max: <%= (@max_age * 1.1).to_i %>,
+        ticks: {
+          // Uses labelExceptCrowdedCeiling() defined in index.js.
+          callback: labelExceptCrowdedCeiling
+        }
       }
     },
     plugins: {
       tooltip: {
         callbacks: {
           label: function(context) {
-            if( typeof(context.dataset.data[context.dataIndex]) == "number" ) {
-              let full_data = <%= @bar_data.inspect %>;
-              let columnIndex = context.dataIndex;
-              let rowIndex = context.datasetIndex - <%= @row_index_offset %>;
-              return context.dataset.label + " of completed work items left this column in " +full_data[rowIndex][columnIndex] + " days or less";
+            let point = context.dataset.data[context.dataIndex];
+            // A band is a floating bar, [bottom, top]. A dot is an object carrying its own title.
+            if( Array.isArray(point) ) {
+              return context.dataset.label + " of completed work items left this column in " + point[1] + " days or less";
             }
             else {
-              return context.dataset.data[context.dataIndex].title;
+              return point.title;
             }
           }
         }

data/lib/jirametrics/html/estimate_accuracy_chart.erb

@@ -6,7 +6,40 @@
 new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
   type: 'bubble',
   data: {
-    datasets: <%= JSON.generate(data_sets) %>
+    datasets: (function() {
+      const dataSets = <%= JSON.generate(data_sets) %>;
+      // The still in progress series is drawn as right pointing arrows rather than discs. Those
+      // items have not finished, so their cycletime is a lower bound that keeps growing and the
+      // arrow says "this one is still moving that way". Same idea as the capped-value arrows on
+      // the scatterplot, turned to point along the axis that is actually still moving.
+      //
+      // Sized per point rather than at a fixed size, because on this chart the radius carries the
+      // number of issues stacked at that spot and we would be throwing that away.
+      function movementArrow(color, radius) {
+        const size = Math.max(12, Math.round(radius * 3));
+        const glyph = document.createElement('canvas');
+        glyph.width = size; glyph.height = size;
+        const pen = glyph.getContext('2d');
+        const middle = size / 2, head = size * 0.3, tip = size * 0.88;
+        pen.strokeStyle = color;
+        pen.lineWidth = Math.max(2, radius * 0.42);
+        pen.lineCap = 'round'; pen.lineJoin = 'round';
+        pen.beginPath();
+        pen.moveTo(size * 0.12, middle); pen.lineTo(tip, middle);
+        pen.moveTo(tip - head, middle - head);
+        pen.lineTo(tip, middle);
+        pen.lineTo(tip - head, middle + head);
+        pen.stroke();
+        return glyph;
+      }
+      dataSets.forEach(function(dataSet) {
+        if (!dataSet.still_in_progress) return;
+        dataSet.pointStyle = dataSet.data.map(function(point) {
+          return movementArrow(dataSet.backgroundColor, point.r);
+        });
+      });
+      return dataSets;
+    })()
   },
   options: {
     responsive: <%= canvas_responsive? %>, // If responsive is true then it fills the screen

data/lib/jirametrics/html/index.css

@@ -33,6 +33,41 @@
   --type-bug-color: #D55E00;         /* Okabe-Ito vermilion */
   --type-spike-color: #CC79A7;       /* Okabe-Ito reddish purple */
 
+  /* The dependency chart is drawn by graphviz, which sets the label text inside the node rather
+     than beside it, so unlike --type-*-color above these are judged against the text and not
+     against the page. They are opaque, so the fill is the background the text sits on and there
+     is nothing for a dark theme to override.
+
+     These are Okabe-Ito hues rather than Okabe-Ito itself. At full strength they sit in a middle
+     band of lightness where NEITHER black nor white text is comfortable on them, which is the
+     thing to understand before changing any of this. Contrast ratio alone will mislead you here:
+     two earlier attempts cleared 7:1 and then 9:1, both of which WCAG calls comfortable, and both
+     still read as muddy in a real report. A mid-toned fill with dark text on it looks wrong at
+     almost any ratio. Going DARK and putting white text on it is what actually reads, so most of
+     these fills are dark, and each carries its own label colour: they are a pair, and changing a
+     fill without rechecking its label is how you get unreadable nodes.
+
+     They are not all dark, because the lightness spread is what does most of the work of keeping
+     them apart. Levelling them all to the same darkness measures about 3, which is unusable;
+     pastelling them all measures about 4.7, which is what the original colours here did. Run
+     `rake check_colors` for what they currently measure, against the full Okabe-Ito set as a
+     reference ceiling. */
+  --dependency-chart-story-color: #015C41;         /* Okabe-Ito bluish green, darkened */
+  --dependency-chart-story-label-color: white;
+  --dependency-chart-task-color: #56B4E9;          /* Okabe-Ito sky blue, unchanged */
+  --dependency-chart-task-label-color: black;
+  --dependency-chart-bug-color: #783200;           /* Okabe-Ito vermilion, darkened. Also Defect */
+  --dependency-chart-bug-label-color: white;
+  --dependency-chart-epic-color: #F0E442;          /* Okabe-Ito yellow, unchanged */
+  --dependency-chart-epic-label-color: black;
+  --dependency-chart-spike-color: #762A58;         /* Okabe-Ito reddish purple, darkened */
+  --dependency-chart-spike-label-color: white;
+
+  /* For a node whose fill was set in the config rather than coming from the palette above, where
+     we cannot know what would read on it. */
+  --dependency-chart-label-color: black;
+  --dependency-chart-link-color: gray;
+
   --status-category-todo-color: gray;
   --status-category-inprogress-color: #0072B2;  /* Okabe-Ito blue */
   --status-category-done-color: #009E73;         /* Okabe-Ito bluish green */
@@ -71,10 +106,16 @@
   --wip-by-column-chart-limit-line-color: #D55E00;        /* Okabe-Ito vermilion */
   --wip-by-column-chart-recommendation-color: #009E73;    /* Okabe-Ito bluish green */
 
-  --estimate-accuracy-chart-completed-fill-color: #92D9C0;    /* light bluish green */
-  --estimate-accuracy-chart-completed-border-color: #009E73;  /* Okabe-Ito bluish green */
-  --estimate-accuracy-chart-active-fill-color: #F4C6AD;       /* light vermilion */
-  --estimate-accuracy-chart-active-border-color: #D55E00;     /* Okabe-Ito vermilion */
+  /* Full strength, not lightened. The pastel versions of these two collapsed into the same beige
+     under protanopia (4.45 apart, where the palette's own floor is 11.08) and measured 1.6 against
+     white, half the contrast WCAG asks of a shape you need to see. At full strength they are 18.45
+     apart and clear the contrast floor. The border is the page colour rather than a second hue, so
+     it separates overlapping bubbles instead of competing with the fill, and needs no dark mode
+     override. See jirametrics-7ss. */
+  --estimate-accuracy-chart-completed-fill-color: #009E73;    /* Okabe-Ito bluish green */
+  --estimate-accuracy-chart-completed-border-color: var(--body-background);
+  --estimate-accuracy-chart-active-fill-color: #D55E00;       /* Okabe-Ito vermilion */
+  --estimate-accuracy-chart-active-border-color: var(--body-background);
 
   --expedited-chart-no-longer-expedited: gray;
   --expedited-chart-dot-issue-started-color: #E69F00;     /* Okabe-Ito orange */
@@ -248,6 +289,10 @@ div.child_issue {
 html[data-theme="dark"] {
   --warning-banner: #9F2B00;
   --non-working-days-color: #2f2f2f;
+
+  /* See the matching comment in the prefers-color-scheme block below. */
+  --dependency-chart-link-color: #999999;
+
   --type-story-color: #2DCB9A;       /* lighter bluish green for dark bg */
   --type-task-color: #56B4E9;        /* sky blue for dark bg */
   --type-bug-color: #E69F00;         /* orange instead of vermilion for dark bg */
@@ -276,8 +321,6 @@ html[data-theme="dark"] {
      band. Those are the two ends of the duration ramp, so confusing them is the worst case. This
      stays in the same warm family so the ramp still reads cool to warm as work ages. */
   --wip-chart-duration-more-than-four-weeks-color: #B16BAE;
-  --estimate-accuracy-chart-completed-border-color: #2DCB9A;
-  --estimate-accuracy-chart-active-border-color: #E69F00;
   --expedited-chart-dot-issue-stopped-color: #2DCB9A;
   --expedited-chart-dot-expedite-started-color: #E69F00;
   --expedited-chart-dot-expedite-stopped-color: #2DCB9A;
@@ -400,6 +443,12 @@ html[data-theme="light"] {
     --warning-banner: #9F2B00;
 
     --non-working-days-color: #2f2f2f;
+
+    /* The only dependency chart colour needing a dark variant. The fills do not, because they
+       are opaque and are their own background, but link lines and their labels sit on the page.
+       Plain gray manages only 2.4:1 here against 3.94:1 in light mode, so it is lifted to match. */
+    --dependency-chart-link-color: #999999;
+
     --type-story-color: #2DCB9A;       /* lighter bluish green for dark bg */
     --type-task-color: #56B4E9;        /* sky blue for dark bg */
     --type-bug-color: #E69F00;         /* orange instead of vermilion for dark bg */
@@ -436,9 +485,6 @@ html[data-theme="light"] {
     --wip-chart-duration-four-weeks-or-less-color: #D55E00;
     --wip-chart-duration-more-than-four-weeks-color: #B16BAE; /* see jirametrics-3fg */
 
-    --estimate-accuracy-chart-completed-border-color: #2DCB9A;
-    --estimate-accuracy-chart-active-border-color: #E69F00;
-
     --expedited-chart-dot-issue-stopped-color: #2DCB9A;
     --expedited-chart-dot-expedite-started-color: #E69F00;
     --expedited-chart-dot-expedite-stopped-color: #2DCB9A;

data/lib/jirametrics/html/index.js

@@ -157,6 +157,19 @@ function withAlpha(color, alpha) {
   return resolved.replace(/^rgb\(/, 'rgba(').replace(/\)$/, `, ${alpha})`)
 }
 
+// A y-axis tick callback for charts whose ceiling is deliberately set above their tallest value, so
+// you can see that nothing is clipped. Chart.js labels that ceiling too, which gives you an arbitrary
+// number like 169 sitting just above 160, or 62 above 50. Drop that label, unless the ceiling happens
+// to land exactly on the regular grid, in which case it is a perfectly good label and worth keeping.
+// Pass it straight to ticks.callback.
+//   ticks 0 20 .. 160 169 -> 169 dropped, it breaks the spacing
+//   ticks 0 20 .. 100 120 -> 120 kept, it continues the spacing
+function labelExceptCrowdedCeiling(value, index, ticks) {
+  if (index !== ticks.length - 1 || index < 2) return value
+  let regularGap = ticks[index - 1].value - ticks[index - 2].value
+  return value - ticks[index - 1].value === regularGap ? value : null
+}
+
 function createDiagonalPattern(color = 'black') {
   // create a 5x5 px canvas for the pattern's base shape
   let shape = document.createElement('canvas')

data/lib/jirametrics/html/legacy_colors.css

@@ -30,6 +30,22 @@ html[data-theme="light"] {
   --type-bug-color: orange;
   --type-spike-color: #9400D3;
 
+  /* The dependency chart's original pastels. They are pleasant but they are not safe: pale
+     colours sit close together, and green, peach and pale yellow are hard to separate for anyone
+     with red-green colour vision deficiency. Every one of them is light, so the label colours all
+     go back to black; the shipped set has dark fills that need white. */
+  --dependency-chart-story-color: #90EE90;
+  --dependency-chart-story-label-color: black;
+  --dependency-chart-task-color: #87CEFA;
+  --dependency-chart-task-label-color: black;
+  --dependency-chart-bug-color: #ffdab9;
+  --dependency-chart-bug-label-color: black;
+  --dependency-chart-epic-color: #fafad2;
+  --dependency-chart-epic-label-color: black;
+  --dependency-chart-spike-color: #DDA0DD;
+  --dependency-chart-spike-label-color: black;
+  --dependency-chart-link-color: gray;
+
   --status-category-todo-color: gray;
   --status-category-inprogress-color: #2663ff;
   --status-category-done-color: #00ff00;
@@ -106,6 +122,7 @@ html[data-theme="light"] {
 html[data-theme="dark"] {
   --warning-banner: #9F2B00;
   --non-working-days-color: #2f2f2f;
+  --dependency-chart-link-color: gray;   /* the chart had no dark variant originally */
   --type-story-color: #6fb86f;
   --type-task-color: #0021b3;
   --type-bug-color: #bb5603;
@@ -139,6 +156,7 @@ html[data-theme="dark"] {
   :root {
     --warning-banner: #9F2B00;
     --non-working-days-color: #2f2f2f;
+    --dependency-chart-link-color: gray;   /* the chart had no dark variant originally */
     --type-story-color: #6fb86f;
     --type-task-color: #0021b3;
     --type-bug-color: #bb5603;

data/lib/jirametrics/html/time_based_histogram.erb

@@ -100,16 +100,20 @@ if show_stats
       <% 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>
+            <td style="text-align: right;"><%= stats_cell v[:min] %></td>
+            <td style="text-align: right;"><%= stats_cell v[:max] %></td>
+            <td style="text-align: right;"><%= stats_cell(v[:average]) { |average| format '%.2f', average } %></td>
+            <td><%= stats_cell(v[:mode]) { |modes| modes.join ', ' } %></td>
             <% percentiles.each do |percentile| %>
-               <td style="text-align: right;"><%= v[:percentiles][percentile] %></td>
+               <td style="text-align: right;"><%= stats_cell v.dig(:percentiles, percentile) %></td>
             <% end %>
           </tr>
        <% end %>
      </table>
+     <% if any_empty_stats? the_stats %>
+       <p><b>&ndash;</b> means no usable data for that group. Every item in it was excluded from the histogram
+       because it had no measurable cycle time. The Data Quality report has the details.</p>
+     <% end %>
   </div>
   <div>
     <p>These statistics help understand the <i>"shape"</i> of the histogram distribution, to help us with predictions.</p>

data/lib/jirametrics/html/time_based_scatterplot.erb

@@ -82,9 +82,10 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
           color: <%= CssVariable['--grid-line-color'].to_json %>
         },
         ticks: {
+          // Uses labelExceptCrowdedCeiling() defined in index.js.
           callback: function(value, index, ticks) {
             <% if @cap %>if (value > <%= @cap[:cutoff] %>) return null;<% end %>
-            return index === ticks.length - 1 ? null : value;
+            return labelExceptCrowdedCeiling(value, index, ticks);
           }
         }
       }

data/lib/jirametrics/issue.rb

@@ -63,7 +63,7 @@ class Issue
 
   def labels = raw_fields['labels'] || []
 
-  def author = raw_fields['creator']&.[]('displayName') || ''
+  def author = User.from_raw(raw_fields['creator'])&.display_name || ''
 
   def resolution = raw_fields['resolution']&.[]('name')
 
@@ -374,13 +374,11 @@ class Issue
     @changes.reverse.find(&:resolution?)
   end
 
-  def assigned_to
-    raw_fields['assignee']&.[]('displayName')
-  end
+  # nil rather than '' when there's no assignee, and daily_view relies on it to decide whether to
+  # render an assignee line at all.
+  def assigned_to = User.from_raw(raw_fields['assignee'])&.display_name
 
-  def assigned_to_icon_url
-    raw_fields['assignee']&.[]('avatarUrls')&.[]('16x16')
-  end
+  def assigned_to_icon_url = User.from_raw(raw_fields['assignee'])&.avatar_url
 
   # Many test failures are simply unreadable because the default inspect on this class goes
   # on for pages. Shorten it up.

data/lib/jirametrics/issue_printer.rb

@@ -19,10 +19,11 @@ class IssuePrinter
   end
 
   def assignee_line
-    assignee = @issue.raw['fields']['assignee']
-    return '' if assignee.nil?
+    user = User.from_raw @issue.raw['fields']['assignee']
+    return '' if user.nil?
 
-    "  [assignee] #{assignee['name'].inspect} <#{assignee['emailAddress']}>\n"
+    email = user.email_address
+    "  [assignee] #{user.display_name.inspect}#{" <#{email}>" if email}\n"
   end
 
   def links_section
@@ -78,6 +79,7 @@ class IssuePrinter
   def render_history history
     type_width = history.collect { |_time, type, _detail, _artificial| type&.length || 0 }.max
     sort_history!(history)
+    # Not all ruby versions return the same string for to_s so we force to a known format.
     history.map do |time, type, detail, _artificial|
       type = type.nil? ? '-' * type_width : type.rjust(type_width)
       "    #{time.strftime '%Y-%m-%d %H:%M:%S %z'} [#{type}] #{detail}\n"

data/lib/jirametrics/jira_gateway.rb

@@ -109,15 +109,13 @@ class JiraGateway
 
   VerifyResult = Data.define(:ok, :url, :message)
 
-  # Confirm that our credentials actually authenticate against Jira. We deliberately hit /myself,
-  # which requires authentication on every Jira edition (anonymous callers get a 401). An endpoint
-  # that also answers anonymously would happily "succeed" with bad credentials, which defeats the
-  # whole point. Cloud speaks v3, Server/Data Center speaks v2. Returns a VerifyResult rather than
-  # raising so the caller can report on every configured connection and set its own exit status.
   def verify_connection
+    # We use /myself because the only reason it can fail is if we aren't authenticated.
     json = call_url relative_url: "/rest/api/#{cloud? ? 3 : 2}/myself"
-    user = json['displayName'] || json['name'] || json['emailAddress'] || 'unknown user'
-    VerifyResult.new(ok: true, url: @jira_url, message: "Verified #{@jira_url} (authenticated as #{user})")
+
+    user = User.new raw: json
+    who = user.display_name || 'unknown user'
+    VerifyResult.new(ok: true, url: @jira_url, message: "Verified #{@jira_url} (authenticated as #{who})")
   rescue StandardError => e
     VerifyResult.new(ok: false, url: @jira_url, message: "Could not authenticate to #{@jira_url}: #{e.message}")
   end

data/lib/jirametrics/sprint_burndown.rb

@@ -37,13 +37,13 @@ class SprintBurndown < ChartBase
   end
 
   def run
-    return nil unless current_board.scrum?
+    return render_no_data unless current_board.scrum?
 
     sprints = sprints_in_time_range current_board
     change_data_by_sprint = gather_change_data_by_sprint sprints
 
     result = +''
-    result << render_top_text(binding)
+    result << render_top_text
 
     # HashEachMethods misreads this array of [method, title] pairs as a hash and thinks y_axis_title
     # is unused; in fact the ERB template reads it (and data_method) from the binding we pass to render.

data/lib/jirametrics/testing/mock_board.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class JiraMetrics
+  module Testing
+    # Builds a Board from the two files jirametrics already downloads for you, so a test can use your
+    # own board rather than a fabricated one.
+    #
+    #   board = MockBoard.load statuses: 'target/mine_statuses.json',
+    #                          configuration: 'target/mine_board_1_configuration.json'
+    #
+    # Takes filenames rather than packaging a sample board, because a board that resembles yours is
+    # worth more than one of ours, and because sample data would have to be carried in the gem forever.
+    class MockBoard
+      class << self
+        def load statuses:, configuration:
+          board = Board.new(
+            raw: JSON.parse(File.read(configuration, encoding: 'UTF-8')),
+            possible_statuses: load_statuses(statuses)
+          )
+          board.project_config = ProjectConfig.new(
+            exporter: Exporter.new, target_path: File.dirname(configuration), jira_config: nil, block: nil
+          )
+          board
+        end
+
+        def load_statuses filename
+          JSON.parse(File.read(filename, encoding: 'UTF-8')).each_with_object(StatusCollection.new) do |raw, collection|
+            collection << Status.from_raw(raw)
+          end
+        end
+      end
+    end
+  end
+end