Class: AgingWorkBarChart

Inherits:
ChartBase show all
Includes:
PercentileValidation
Defined in:
lib/jirametrics/aging_work_bar_chart.rb

Constant Summary

Constants inherited from ChartBase

ChartBase::LABEL_POSITIONS, ChartBase::OKABE_ITO_PALETTE

Instance Attribute Summary

Attributes inherited from ChartBase

#aggregated_project, #all_boards, #atlassian_document_format, #board_id, #canvas_height, #canvas_width, #color_palette, #data_quality, #date_range, #file_system, #fix_versions, #holiday_dates, #issues, #settings, #time_range, #timezone_offset, #x_axis_title, #y_axis_title

Instance Method Summary collapse

Methods included from PercentileValidation

validate_percentile, validate_percentiles

Methods inherited from ChartBase

#aggregated_project?, #before_run, #call_before_run, #canvas, #canvas_responsive?, #collapsible_issues_panel, #color_block, #color_for, #comma_and, #completed_issues_in_range, #current_board, #cycletime, #cycletime_for_issue, #daily_chart_dataset, #date_annotation, #describe_non_working_days, #description_text, #expand_template, #expanded_header_text, #format_integer, #format_status, #header_text, #holidays, #html_directory, #icon_span, #link_to_issue, #next_id, #next_palette_color, #no_data_text, #non_working_day?, #normalize_annotation_datetime, #not_visible_icon, #not_visible_text, #ordinal, #percentile_of, #render, #render_axis_title, #render_binding, #render_header, #render_no_data, #render_top_text, #resolve_status, #stagger_label_positions, #status_category_color, #to_human_readable, #working_days_annotation, #wrap_and_render

Methods included from ChartFormat

#chart_format

Constructor Details

#initialize(block) ⇒ AgingWorkBarChart

Returns a new instance of AgingWorkBarChart.



10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 10

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'
  no_data_text '<%= render_header %><p>There is no aging work</p>'
  # 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
    <div class="p">
      This chart shows all active (started but not completed) work, ordered from oldest at the top to
      newest at the bottom.
    </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
        status category, which will be one of #{color_block '--status-category-todo-color'} To Do,
        #{color_block '--status-category-inprogress-color'} In Progress,
        or #{color_block '--status-category-done-color'} Done</li>
        <li>Activity: This bar indicates #{color_block '--blocked-color'} blocked
        or #{color_block '--stalled-color'} stalled.</li>
        <li>Priority: This shows the priority over time. If one of these priorities is considered expedited
        then it will be drawn with diagonal lines.</li>
        <% if aggregated_project? || current_board.scrum? %>
          <li>Sprints: The sprints that the issue was in.</li>
        <% end %>
      </ol>
    </div>
    <%= percentile_description %>
    #{describe_non_working_days}
  HTML

  # Because this one will size itself as needed, we start with a smaller default size
  @canvas_height = 80

  instance_eval(&block)
end

Instance Method Details

#adjust_time_date_ranges_to_start_from_earliest_issue_start(aging_issues) ⇒ Object 



78
79
80
81
82
83
84
85
86
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 78

def adjust_time_date_ranges_to_start_from_earliest_issue_start aging_issues
  earliest_start_time = aging_issues.collect do |issue|
    issue.started_stopped_times.first
  end.min
  return if earliest_start_time.nil? || earliest_start_time >= @time_range.begin

  @time_range = earliest_start_time..@time_range.end
  @date_range = @time_range.begin.to_date..@time_range.end.to_date
end

#age_cutoff(days) ⇒ Object 



424
425
426
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 424

def age_cutoff days
  @age_cutoff = days
end

#bar_chart_range_to_data_set(y_value:, ranges:, stack:, issue_start_time:) ⇒ Object 



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 174

def bar_chart_range_to_data_set y_value:, ranges:, stack:, issue_start_time:
  ranges.filter_map do |bar_chart_range|
    next if bar_chart_range.stop < issue_start_time

    background_color = bar_chart_range.color
    if bar_chart_range.highlight
      background_color = RawJavascript.new("createDiagonalPattern(#{background_color.to_json})")
    end

    {
      type: 'bar',
      data: [{
        x: [chart_format([bar_chart_range.start, issue_start_time].max), chart_format(bar_chart_range.stop)],
        y: y_value,
        title: bar_chart_range.title
      }],
      backgroundColor: background_color,
      borderColor: CssVariable['--aging-work-bar-chart-separator-color'],
      borderWidth: {
         top: 0,
         right: 1,
         bottom: 0,
         left: 0
      },
      stacked: true,
      stack: stack
    }
  end
end

#blocked_stalled_range(starting_change, change) ⇒ Object 



220
221
222
223
224
225
226
227
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 220

