Class: DataQualityReport

Inherits:
ChartBase show all
Defined in:
lib/jirametrics/data_quality_report.rb

Defined Under Namespace

Classes: Entry

Constant Summary

Constants inherited from ChartBase

ChartBase::LABEL_POSITIONS, ChartBase::OKABE_ITO_PALETTE

Instance Attribute Summary collapse

Attributes inherited from ChartBase

#aggregated_project, #all_boards, #atlassian_document_format, #canvas_height, #canvas_width, #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 inherited from ChartBase

#aggregated_project?, #before_run, #call_before_run, #canvas, #canvas_responsive?, #chart_format, #collapsible_issues_panel, #color_block, #color_for, #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, #non_working_day?, #normalize_annotation_datetime, #not_visible_icon, #not_visible_text, #random_color, #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(discarded_changes_data) ⇒ DataQualityReport

Returns a new instance of DataQualityReport.



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/jirametrics/data_quality_report.rb', line 22

def initialize discarded_changes_data
  super()

  @discarded_changes_data = discarded_changes_data

  header_text 'Data Quality Report'
  description_text <<-HTML
    <p>
      We have a tendency to assume that anything we see in a chart is 100% accurate, although that's
      not always true. The accuracy of a chart depends both on how good the underlying data was and
      on how much of that data actually made it into the chart.
    </p>
    <p>
      The items highlighted below are not necessarily bad data. Some are genuine contradictions worth
      fixing in Jira, such as an item finishing before it started. But many are simply places where the
      way your team actually works bumps up against the simplified start-to-finish model this tool uses
      to compute flow metrics. Those aren't mistakes; we flag them so you can read the charts with the
      right context, not because anyone did anything wrong.
    </p>
  HTML
end

Instance Attribute Details

#board_id ⇒ Object

Returns the value of attribute board_id.



5
6
7
 
# File 'lib/jirametrics/data_quality_report.rb', line 5

def board_id
  @board_id
end

#discarded_changes_data ⇒ Object (readonly)

Both for testing purposes only



4
5
6
 
# File 'lib/jirametrics/data_quality_report.rb', line 4

def discarded_changes_data
  @discarded_changes_data
end

#entries ⇒ Object (readonly)

Both for testing purposes only



4
5
6
 
# File 'lib/jirametrics/data_quality_report.rb', line 4

def entries
  @entries
end

Instance Method Details

#column_index_for(board, change) ⇒ Object 



193
194
195
 
# File 'lib/jirametrics/data_quality_report.rb', line 193

def column_index_for board, change
  board.visible_columns.find_index { |column| column.status_ids.include? change.value_id }
end

#entries_with_problems ⇒ Object 



124
125
126
 
# File 'lib/jirametrics/data_quality_report.rb', line 124

def entries_with_problems
  @entries.reject { |entry| entry.problems.empty? }
end

#incomplete_subtask_label(subtask, issue_stopped) ⇒ Object

The label for one subtask that isn't finished when its parent is done, or nil if it is fine.



346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/jirametrics/data_quality_report.rb', line 346

def incomplete_subtask_label subtask, issue_stopped
  subtask_started, subtask_stopped = subtask.started_stopped_times

  if !subtask_started && !subtask_stopped
    "#{subtask_label subtask} (Not even started)"
  elsif !subtask_stopped
    "#{subtask_label subtask} (Still not done)"
  elsif subtask_stopped > issue_stopped
    "#{subtask_label subtask} (Closed #{time_as_english issue_stopped, subtask_stopped} later)"
  end
end

#initialize_entries ⇒ Object 



128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/jirametrics/data_quality_report.rb', line 128

def initialize_entries
  @entries = @issues.filter_map do |issue|
    started, stopped = issue.started_stopped_times
    next if stopped && stopped < time_range.begin
    next if started && started > time_range.end

    Entry.new started: started, stopped: stopped, issue: issue
  end

  @entries.sort_by! { |entry| entry.issue.key_as_i }
end

#problems_for(key) ⇒ Object 



90
91
92
93
94
95
96
97
98
 
# File 'lib/jirametrics/data_quality_report.rb', line 90

def problems_for key
  result = []
  @entries.each do |entry|
    entry.problems.each do |problem_key, detail|
      result << [entry.issue, detail, key] if problem_key == key
    end
  end
  result
end

#render_backwards_through_status_categories(problems) ⇒ Object 



424
425
426
427
428
429
430
 
# File 'lib/jirametrics/data_quality_report.rb', line 424

