jirametrics 3.2 → 3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9952ccca62cfc09c062633e0ee50828016681b77b537e736e77046a0365a47ca
-  data.tar.gz: 577b27edc9b07c42285339995ea3a23f2082d62feaa34a1d225cf7c61300fda0
+  metadata.gz: 25832ca03b7dcdc188d741171ee47d3f463551d1893257e39a9b52c0fb45dd83
+  data.tar.gz: a4d1b9ce7039e568e8c1a614862688887bc4e188c3b24af646922983eb859b9f
 SHA512:
-  metadata.gz: 29ec03cf3689cd29d772ca781dd750fe33c54d203307b1ce0bb378b35b211a70b33c7d81503b688fad0cd1f7204b14b3fdaebfcc7fd2375ff3dbbc42ed6615c5
-  data.tar.gz: b73780c0e68abea384a151d2f194c17e9705f9e507fd1587809d7ddb6691b9157aa82b6ab3a3cdd86ca513acd489b7c5dac733184cd1774887f0e2d6c6e5d990
+  metadata.gz: cdbfed22a95da07665930c339330d1f6def0f3ce36118fa68fd249295bbb7386d1a85bd0fe4301de8c5fc35d94e1a98bdee22f81daf9fc59db8095ea02000cec
+  data.tar.gz: 9122e7aa6cfb881723e7acc7b20df65a12ba372ab0736e94fe2e92e6e5206f69c342b94242e5f7e67d43135a426dab7c82b01d8e57fd5f33ee2a2227b0302445

data/lib/jirametrics/aging_work_bar_chart.rb

@@ -2,19 +2,27 @@
 
 require 'jirametrics/chart_base'
 require 'jirametrics/bar_chart_range'
+require 'jirametrics/percentile_validation'
 
 class AgingWorkBarChart < ChartBase
+  include PercentileValidation
+
   def initialize block
     super()
 
     @age_cutoff = nil
+    @percentage_lines = [] # Populated by run; the description reads it, so it must never be nil.
+    percentiles [85]
     header_text 'Aging Work Bar Chart'
+    # div class="p" throughout rather than <p>: color_block emits a div and the list below is an
+    # ol, neither of which is legal inside a paragraph. A browser closes the p at the first one,
+    # which strands the rest of the text outside it. This is what the other charts use.
     description_text <<-HTML
-      <p>
+      <div class="p">
         This chart shows all active (started but not completed) work, ordered from oldest at the top to
         newest at the bottom.
-      </p>
-      <p>
+      </div>
+      <div class="p">
         There are <%= (aggregated_project? || current_board.scrum?) ? 'four' : 'three' %> bars for each issue, and hovering over any of the bars will provide more details.
         <ol>
           <li>Status: The status the issue was in at any time. The colour indicates the
@@ -29,7 +37,8 @@ class AgingWorkBarChart < ChartBase
             <li>Sprints: The sprints that the issue was in.</li>
           <% end %>
         </ol>
-      </p>
+      </div>
+      <%= percentile_description %>
       #{describe_non_working_days}
     HTML
 
@@ -53,8 +62,12 @@ class AgingWorkBarChart < ChartBase
       .flatten
       .compact
 
-    percentage = calculate_percent_line
-    percentage_line_x = date_range.end - calculate_percent_line if percentage
+    # An item sitting left of one of these lines has been aging longer than that percentage of
+    # everything we completed, so the line is drawn that many days back from today. Held on the
+    # instance because the description text reads it too, and it must not be computed twice.
+    @percentage_lines = percentile_lines.collect do |percentile, days|
+      { percentile: percentile, days: days, x: date_range.end - days, id: "percentile_#{percentile}" }
+    end
 
     if aging_issues.empty?
       @description_text = '<p>There is no aging work</p>'
@@ -309,17 +322,105 @@ class AgingWorkBarChart < ChartBase
     BarChartRange.new(
       start: previous_change.time,
       stop: stop_time,
-      color: CssVariable["--priority-color-#{previous_change.value.downcase.gsub(/\s/, '')}"],
+      color: priority_color(previous_change.value),
       title: title,
       highlight: expedited
     )
   end
 
