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

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, #label_days, #label_hours, #label_minutes, #link_to_issue, #next_id, #normalize_annotation_datetime, #not_visible_text, #random_color, #render, #render_axis_title, #render_top_text, #seam_end, #seam_start, #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
 
# 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. To understand the accuracy of the chart, we have to understand how accurate the
      initial data was and also how much of the original data set was used in the chart. This section
      will hopefully give you enough information to make that decision.
    </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

#entries_with_problems ⇒ Object 



118
119
120
 
# File 'lib/jirametrics/data_quality_report.rb', line 118

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

#initialize_entries ⇒ Object 



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/jirametrics/data_quality_report.rb', line 122

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! do |a, b|
    a.issue.key =~ /.+-(\d+)$/
    a_id = $1.to_i

    b.issue.key =~ /.+-(\d+)$/
    b_id = $1.to_i

    a_id <=> b_id
  end
end

#label_issues(number) ⇒ Object 



348
349
350
351
352
 
# File 'lib/jirametrics/data_quality_report.rb', line 348

def label_issues number
  return '1 item' if number == 1

  "#{number} items"
end

#problems_for(key) ⇒ Object 



84
85
86
87
88
89
90
91
92
 
# File 'lib/jirametrics/data_quality_report.rb', line 84

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 



420
421
422
423
424
425
426
 
# File 'lib/jirametrics/data_quality_report.rb', line 420

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 



428
429
430
431
432
433
434
 
# File 'lib/jirametrics/data_quality_report.rb', line 428

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 



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

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 



447
448
449
450
451
452
453
 
# File 'lib/jirametrics/data_quality_report.rb', line 447

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 



389
390
391
392
393
394
395
 
# File 'lib/jirametrics/data_quality_report.rb', line 389

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 



471
472
473
474
475
 
# File 'lib/jirametrics/data_quality_report.rb', line 471

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

#render_issue_not_started_but_subtasks_have(problems) ⇒ Object 



463
464
465
466
467
468
469
 
# File 'lib/jirametrics/data_quality_report.rb', line 463

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 



436
437
438
439
440
441
442
443
444
445
 
# File 'lib/jirametrics/data_quality_report.rb', line 436

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 



477
478
479
480
481
482
 
# File 'lib/jirametrics/data_quality_report.rb', line 477

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 



484
485
486
487
488
489
 
# File 'lib/jirametrics/data_quality_report.rb', line 484

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 



94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/jirametrics/data_quality_report.rb', line 94

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 



413
414
415
416
417
418
 
# File 'lib/jirametrics/data_quality_report.rb', line 413

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 



455
456
457
458
459
460
461
 
# File 'lib/jirametrics/data_quality_report.rb', line 455

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

#run ⇒ Object 



38
39
40
41
42
43
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
 
# File 'lib/jirametrics/data_quality_report.rb', line 38

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 



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
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/jirametrics/data_quality_report.rb', line 176

def scan_for_backwards_movement entry:, backlog_statuses:
  issue = entry.issue

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

    board = entry.issue.board
    index = entry.issue.board.visible_columns.find_index { |column| column.status_ids.include? change.value_id }
    if index.nil?
      # If it's a backlog status then ignore it. Not supposed to be visible.
      next if entry.issue.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 issue.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?
    elsif change.old_value.nil?
      # Do nothing
    elsif index < last_index
      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
    last_index = index || -1
  end
end

#scan_for_completed_issues_without_a_start_time(entry:) ⇒ Object 



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

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 



354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/jirametrics/data_quality_report.rb', line 354

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 



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/jirametrics/data_quality_report.rb', line 325

def scan_for_incomplete_subtasks_when_issue_done entry:
  return unless entry.stopped

  subtask_labels = entry.issue.subtasks.filter_map do |subtask|
    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 > entry.stopped
      "#{subtask_label subtask} (Closed #{time_as_english entry.stopped, subtask_stopped} later)"
    end
  end

  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 



235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/jirametrics/data_quality_report.rb', line 235

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 



227
228
229
230
231
232
233
 
# File 'lib/jirametrics/data_quality_report.rb', line 227

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 



250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/jirametrics/data_quality_report.rb', line 250

def scan_for_issues_not_created_in_a_backlog_status entry:, backlog_statuses:
  creation_change = entry.issue.changes.find { |issue| issue.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 



272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/jirametrics/data_quality_report.rb', line 272

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 



376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/jirametrics/data_quality_report.rb', line 376

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 



291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'lib/jirametrics/data_quality_report.rb', line 291

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 



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

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 



263
264
265
266
267
268
269
270
 
# File 'lib/jirametrics/data_quality_report.rb', line 263

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 



307
308
309
 
# File 'lib/jirametrics/data_quality_report.rb', line 307

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



107
108
109
110
111
112
113
114
115
116
 
# File 'lib/jirametrics/data_quality_report.rb', line 107

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 



311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/jirametrics/data_quality_report.rb', line 311

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