def render_backwards_through_status_categories problems
  <<-HTML
    #{label_issues problems.size} moved backwards across the board, <b>crossing status categories</b>.
    This will almost certainly have impacted timings as the end times are often taken at status category
    boundaries. You should assume that any timing measurements for this item are wrong.
  HTML
end

#render_backwords_through_statuses(problems) ⇒ Object 



432
433
434
435
436
437
438
 
# File 'lib/jirametrics/data_quality_report.rb', line 432

def render_backwords_through_statuses problems
  <<-HTML
    #{label_issues problems.size} moved backwards across the board. Depending where we have set the
    start and end points, this may give us incorrect timing data. Note that these items did not cross
    a status category and may not have affected metrics.
  HTML
end

#render_completed_but_not_started(problems) ⇒ Object 



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/jirametrics/data_quality_report.rb', line 401

def render_completed_but_not_started problems
  percentage_work_included = ((issues.size - problems.size).to_f / issues.size * 100).to_i
  html = <<-HTML
    #{label_issues problems.size} were discarded from all charts using cycletime (scatterplot, histogram, etc)
    as we couldn't determine when they started.
  HTML
  if percentage_work_included < 85
    html << <<-HTML
      Consider whether looking at only #{percentage_work_included}% of the total data points is enough
      to come to any reasonable conclusions. See <a href="https://unconsciousagile.com/2024/11/19/survivor-bias.html">
      Survivor Bias</a>.
    HTML
  end
  html
end

#render_created_in_wrong_status(problems) ⇒ Object 



451
452
453
454
455
456
457
 
# File 'lib/jirametrics/data_quality_report.rb', line 451

def render_created_in_wrong_status problems
  <<-HTML
    #{label_issues problems.size} were created in a status that is not considered to be some varient
    of To Do. Most likely this means that the issue was created from one of the columns on the board,
    rather than in the backlog. Why Jira allows this is still a mystery.
  HTML
end

#render_discarded_changes(problems) ⇒ Object 



393
394
395
396
397
398
399
 
# File 'lib/jirametrics/data_quality_report.rb', line 393

def render_discarded_changes problems
  <<-HTML
    #{label_issues problems.size} have had information discarded. This configuration is set
    to "reset the clock" if an item is moved back to the backlog after it's been started. This hides important
    information and makes the data less accurate. <b>Moving items back to the backlog is strongly discouraged.</b>
  HTML
end

#render_incomplete_subtasks_when_issue_done(problems) ⇒ Object 



475
476
477
478
479
 
# File 'lib/jirametrics/data_quality_report.rb', line 475

def render_incomplete_subtasks_when_issue_done problems
  <<-HTML
    #{label_issues problems.size} were marked as done while subtasks were still not done.
  HTML
end

#render_issue_not_started_but_subtasks_have(problems) ⇒ Object 



467
468
469
470
471
472
473
 
# File 'lib/jirametrics/data_quality_report.rb', line 467

def render_issue_not_started_but_subtasks_have problems
  <<-HTML
    #{label_issues problems.size} still showing 'not started' while sub-tasks underneath them have
    started. This is almost always a mistake; if we're working on subtasks, the top level item should
    also have started.
  HTML
end

#render_issue_not_visible_on_board(problems) ⇒ Object 



440
441
442
443
444
445
446
447
448
449
 
# File 'lib/jirametrics/data_quality_report.rb', line 440

def render_issue_not_visible_on_board problems
  unique_issue_count = problems.map(&:first).uniq.size
  <<-HTML
    #{problems.size} #{'time'.then { |w| problems.size == 1 ? w : "#{w}s" }} across #{label_issues unique_issue_count},
    an item was not visible on the board. This may impact
    timings as the work was likely to have been forgotten if it wasn't visible. An issue can be not visible
    for two reasons: the issue was in a status that is not mapped to any visible column on the board
    (look in "unmapped statuses" on your board), or for scrum boards, the issue was not in an active sprint.
  HTML
end

#render_issue_on_multiple_boards(problems) ⇒ Object 



481
482
483
484
485
486
 
# File 'lib/jirametrics/data_quality_report.rb', line 481

def render_issue_on_multiple_boards problems
  <<-HTML
    For #{label_issues problems.size}, we have an issue that shows up on more than one board. This
    could result in more data points showing up on a chart then there really should be.
  HTML
end

#render_items_blocked_on_closed_tickets(problems) ⇒ Object 



488
489
490
491
492
493
 
# File 'lib/jirametrics/data_quality_report.rb', line 488

def render_items_blocked_on_closed_tickets problems
  <<-HTML
    For #{label_issues problems.size}, the issue is identified as being blocked by another issue. Yet,
    that other issue is already completed so, by definition, it can't still be blocking.
  HTML