+  # Which percentiles of completed cycle time to mark with a vertical line. An empty list draws
+  # none. The lines all share one colour because, unlike the scatterplot, they do not stand for
+  # groups; their position is what tells them apart.
+  def percentiles list = nil
+    @percentiles = validate_percentiles(list) unless list.nil?
+    @percentiles
+  end
+
+  # Explains the vertical line or lines, following whatever was configured. Note the caller must
+  # be the ERB tag <%= percentile_description %> and NOT string interpolation: description_text is
+  # built during initialize, before the config block has run, so interpolation would freeze the
+  # default into every report while ignoring what the user asked for.
+  def percentile_description
+    lines = @percentage_lines
+    return '' if lines.empty?
+
+    swatch = color_block '--aging-work-bar-chart-percentage-line-color'
+    if lines.size == 1
+      percentile = lines.first[:percentile]
+      days = lines.first[:days]
+      # <div class="p"> rather than <p>: color_block emits a div, and a div inside a p is invalid
+      # HTML, so the browser closes the paragraph early and the rest of the sentence escapes it.
+      <<-HTML
+        <div class="p">
+          The vertical #{swatch} line marks the #{ordinal percentile} percentile of how long
+          completed work actually took (#{label_days days}). Anything still in progress that
+          extends past it has now been aging longer than #{percentile}% of everything we
+          finished, which makes it worth a conversation.
+        </div>
+      HTML
+    else
+      described = lines.collect { |line| ordinal line[:percentile] }
+      <<-HTML
+        <div class="p">
+          The vertical #{swatch} lines mark the #{comma_and described} percentiles of how long
+          completed work actually took. Anything still in progress that extends past one of them
+          has been aging longer than that percentage of everything we finished. Hover a line to
+          see which one it is.
+        </div>
+      HTML
+    end
+  end
+
+  # Returns [[percentile, days], ...] for the configured percentiles, dropping any that have no
+  # value because nothing completed in range.
+  def percentile_lines
+    percentiles.filter_map do |percentile|
+      days = calculate_percent_line percentage: percentile
+      [percentile, days] unless days.nil?
+    end
+  end
+
   def calculate_percent_line percentage: 85
-    days = completed_issues_in_range.filter_map { |issue| issue.board.cycletime.cycletime(issue) }.sort
-    return nil if days.empty?
+    percentile_of(
+      completed_issues_in_range.filter_map { |issue| issue.board.cycletime.cycletime(issue) },
+      percentage
+    )
+  end
+
+  # Priority names come from Jira and an admin can define whatever they like, so the variable we
+  # build from one may simply not exist, in which case the bar draws black. That is acceptable, but
+  # silently is not, so say it once per unknown priority and hand over the line to paste.
+  def priority_color priority_name
+    key = priority_name.downcase.gsub(/\s/, '')
+    warn_about_unknown_priority priority_name, key unless defined_priority_colors.include? key
+    CssVariable["--priority-color-#{key}"]
+  end
 
-    days[days.length * percentage / 100]
+  def warn_about_unknown_priority priority_name, key
+    @warned_priorities ||= []
+    return if @warned_priorities.include? key
+
+    @warned_priorities << key
+    file_system.log(
+      "Warning: the priority #{priority_name.inspect} has no colour defined, so it will be drawn " \
+      'in black on the aging work bar chart. That is fine if you do not mind how it looks. To ' \
+      'give it a colour, add this to the CSS file named by your include_css setting: ' \
+      ":root { --priority-color-#{key}: #0072B2; }",
+      also_write_to_stderr: true
+    )
+  end
+
+  # Read from the CSS rather than kept as a list here, so that defining a new priority colour is a
+  # CSS edit and the two cannot drift apart. Includes the user's own stylesheet, so defining the
+  # colour there silences the warning.
+  def defined_priority_colors
+    @defined_priority_colors ||=
+      begin
+        css = File.read File.join(html_directory, 'index.css')
+        extra = settings && settings['include_css']
+        css += File.read(extra) if extra && File.exist?(extra)
+        css.scan(/--priority-color-([a-z0-9]+)\s*:/).flatten.uniq
+      end
   end
 
   def age_cutoff days

data/lib/jirametrics/aging_work_in_progress_chart.rb

@@ -13,12 +13,15 @@ class AgingWorkInProgressChart < ChartBase
   def initialize block
     super()
     header_text 'Aging Work in Progress'
+    # div class="p" rather than <p>: the notes below are a ul, which is block level and not legal
+    # inside a paragraph, so a browser closes the p early. Harmless while the list is the last
+    # thing in the block, but it breaks the moment any text follows it.
     description_text <<-HTML
-      <p>
+      <div class="p">
         This chart shows only work items that have started but not completed, grouped by the column
         they're currently in. Hovering over a dot will show you the ID of that work item.
-      </p>
-      <p>
+      </div>
+      <div class="p">
         The shaded areas indicate what percentage of the work has passed that column within that time.
         Notes:
         <ul>
@@ -30,7 +33,7 @@ class AgingWorkInProgressChart < ChartBase
              backwards athough it could also indicate that a ticket jumped over columns as it moved to the right.
            </li>
         </ul>
-      </p>
+      </div>
       <div style="border: 1px solid gray; padding: 0.2em">
         <% @percentiles.keys.sort.reverse.each do |percent| %>
           <span style="padding-left: 0.5em; padding-right: 0.5em; vertical-align: middle;"><%= color_block @percentiles[percent] %> <%= percent %>%</span>
@@ -230,8 +233,9 @@ class AgingWorkInProgressChart < ChartBase
     end
 
     if has_unmapped && @description_text
-      @description_text += "<p>The items shown in #{column_name.inspect} are not visible on the " \
-        'board but are still active. Most likely everyone has forgotten about them.</p>'
+      @description_text += "<div class=\"p\">The items shown in #{column_name.inspect} are not " \
+        'visible on the board but are still active. Most likely everyone has forgotten about ' \
+        'them.</div>'
     else
       # @column_headings.pop
       @board_columns.pop

data/lib/jirametrics/aging_work_table.rb

@@ -2,7 +2,11 @@
 
 require 'jirametrics/chart_base'
 
+require 'jirametrics/percentile_validation'
+
 class AgingWorkTable < ChartBase
+  include PercentileValidation
+
   attr_accessor :today
   attr_reader :any_scrum_boards
 
@@ -11,25 +15,28 @@ class AgingWorkTable < ChartBase
     @stalled_threshold = 5
     @dead_threshold = 45
     @age_cutoff = 0
+    @percentile = 85
 
     header_text 'Aging Work Table'
+    # div class="p" rather than <p>: the legend below is a ul, which is block level and not legal
+    # inside a paragraph, so a browser closes the p early.
     description_text <<-TEXT
-      <p>
+      <div class="p">
         This chart shows all active (started but not completed) work, ordered from oldest at the top to
         newest at the bottom.
-      </p>
-      <p>
+      </div>
+      <div class="p">
         If there are expedited items that haven't yet started then they're at the bottom of the table.
         By the very definition of expedited, if we haven't started them already, we'd better get on that.
-      </p>
-      <p>
+      </div>
+      <div class="p">
         Legend:
         <ul>
         <li><b>E:</b> Whether this item is <b>E</b>xpedited.</li>
         <li><b>B/S:</b> Whether this item is either <b>B</b>locked or <b>S</b>talled.</li>
         <li><b>Forecast:</b> A forecast of how long it is likely to take to finish this work item.</li>
         </ul>
-      </p>
+      </div>
     TEXT
 
     instance_eval(&block)
@@ -125,7 +132,7 @@ class AgingWorkTable < ChartBase
 
   def dates_text issue
     days_remaining, error = @calculators[issue.board.id].forecasted_days_remaining_and_message(
-      issue: issue, today: @today
+      issue: issue, today: @today, percentile: percentile
     )
     message = nil
     message, error = due_date_status(issue, days_remaining, error) unless error
@@ -158,6 +165,14 @@ class AgingWorkTable < ChartBase
     text
   end
 
+  # Which percentile of historical column movement the Forecast column is based on. Singular,
+  # unlike the charts' "percentiles", because a forecast has to resolve to one number of days: the
+  # due date risk calculation compares that single figure against the due date.
+  def percentile value = nil
+    @percentile = validate_percentile(value) unless value.nil?
+    @percentile
+  end
+
   def age_cutoff age = nil
     @age_cutoff = age.to_i if age
     @age_cutoff

data/lib/jirametrics/blocked_stalled_change_stream_builder.rb

@@ -31,12 +31,16 @@ class BlockedStalledChangeStreamBuilder
     mock_change = ChangeItem.new time: end_time, artificial: true, raw: { 'field' => '' }, author_raw: nil
 
     (@changes + [mock_change]).each do |change|
-      previous_was_active = false if check_for_stalled(
+      counts_as_activity = !ignored_for_stalled?(change)
+
+      if counts_as_activity && check_for_stalled(
         change_time: change.time,
         previous_change_time: previous_change_time,
         stalled_threshold: @settings['stalled_threshold_days'],
         blocking_stalled_changes: result
       )
+        previous_was_active = false
+      end
 
       update_blocking_state state, change
 
@@ -47,13 +51,22 @@ class BlockedStalledChangeStreamBuilder
       result << new_change if record_change? new_change, previous_was_active, change, mock_change
 
       previous_was_active = new_change.active?
-      previous_change_time = change.time
+      # An ignored change must not advance the clock, or it would split one long gap into two
+      # short ones and hide a stall.
+      previous_change_time = change.time if counts_as_activity
     end
 
     finalize_stalled_tail result
     result
   end
 
+  # Some changelog entries are not somebody working on the item. Adding a Jira issue macro to a
+  # Confluence page writes a RemoteIssueLink, which should not reset the inactivity clock. They are
+  # still processed for blocking, so putting a field here only affects the stalled calculation.
+  def ignored_for_stalled? change
+    (@settings['stalled_ignored_fields'] || []).include? change.field
+  end
+
   def update_blocking_state state, change
     if change.flagged? && flagged_means_blocked?
       state.flag, state.flag_reason = flag_logic change

data/lib/jirametrics/board_movement_calculator.rb

@@ -119,10 +119,13 @@ class BoardMovementCalculator
     "#{days} day#{'s' unless days == 1}"
   end
 
-  def forecasted_days_remaining_and_message issue:, today:
+  # percentile is passed in rather than held on the calculator because this class is shared: the
+  # aging work in progress chart builds one too and never forecasts, so it has no business
+  # carrying a forecast setting.
+  def forecasted_days_remaining_and_message issue:, today:, percentile: 85
     return [nil, 'Already done'] if issue.done?
 
-    likely_age_data = age_data_for percentage: 85
+    likely_age_data = age_data_for percentage: percentile
 
     column_name, entry_time = find_current_column_and_entry_time_in_column issue
     return [nil, 'This issue is not visible on the board. No way to predict when it will be done.'] if column_name.nil?
@@ -145,14 +148,22 @@ class BoardMovementCalculator
 
     remaining_in_current_column = likely_age_data[column_index] - age_in_column
     if remaining_in_current_column.negative?
-      message = "This item is an outlier at #{label_days issue.board.cycletime.age(issue, today: today)} " \
-        "in the #{column_name.inspect} column. Most items on this board have left this column in " \
-        "#{label_days likely_age_data[column_index]} or less, so we cannot forecast when it will be done."
-      remaining_in_current_column = 0
-      return [nil, message]
+      return [nil, outlier_message(
+        issue: issue, today: today, column_name: column_name, percentile: percentile,
+        column_age: likely_age_data[column_index]
+      )]
     end
 
     forecasted_days = last_non_zero_datapoint - likely_age_data[column_index] + remaining_in_current_column
     [forecasted_days, message]
   end
+
+  # Why we cannot forecast: this item has already been in the column longer than the historical
+  # figure we would forecast from. The message names the percentile rather than characterising it
+  # as "most", which was only ever a fair description at the default and plainly wrong at the median.
+  def outlier_message issue:, today:, column_name:, percentile:, column_age:
+    "This item is an outlier at #{label_days issue.board.cycletime.age(issue, today: today)} " \
+      "in the #{column_name.inspect} column. #{percentile}% of items on this board have left this " \
+      "column in #{label_days column_age} or less, so we cannot forecast when it will be done."
+  end
 end

data/lib/jirametrics/chart_base.rb

@@ -14,7 +14,7 @@ class ChartBase
   ].freeze
   attr_accessor :timezone_offset, :board_id, :all_boards, :date_range,
     :time_range, :data_quality, :holiday_dates, :settings, :issues, :file_system,
-    :atlassian_document_format, :x_axis_title, :y_axis_title, :fix_versions
+    :atlassian_document_format, :x_axis_title, :y_axis_title, :fix_versions, :color_palette
   attr_writer :aggregated_project
   attr_reader :canvas_width, :canvas_height
 
@@ -83,7 +83,7 @@ class ChartBase
   end
 
   def color_for type:
-    @chart_colors[type] ||= random_color
+    @chart_colors[type] ||= next_palette_color
   end
 
   # Defines label_days, label_hours, label_minutes and label_issues - each renders a pluralised count
@@ -259,6 +259,38 @@ class ChartBase
     @description_text
   end
 
+  # The nearest rank percentile: the smallest value with at least this percentage of the data at
+  # or below it. One implementation for the whole product, because three call sites used to
+  # compute this separately and two of them overshot by one whenever the rank landed exactly on a
+  # boundary, so the same percentile of the same data could read differently on two charts.
+  # Returns nil when there is nothing to measure.
+  def percentile_of values, percentile
+    return nil if values.empty?
+
+    sorted = values.sort
+    rank = (percentile / 100.0 * sorted.size).ceil
+    sorted[rank.clamp(1, sorted.size) - 1]
+  end
+
+  # "a and b" for two, "a, b and c" for more. Used when listing configured percentiles in prose.
+  def comma_and phrases
+    return phrases.join ' and ' if phrases.size <= 2
+
+    "#{phrases[0..-2].join ', '} and #{phrases.last}"
+  end
+
+  # 1st, 2nd, 3rd, 4th ... 11th, 12th, 13th ... 21st. Percentiles are the main caller and they
+  # range over 0..100, so blindly appending "th" would render "1th" and "22th".
+  def ordinal number
+    suffix =
+      if [11, 12, 13].include?(number % 100)
+        'th'
+      else
+        { 1 => 'st', 2 => 'nd', 3 => 'rd' }.fetch(number % 10, 'th')
+      end
+    "#{number}#{suffix}"
+  end
+
   # Convert a number like 1234567 into the string "1,234,567"
   def format_integer number
     number.to_s.reverse.scan(/.{1,3}/).join(',').reverse
@@ -324,9 +356,11 @@ class ChartBase
     end
   end
 
-  def random_color
-    @palette_index = (@palette_index || -1) + 1
-    OKABE_ITO_PALETTE[@palette_index % OKABE_ITO_PALETTE.size]
+  # A colour for something that needs telling apart, where no specific colour is wanted. If a
+  # specific colour matters, configure it instead. See ColorPalette for why this is not random and
+  # why it must not become random again.
+  def next_palette_color
+    (@color_palette ||= ColorPalette.default).next_color
   end
 
   def canvas width:, height:, responsive: true

data/lib/jirametrics/color_palette.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Hands out colours for things that need to be told apart but where no specific colour is wanted.
+# If a specific colour matters it should be configured, not obtained from here.
+#
+# Two properties matter and neither is obvious from the call site:
+#
+# 1. The colours have to stay distinguishable to people with colour vision deficiency. This started
+#    life as a genuinely random picker, which regularly produced pairs nobody could tell apart, so
+#    it is a curated set and must stay one. Do not "improve" it back into a generator.
+# 2. It returns CssVariable rather than a literal, so the colours follow the light and dark themes
+#    and can be overridden by a user's own stylesheet. Baked in hex can do neither.
+#
+# The number of slots is read from the CSS rather than declared here, so adding a colour is a CSS
+# edit and the count never becomes something the Ruby and the CSS have to agree on separately.
+class ColorPalette
+  PALETTE_VARIABLE = /--palette-color-(\d+)\s*:/
+
+  attr_reader :size
+
+  # For anything holding a chart on its own, outside a report run: tests, and any future standalone
+  # use. A report injects a shared instance so the whole page draws from one rotation, but nothing
+  # depends on that, because a caller who needs a SPECIFIC colour is supposed to configure it.
+  # A FRESH palette each call, not a shared singleton. The rotation is mutable state, so a memoised
+  # instance would leak position between charts and, worse, between test examples. Only the parsed
+  # stylesheet is cached, since that is the expensive part and it does not change.
+  def self.default
+    new css: shipped_css
+  end
+
+  def self.shipped_css
+    @shipped_css ||= File.read File.join(__dir__, 'html', 'index.css')
+  end
+
+  def initialize css:
+    @size = count_slots css
+    @index = -1
+  end
+
+  # The next slot, cycling back to the first once they have all been used.
+  def next_color
+    @index += 1
+    CssVariable["--palette-color-#{(@index % @size) + 1}"]
+  end
+
+  private
+
+  # Only the contiguous run from 1 counts. A theme block that overrides slot 2 is not a third slot,
+  # it is the cascade doing its job, so counting distinct numbers is right and counting occurrences
+  # would not be. A gap ends the run because the cycle would otherwise land on a slot that no rule
+  # defines, and an undefined variable resolves to nothing rather than to a colour.
+  def count_slots css
+    defined_slots = css.scan(PALETTE_VARIABLE).flatten.map(&:to_i).uniq
+    if defined_slots.empty?
+      raise 'The CSS defines no --palette-color-N variables, so there are no colours to hand out. ' \
+        'They are normally defined in the :root block of jirametrics/html/index.css.'
+    end
+
+    (1..).take_while { |slot| defined_slots.include? slot }.size
+  end
+end

data/lib/jirametrics/cumulative_flow_diagram.rb

@@ -116,7 +116,7 @@ class CumulativeFlowDiagram < ChartBase
 
     daily_marginals = marginal_band_heights(daily_counts, column_count)
 
-    border_colors = active_rules.map { |rules| rules.color || random_color }
+    border_colors = active_rules.map { |rules| rules.color || next_palette_color }
 
     fill_colors = active_rules.zip(border_colors).map { |rules, border| fill_color_for(rules, border) }
 
@@ -206,14 +206,17 @@ class CumulativeFlowDiagram < ChartBase
     )
   end
 