def blocked_stalled_range starting_change, change
  color = '--blocked-color'
  color = '--stalled-color' if starting_change.stalled?

  BarChartRange.new(
    start: starting_change.time, stop: change.time, color: CssVariable[color], title: starting_change.reasons
  )
end

#calculate_percent_line(percentage: 85) ⇒ Object 



381
382
383
384
385
386
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 381

def calculate_percent_line percentage: 85
  percentile_of(
    completed_issues_in_range.filter_map { |issue| issue.board.cycletime.cycletime(issue) },
    percentage
  )
end

#clip_ranges_to_start_time(ranges:, issue_start_time:) ⇒ Object 



133
134
135
136
137
138
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 133

def clip_ranges_to_start_time ranges:, issue_start_time:
  return if issue_start_time.nil?

  ranges.each { |range| range.start = issue_start_time if range.start < issue_start_time }
  ranges.reject! { |range| range.start >= range.stop }
end

#close_removed_sprints(change, open_sprints, results) ⇒ Object

For each sprint this change leaves, close its open range. The range stops when the issue left, or when the sprint completed if that came first.



283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 283

def close_removed_sprints change, open_sprints, results
  removed_sprint_ids = change.old_value_id - change.value_id
  removed_sprint_ids.each do |id|
    data = open_sprints.delete(id)
    next unless data

    completed = data[:sprint].completed_time
    stop = completed ? [change.time, completed].min : change.time
    results << sprint_range(data, stop)
  end
end

#collect_blocked_stalled_ranges(issue:, issue_start_time:) ⇒ Object 



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 204

def collect_blocked_stalled_ranges issue:, issue_start_time:
  results = []
  starting_change = nil

  issue.blocked_stalled_changes(end_time: time_range.end).each do |change|
    if starting_change.nil? || starting_change.active?
      starting_change = change
      next
    end

    results << blocked_stalled_range(starting_change, change) if change.time >= issue_start_time
    starting_change = change
  end
  results
end

#collect_priority_ranges(issue:) ⇒ Object 



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 229

def collect_priority_ranges issue:
  expedited_priority_names = settings['expedited_priority_names']

  previous_change = nil
  results = []

  issue.changes.each do |change|
    next unless change.priority?

    if previous_change.nil?
      previous_change = change
      next
    end

    results << create_range_for_priority(
      previous_change: previous_change, stop_time: change.time,
      expedited_priority_names: expedited_priority_names
    )
    previous_change = change
  end

  if previous_change
    results << create_range_for_priority(
      previous_change: previous_change, stop_time: time_range.end,
      expedited_priority_names: expedited_priority_names
    )
  end
  results
end

#collect_sprint_ranges(issue:) ⇒ Object 



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 259

def collect_sprint_ranges issue:
  results = []
  open_sprints = {}

  issue.changes.each do |change|
    next unless change.sprint?

    close_removed_sprints(change, open_sprints, results)
    open_added_sprints(change, issue, open_sprints)
  end

  # Anything still open at the end runs to the sprint's completion, or the end of the range if it's
  # still active.
  open_sprints.each_value do |data|
    next if data[:sprint].future?

    results << sprint_range(data, data[:sprint].completed_time || time_range.end)
  end

  results
end

#collect_status_ranges(issue:, now:) ⇒ Object 



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 140

def collect_status_ranges issue:, now:
  ranges = []
  issue_started_time = issue.started_stopped_times.first
  previous_start = nil
  previous_status = nil
  issue.status_changes.each do |change|
    new_status = issue.find_or_create_status id: change.value_id, name: change.value
    if previous_start.nil?
      previous_start = change.time
      previous_status = new_status
      next
    end

    previous_start = issue_started_time if issue_started_time > previous_start

    ranges << BarChartRange.new(
      start: previous_start,
      stop: change.time,
      color: status_category_color(previous_status),
      title: previous_status.to_s
    )
    previous_start = change.time
    previous_status = new_status
  end

  ranges << BarChartRange.new(
    start: previous_start,
    stop: now,
    color: status_category_color(previous_status),
    title: previous_status.to_s
  )
  ranges
end

#create_range_for_priority(previous_change:, stop_time:, expedited_priority_names:) ⇒ Object 



315
316
317
318
319
320
321
322
323
324
325
326
327
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 315

def create_range_for_priority previous_change:, stop_time:, expedited_priority_names:
  expedited = expedited_priority_names.include?(previous_change.value)
  title = "Priority: #{previous_change.value}"
  title << ' (expedited)' if expedited

  BarChartRange.new(
    start: previous_change.time,
    stop: stop_time,
    color: priority_color(previous_change.value),
    title: title,
    highlight: expedited
  )
end