end

#render_problem_type(problem_key) ⇒ Object 



100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/jirametrics/data_quality_report.rb', line 100

def render_problem_type problem_key
  problems = problems_for problem_key
  return '' if problems.empty?

  <<-HTML
    <li>
      #{__send__ :"render_#{problem_key}", problems}
      #{collapsible_issues_panel problems}
    </li>
  HTML
end

#render_status_changes_after_done(problems) ⇒ Object 



417
418
419
420
421
422
 
# File 'lib/jirametrics/data_quality_report.rb', line 417

def render_status_changes_after_done problems
  <<-HTML
    #{label_issues problems.size} had a status change after being identified as done. We should question
    whether they were really done at that point or if we stopped the clock too early.
  HTML
end

#render_stopped_before_started(problems) ⇒ Object 



459
460
461
462
463
464
465
 
# File 'lib/jirametrics/data_quality_report.rb', line 459

def render_stopped_before_started problems
  <<-HTML
    #{label_issues problems.size} were stopped before they were started and this will play havoc with
    any cycletime or WIP calculations. The most common case for this is when an item gets closed and
    then moved back into an in-progress status.
  HTML
end

#report_backwards_movement(entry:, change:, board:) ⇒ Object 



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/jirametrics/data_quality_report.rb', line 212

def report_backwards_movement entry:, change:, board:
  new_category = board.possible_statuses.find_by_id(change.value_id).category.name
  old_category = board.possible_statuses.find_by_id(change.old_value_id).category.name

  if new_category == old_category
    entry.report(
      problem_key: :backwords_through_statuses,
      detail: "Moved from #{format_status change, use_old_status: true, board: board}" \
        " to #{format_status change, board: board}" \
        " on #{change.time.to_date}"
    )
  else
    entry.report(
      problem_key: :backwards_through_status_categories,
      detail: "Moved from #{format_status change, use_old_status: true, board: board}" \
        " to #{format_status change, board: board}" \
        " on #{change.time.to_date}," \
        " crossing from category #{format_status change, use_old_status: true, board: board, is_category: true}" \
        " to #{format_status change, board: board, is_category: true}."
    )
  end
end

#report_status_not_on_board(entry:, change:, board:, backlog_statuses:) ⇒ Object 



197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/jirametrics/data_quality_report.rb', line 197

def report_status_not_on_board entry:, change:, board:, backlog_statuses:
  # If it's a backlog status then ignore it. Not supposed to be visible.
  return if board.backlog_statuses.include?(board.possible_statuses.find_by_id(change.value_id))

  detail = "Status #{format_status change, board: board} is not on the board"
  if board.possible_statuses.find_by_id(change.value_id).nil?
    detail = "Status #{format_status change, board: board} cannot be found at all. Was it deleted?"
  end

  # If it's been moved back to backlog then it's on a different report. Ignore it here.
  detail = nil if backlog_statuses.any? { |s| s.name == change.value }

  entry.report(problem_key: :issue_not_visible_on_board, detail: detail) unless detail.nil?
end

#run ⇒ Object 



44
45
46
47
48
49
50
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
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/jirametrics/data_quality_report.rb', line 44

def run
  initialize_entries

  @entries.each do |entry|
    board = entry.issue.board
    backlog_statuses = board.backlog_statuses

    scan_for_completed_issues_without_a_start_time entry: entry
    scan_for_status_change_after_done entry: entry
    scan_for_backwards_movement entry: entry, backlog_statuses: backlog_statuses
    scan_for_issue_not_in_active_sprint entry: entry
    scan_for_issues_not_created_in_a_backlog_status entry: entry, backlog_statuses: backlog_statuses
    scan_for_stopped_before_started entry: entry
    scan_for_issues_not_started_with_subtasks_that_have entry: entry
    scan_for_incomplete_subtasks_when_issue_done entry: entry
    scan_for_discarded_data entry: entry
    scan_for_items_blocked_on_closed_tickets entry: entry
  end

  scan_for_issues_on_multiple_boards entries: @entries

  entries_with_problems = entries_with_problems()
  return '' if entries_with_problems.empty?

  caller_binding = binding
  result = +''
  result << render_top_text(caller_binding)

  result << '<ul class="quality_report">'
  result << render_problem_type(:discarded_changes)
  result << render_problem_type(:completed_but_not_started)
  result << render_problem_type(:status_changes_after_done)
  result << render_problem_type(:backwards_through_status_categories)
  result << render_problem_type(:backwords_through_statuses)
  result << render_problem_type(:issue_not_visible_on_board)
  result << render_problem_type(:created_in_wrong_status)
  result << render_problem_type(:stopped_before_started)
  result << render_problem_type(:issue_not_started_but_subtasks_have)
  result << render_problem_type(:incomplete_subtasks_when_issue_done)
  result << render_problem_type(:issue_on_multiple_boards)
  result << render_problem_type(:items_blocked_on_closed_tickets)
  result << '</ul>'

  result