-  def hex_to_rgba hex, alpha
-    r, g, b = hex.delete_prefix('#').scan(/../).map { |c| c.to_i(16) }
-    "rgba(#{r}, #{g}, #{b}, #{alpha})"
+  # The fill is a translucent version of the border colour. Border colours may now be CssVariable
+  # rather than a literal, and Ruby cannot resolve one, so the alpha is applied in the browser.
+  def translucent border, alpha
+    RawJavascript.new "withAlpha(#{border.to_json}, #{alpha})"
   end
 
+  # A colour the user set explicitly is used as given. Anything else, including a palette colour,
+  # gets the translucent treatment.
   def fill_color_for rules, border
-    if rules.color.nil? || rules.color.match?(/\A#[0-9a-fA-F]{6}\z/)
-      hex_to_rgba(border, 0.35)
+    if rules.color.nil? || rules.color.is_a?(CssVariable) || rules.color.match?(/\A#[0-9a-fA-F]{6}\z/)
+      translucent border, 0.35
     else
       rules.color
     end

data/lib/jirametrics/cycletime_scatterplot.rb

@@ -14,14 +14,8 @@ class CycletimeScatterplot < TimeBasedScatterplot
         This chart shows only completed work and indicates both what day it completed as well as
         how many days it took to get done. Hovering over a dot will show you the ID of the work item.
       </div>
-      <div class="p">
-        The #{color_block '--cycletime-scatterplot-overall-trendline-color'} line indicates the 85th
-        percentile (<%= overall_percent_line %> days). 85% of all
-        items on this chart fall on or below the line and the remaining 15% are above the line. 85%
-        is a reasonable proxy for "most" so that we can say that based on this data set, we can
-        predict that most work of this type will complete in <%= overall_percent_line %> days or
-        less. The other lines reflect the 85% line for that respective type of work.
-      </div>
+      <%= percentile_description %>
+      <%= trend_line_description %>
       #{describe_non_working_days}
     HTML
     @x_axis_title = 'Date completed'
@@ -65,4 +59,69 @@ class CycletimeScatterplot < TimeBasedScatterplot
 
   # Kept for backwards compatibility with existing callers and specs
   alias data_for_issue data_for_item
+
+  # The number that the "reasonable proxy for most" claim is actually about. That claim is only
+  # defensible near this value: at the median half the work runs longer, and at the 98th you are
+  # describing the worst case, not the typical one. So the sentence appears when this percentile
+  # is on the chart and is silently dropped when it is not, rather than being reworded into
+  # something that sounds authoritative and is wrong.
+  PROXY_FOR_MOST_PERCENTILE = 85
+
+  # The prose follows the configuration, so it has to read well for one percentile or several,
+  # and say nothing at all for none. Values come from percentage_lines because run has already
+  # computed them, and because this string is not run through ERB a second time.
+  def percentile_description
+    overall_lines = percentage_lines.select { |line| line[:dataset_index].nil? }
+    return '' if overall_lines.empty?
+
+    sentences = [
+      percentile_summary_sentence(overall_lines),
+      proxy_for_most_sentence(overall_lines),
+      per_type_sentence(overall_lines)
+    ].compact
+    <<-HTML
+      <div class="p">
+        #{sentences.join ' '}
+      </div>
+    HTML
+  end
+
+  # Mechanical and true whatever the configured percentiles are. Singular phrasing is preserved
+  # word for word from the original so the default chart reads exactly as it always has.
+  def percentile_summary_sentence lines
+    swatch = color_block '--cycletime-scatterplot-overall-trendline-color'
+    if lines.size == 1
+      percentile = lines.first[:percentile]
+      "The #{swatch} line indicates the #{ordinal percentile} percentile " \
+        "(#{lines.first[:value]} days). #{percentile}% of all items on this chart fall on or " \
+        "below the line and the remaining #{100 - percentile}% are above the line."
+    else
+      # No values inline here. With several lines the sentence turns into a wall of parentheses,
+      # and each value is already on the line's hover label and in that group's legend entry.
+      described = lines.collect { |line| ordinal line[:percentile] }
+      "The #{swatch} lines indicate the #{comma_and described} percentiles of all items on " \
+        'this chart. For each line, that percentage of items fall on or below it and the rest ' \
+        'are above.'
+    end
+  end
+
+  # Only emitted when 85 is actually among the configured percentiles. See PROXY_FOR_MOST_PERCENTILE.
+  def proxy_for_most_sentence lines
+    line = lines.find { |candidate| candidate[:percentile] == PROXY_FOR_MOST_PERCENTILE }
+    return nil unless line
+
+    "#{PROXY_FOR_MOST_PERCENTILE}% is a " \
+      '<a href="https://jirametrics.org/faq/#why-85">reasonable proxy</a> for "most" so that we ' \
+      'can say that based on this data set, we can predict that most work of this type will ' \
+      "complete in #{line[:value]} days or less."
+  end
+
+  def per_type_sentence lines
+    if lines.size == 1
+      "The other lines reflect the #{lines.first[:percentile]}% line for that respective type of work."
+    else
+      'Each type of work also gets its own lines in its own colour, at whichever percentiles ' \
+        'were configured for that type. Hover any line to see which one it is and its value.'
+    end
+  end
 end

data/lib/jirametrics/daily_wip_chart.rb

@@ -150,7 +150,7 @@ class DailyWipChart < ChartBase
   end
 
   def background_color_for grouping_rule
-    color = grouping_rule.color || random_color
+    color = grouping_rule.color || next_palette_color
     return color unless grouping_rule.highlight
 
     RawJavascript.new("createDiagonalPattern(#{color.to_json})")

data/lib/jirametrics/dependency_chart.rb

@@ -119,7 +119,7 @@ class DependencyChart < ChartBase
       'Defect' => '#ffdab9',
       'Epic' => '#fafad2',
       'Spike' => '#DDA0DD' # light purple
-    }[type] ||= random_color
+    }[type] ||= next_palette_color
   end
 
   def build_dot_graph