#data_sets_for_one_issue(issue:, today:) ⇒ Object 



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 88

def data_sets_for_one_issue issue:, today:
  cycletime = issue.board.cycletime
  issue_start_time = cycletime.started_stopped_times(issue).first
  end_of_today = Time.parse("#{today}T23:59:59#{@timezone_offset}")

  bar_data = [
    ['status', collect_status_ranges(issue: issue, now: end_of_today)],
    ['blocked', collect_blocked_stalled_ranges(issue: issue, issue_start_time: issue_start_time)],
    ['priority', collect_priority_ranges(issue: issue)]
  ]
  bar_data << ['sprints', collect_sprint_ranges(issue: issue)] if aggregated_project? || current_board.scrum?

  bar_data.each { |entry| clip_ranges_to_start_time(ranges: entry.last, issue_start_time: issue_start_time) }

  issue_label = "[#{label_days cycletime.age(issue, today: today)}] #{issue.key}: #{issue.summary}"[0..60]
  bar_data.collect do |stack, ranges|
    bar_chart_range_to_data_set y_value: issue_label, ranges: ranges, stack: stack, issue_start_time: issue_start_time
  end
end

#defined_priority_colors ⇒ Object

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.



414
415
416
417
418
419
420
421
422
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 414

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

#grow_chart_height_if_too_many_issues(aging_issue_count:) ⇒ Object 



124
125
126
127
128
129
130
131
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 124

def grow_chart_height_if_too_many_issues aging_issue_count:
  px_per_bar = 10
  bars_per_issue = 3
  bars_per_issue += 1 if aggregated_project? || current_board.scrum?

  preferred_height = aging_issue_count * px_per_bar * bars_per_issue
  @canvas_height = preferred_height if @canvas_height.nil? || @canvas_height < preferred_height
end

#open_added_sprints(change, issue, open_sprints) ⇒ Object

For each sprint this change joins (that exists and has already started), open a range. It starts when the issue joined, or when the sprint began if the issue was added beforehand.



297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 297

def open_added_sprints change, issue, open_sprints
  added_sprint_ids = change.value_id - change.old_value_id
  added_sprint_ids.each do |id|
    sprint = issue.board.sprints.find { |s| s.id == id }
    next unless sprint
    next if sprint.future?

    start_time = [sprint.start_time, change.time].max
    open_sprints[id] = { start_time: start_time, sprint: sprint }
  end
end

#percentile_description ⇒ Object

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.



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 341

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

#percentile_lines ⇒ Object

Returns [[percentile, days], ...] for the configured percentiles, dropping any that have no value because nothing completed in range.



374
375
376
377
378
379
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 374

def percentile_lines
  percentiles.filter_map do |percentile|
    days = calculate_percent_line percentage: percentile
    [percentile, days] unless days.nil?
  end
end

#percentiles(list = nil) ⇒ Object

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.



332
333
334
335
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 332

def percentiles list = nil
  @percentiles = validate_percentiles(list) unless list.nil?
  @percentiles
end

#priority_color(priority_name) ⇒ Object

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.



391
392
393
394
395
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 391

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

#run ⇒ Object 



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 52

def run
  aging_issues = select_aging_issues issues: @issues
  adjust_time_date_ranges_to_start_from_earliest_issue_start(aging_issues)

  today = date_range.end
  sort_by_age! issues: aging_issues, today: today

  grow_chart_height_if_too_many_issues aging_issue_count: aging_issues.size

  data_sets = aging_issues
    .collect { |issue| data_sets_for_one_issue issue: issue, today: today }
    .flatten
    .compact

  # 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

  return render_no_data if aging_issues.empty?

  wrap_and_render(binding, __FILE__)
end

#select_aging_issues(issues:) ⇒ Object 



114
115
116
117
118
119
120
121
122
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 114

def select_aging_issues issues:
  issues.select do |issue|
    cycletime = issue.board.cycletime
    next false unless cycletime.in_progress?(issue)

    age = cycletime.age(issue, today: date_range.end)
    !(@age_cutoff && @age_cutoff >= age)
  end
end

#sort_by_age!(issues:, today:) ⇒ Object 



108
109
110
111
112
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 108

def sort_by_age! issues:, today:
  issues.sort! do |a, b|
    b.board.cycletime.age(b, today: today) <=> a.board.cycletime.age(a, today: today)
  end
end

#sprint_range(data, stop) ⇒ Object 



309
310
311
312
313
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 309

def sprint_range data, stop
  BarChartRange.new(
    start: data[:start_time], stop: stop, color: CssVariable['--sprint-color'], title: data[:sprint].name
  )
end

#warn_about_unknown_priority(priority_name, key) ⇒ Object 



397
398
399
400
401
402
403
404
405
406
407
408
409
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 397

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