end

#scan_for_backwards_movement(entry:, backlog_statuses:) ⇒ Object 



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/jirametrics/data_quality_report.rb', line 174

def scan_for_backwards_movement entry:, backlog_statuses:
  # Moving backwards through statuses is bad. Moving backwards through status categories is almost always worse.
  last_index = -1
  entry.issue.changes.each do |change|
    next unless change.status?

    board = entry.issue.board
    index = column_index_for(board, change)
    if index.nil?
      report_status_not_on_board(entry: entry, change: change, board: board, backlog_statuses: backlog_statuses)
    elsif change.old_value.nil?
      # A move onto the board with no prior status has nothing to compare against.
    elsif index < last_index
      report_backwards_movement(entry: entry, change: change, board: board)
    end
    last_index = index || -1
  end
end

#scan_for_completed_issues_without_a_start_time(entry:) ⇒ Object 



140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/jirametrics/data_quality_report.rb', line 140

def scan_for_completed_issues_without_a_start_time entry:
  return unless entry.stopped && entry.started.nil?

  status_names = entry.issue.status_changes.filter_map do |change|
    format_status change, board: entry.issue.board
  end

  entry.report(
    problem_key: :completed_but_not_started,
    detail: "Status changes: #{status_names.join ' → '}"
  )
end

#scan_for_discarded_data(entry:) ⇒ Object 



358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
 
# File 'lib/jirametrics/data_quality_report.rb', line 358

def scan_for_discarded_data entry:
  hash = @discarded_changes_data&.find { |a| a[:issue] == entry.issue }
  return if hash.nil?

  old_start_time = hash[:original_start_time]
  cutoff_time = hash[:cutoff_time]

  old_start_date = old_start_time.to_date
  cutoff_date = cutoff_time.to_date

  days_ignored = (cutoff_date - old_start_date).to_i + 1
  message = "Started: #{old_start_date}, Discarded: #{cutoff_date}, Ignored: #{label_days days_ignored}"

  # If days_ignored is zero then we don't really care as it won't affect any of the calculations.
  return if days_ignored == 1

  entry.report(
    problem_key: :discarded_changes,
    detail: message
  )
end

#scan_for_incomplete_subtasks_when_issue_done(entry:) ⇒ Object 



333
334
335
336
337
338
339
340
341
342
343
 
# File 'lib/jirametrics/data_quality_report.rb', line 333

def scan_for_incomplete_subtasks_when_issue_done entry:
  return unless entry.stopped

  subtask_labels = entry.issue.subtasks.filter_map { |subtask| incomplete_subtask_label subtask, entry.stopped }
  return if subtask_labels.empty?

  entry.report(
    problem_key: :incomplete_subtasks_when_issue_done,
    detail: subtask_labels.join('<br />')
  )
end

#scan_for_issue_never_visible_on_board(entry:) ⇒ Object 



243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/jirametrics/data_quality_report.rb', line 243

def scan_for_issue_never_visible_on_board entry:
  issue = entry.issue
  ever_visible = issue.changes.any? do |change|
    next unless change.status?

    issue.board.visible_columns.any? { |col| col.status_ids.include?(change.value_id) }
  end
  return if ever_visible

  entry.report(
    problem_key: :issue_not_visible_on_board,
    detail: 'Issue has never been in a status mapped to a visible column on the board'
  )
end

#scan_for_issue_not_in_active_sprint(entry:) ⇒ Object 



235
236
237
238
239
240
241
 
# File 'lib/jirametrics/data_quality_report.rb', line 235

def scan_for_issue_not_in_active_sprint entry:
  issue = entry.issue
  return unless issue.board.scrum?
  return if issue.sprints.any?(&:active?)

  entry.report(problem_key: :issue_not_visible_on_board, detail: 'Issue is not in an active sprint')
end

#scan_for_issues_not_created_in_a_backlog_status(entry:, backlog_statuses:) ⇒ Object 



258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/jirametrics/data_quality_report.rb', line 258

