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?, #chart_format, #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, #format_integer, #format_status, #header_text, #holidays, #html_directory, #icon_span, #link_to_issue, #next_id, #next_palette_color, #non_working_day?, #normalize_annotation_datetime, #not_visible_icon, #not_visible_text, #ordinal, #percentile_of, #render, #render_axis_title, #render_top_text, #resolve_status, #stagger_label_positions, #status_category_color, #to_human_readable, #working_days_annotation, #wrap_and_render

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
 
# 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'
  # 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 



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

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 



426
427
428
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 426

def age_cutoff days
  @age_cutoff = days
end

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



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
203
204
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 176

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 



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

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 



383
384
385
386
387
388
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 383

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 



135
136
137
138
139
140
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 135

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.



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

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 



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

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 



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
258
259
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 231

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 



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

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 



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
173
174
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 142

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 



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

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 



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

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.



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

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 



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

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.



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

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.



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
371
372
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 343

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.



376
377
378
379
380
381
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 376

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.



334
335
336
337
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 334

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.



393
394
395
396
397
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 393

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 



51
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
77
78
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 51

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

  if aging_issues.empty?
    @description_text = '<p>There is no aging work</p>'
    return render_top_text(binding)
  end

  wrap_and_render(binding, __FILE__)
end

#select_aging_issues(issues:) ⇒ Object 



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

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 



110
111
112
113
114
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 110

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 



311
312
313
314
315
 
# File 'lib/jirametrics/aging_work_bar_chart.rb', line 311

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 



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

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