def scan_for_issues_not_created_in_a_backlog_status entry:, backlog_statuses:
  creation_change = entry.issue.changes.find(&:status?)

  return if backlog_statuses.any? { |status| status.id == creation_change.value_id }

  status_string = backlog_statuses.collect { |s| format_status s, board: entry.issue.board }.join(', ')
  entry.report(
    problem_key: :created_in_wrong_status,
    detail: "Created in #{format_status creation_change, board: entry.issue.board}, " \
      "which is not one of the backlog statuses for this board: #{status_string}"
  )
end

#scan_for_issues_not_started_with_subtasks_that_have(entry:) ⇒ Object 



280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/jirametrics/data_quality_report.rb', line 280

def scan_for_issues_not_started_with_subtasks_that_have entry:
  return if entry.started

  started_subtasks = []
  entry.issue.subtasks.each do |subtask|
    started_subtasks << subtask if subtask.started_stopped_times.first
  end

  return if started_subtasks.empty?

  subtask_labels = started_subtasks.collect do |subtask|
    subtask_label(subtask)
  end
  entry.report(
    problem_key: :issue_not_started_but_subtasks_have,
    detail: subtask_labels.join('<br />')
  )
end

#scan_for_issues_on_multiple_boards(entries:) ⇒ Object 



380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/jirametrics/data_quality_report.rb', line 380

def scan_for_issues_on_multiple_boards entries:
  grouped_entries = entries.group_by { |entry| entry.issue.key }
  grouped_entries.each_value do |entry_list|
    next if entry_list.size == 1

    board_names = entry_list.collect { |entry| entry.issue.board.name.inspect }
    entry_list.first.report(
      problem_key: :issue_on_multiple_boards,
      detail: "Found on boards: #{board_names.sort.join(', ')}"
    )
  end
end

#scan_for_items_blocked_on_closed_tickets(entry:) ⇒ Object 



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/jirametrics/data_quality_report.rb', line 299

def scan_for_items_blocked_on_closed_tickets entry:
  entry.issue.issue_links.each do |link|
    next unless settings['blocked_link_text'].include?(link.label)

    this_active = !entry.stopped
    other_active = !link.other_issue.started_stopped_times.last
    next unless this_active && !other_active

    entry.report(
      problem_key: :items_blocked_on_closed_tickets,
      detail: "#{entry.issue.key} thinks it's blocked by #{link.other_issue.key}, " \
        "except #{link.other_issue.key} is closed."
    )
  end
end

#scan_for_status_change_after_done(entry:) ⇒ Object 



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/jirametrics/data_quality_report.rb', line 153

def scan_for_status_change_after_done entry:
  return unless entry.stopped

  changes_after_done = entry.issue.changes.select do |change|
    change.status? && change.time >= entry.stopped
  end
  done_status = changes_after_done.shift

  return if changes_after_done.empty?

  board = entry.issue.board
  problem = "Completed on #{entry.stopped.to_date} with status #{format_status done_status, board: board}."
  changes_after_done.each do |change|
    problem << " Changed to #{format_status change, board: board} on #{change.time.to_date}."
  end
  entry.report(
    problem_key: :status_changes_after_done,
    detail: problem
  )
end

#scan_for_stopped_before_started(entry:) ⇒ Object 



271
272
273
274
275
276
277
278
 
# File 'lib/jirametrics/data_quality_report.rb', line 271

def scan_for_stopped_before_started entry:
  return unless entry.stopped && entry.started && entry.stopped < entry.started

  entry.report(
    problem_key: :stopped_before_started,
    detail: "The stopped time '#{entry.stopped}' is before the started time '#{entry.started}'"
  )
end

#subtask_label(subtask) ⇒ Object 



315
316
317
 
# File 'lib/jirametrics/data_quality_report.rb', line 315

def subtask_label subtask
  "<img src='#{subtask.type_icon_url}' /> #{link_to_issue(subtask)} #{subtask.summary[..50].inspect}"
end

#testable_entries ⇒ Object

Return a format that's easier to assert against



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

def testable_entries
  formatter = ->(time) { time&.strftime('%Y-%m-%d %H:%M:%S %z') || '' }
  @entries.collect do |entry|
    [
      formatter.call(entry.started),
      formatter.call(entry.stopped),
      entry.issue
    ]
  end
end

#time_as_english(from_time, to_time) ⇒ Object 



319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/jirametrics/data_quality_report.rb', line 319

def time_as_english(from_time, to_time)
  delta = (to_time - from_time).to_i
  return "#{delta} seconds" if delta < 60

  delta /= 60
  return "#{delta} minutes" if delta < 60

  delta /= 60
  return "#{delta} hours" if delta < 24

  delta /= 24
  label_days delta
end