jirametrics 2.7 → 2.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73e2f2e8408a55ccecb221ba0c6d241c77f19de18d2100a9b05213a6470ed65f
-  data.tar.gz: d0f9056615c44e783c824ca1c6566c95bf68f16a26f81a596475c1d458fee9f1
+  metadata.gz: b747372b77be9d3ec514c09b57f479741a47688dd6e634e6823aa9feefe3154e
+  data.tar.gz: df7b9bdc06211d7d2fd89df18af5aa8ab4b780aa58f798c29c45ca8033c1986f
 SHA512:
-  metadata.gz: e58594175d798269e0e4b8ec1fd4c0f8b693767670222bc6144be19646b04f83e5edb508e4f933f8466865018e8802f789ecb348db368c3f626318df7774c0e0
-  data.tar.gz: 4555628c33a398cd3aaedd6e36a074b54d89f5a431f47d8617344e4af45e389e529ba54dd9cbd7d9e7d8ad7f673a68f664d00b951451b433d47f90c6feb439a5
+  metadata.gz: 7f4873e816019b7b2903b7b2a5c905484a6e1ef5d2601f9bb8dd0cec78a306646a4d145a6bb76981a4bd3ce46d884e5e7b8e8e3ccef4f179a2a7067e26b58a43
+  data.tar.gz: 40790878004dd12d1aa362cbe72988a2c6ed13152066b48ab1f38855a74bf89f8aae926d13d3e721990ca568c20f5adbd1c99d0ce5b81aaece19d04701b8eddd

data/lib/jirametrics/chart_base.rb

@@ -25,6 +25,14 @@ class ChartBase
     @aggregated_project
   end
 
+  def html_directory
+    pathname = Pathname.new(File.realpath(__FILE__))
+    # basename = pathname.basename.to_s
+    # raise "Unexpected filename #{basename.inspect}" unless basename.match?(/^(.+)\.rb$/)
+
+    "#{pathname.dirname}/html"
+  end
+
   def render caller_binding, file
     pathname = Pathname.new(File.realpath(file))
     basename = pathname.basename.to_s
@@ -33,8 +41,8 @@ class ChartBase
     # Insert a incrementing chart_id so that all the chart names on the page are unique
     caller_binding.eval "chart_id='chart#{next_id}'" # chart_id=chart3
 
-    @html_directory = "#{pathname.dirname}/html"
-    erb = ERB.new file_system.load "#{@html_directory}/#{$1}.erb"
+    # @html_directory = "#{pathname.dirname}/html"
+    erb = ERB.new file_system.load "#{html_directory}/#{$1}.erb"
     erb.result(caller_binding)
   end
 
@@ -100,7 +108,7 @@ class ChartBase
     issues_id = next_id
 
     issue_descriptions.sort! { |a, b| a[0].key_as_i <=> b[0].key_as_i }
-    erb = ERB.new file_system.load "#{@html_directory}/collapsible_issues_panel.erb"
+    erb = ERB.new file_system.load File.join(html_directory, 'collapsible_issues_panel.erb')
     erb.result(binding)
   end
 

data/lib/jirametrics/data_quality_report.rb

@@ -57,7 +57,25 @@ class DataQualityReport < ChartBase
     entries_with_problems = entries_with_problems()
     return '' if entries_with_problems.empty?
 
-    wrap_and_render(binding, __FILE__)
+    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(:status_not_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 << '</ul>'
+
+    result
   end
 
   def problems_for key
@@ -70,6 +88,18 @@ class DataQualityReport < ChartBase
     result
   end
 
+  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
+
   # Return a format that's easier to assert against
   def testable_entries
     format = '%Y-%m-%d %H:%M:%S %z'
@@ -317,4 +347,94 @@ class DataQualityReport < ChartBase
       )
     end
   end
+
+  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
+    HTML
+  end
+
+  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://en.wikipedia.org/wiki/Survivorship_bias">
+        Survivorship Bias</a>.
+      HTML
+    end
+    html
+  end
+
+  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
+
+  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
+
+  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
+
+  def render_status_not_on_board problems
+    <<-HTML
+      #{label_issues problems.size} were not visible on the board for some period of time. This may impact
+      timings as the work was likely to have been forgotten if it wasn't visible.
+    HTML
+  end
+
+  def render_created_in_wrong_status problems
+    <<-HTML
+      #{label_issues problems.size} were created in a status not designated as Backlog. This will impact
+      the measurement of start times and will therefore impact whether it's shown as in progress or not.
+    HTML
+  end
+
+  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
+
+  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
+
+  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
+
+  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
 end

data/lib/jirametrics/examples/aggregated_project.rb

@@ -3,8 +3,6 @@
 # This file is really intended to give you ideas about how you might configure your own reports, not
 # as a complete setup that will work in every case.
 #
-# See https://github.com/mikebowler/jirametrics/wiki/Examples-folder for more details
-#
 # The point of an AGGREGATED report is that we're now looking at a higher level. We might use this in a
 # S2 meeting (Scrum of Scrums) to talk about the things that are happening across teams, not within a
 # single team. For that reason, we look at slightly different things that we would on a single team board.

data/lib/jirametrics/examples/standard_project.rb

@@ -2,8 +2,6 @@
 
 # This file is really intended to give you ideas about how you might configure your own reports, not
 # as a complete setup that will work in every case.
-#
-# See https://github.com/mikebowler/jirametrics/wiki/Examples-folder for more
 class Exporter
   def standard_project name:, file_prefix:, ignore_issues: nil, starting_status: nil, boards: {},
       default_board: nil, anonymize: false, settings: {}, status_category_mappings: {},

data/lib/jirametrics/flow_efficiency_scatterplot.rb

@@ -19,14 +19,12 @@ class FlowEfficiencyScatterplot < ChartBase
       </div>
       <div class="p">
         <math>
-          <mn>Flow efficiency</mn>
+          <mn>Flow efficiency (%)</mn>
           <mo>=</mo>
           <mfrac>
             <mrow><mn>Time adding value</mn></mrow>
             <mrow><mn>Total time</mn></mrow>
           </mfrac>
-          <mo>x</mo>
-          <mn>100%</mn>
         </math>
       </div>
       <div style="background: yellow">Note that for this calculation to be accurate, we must be moving items into a

data/lib/jirametrics/html/index.css

@@ -99,9 +99,6 @@ table.standard {
     background-color: #eee;
   }
 }
-.quality_note_bullet {
-  color: red;
-}
 
 .chart {
   background-color: white;
@@ -119,6 +116,16 @@ div.color_block {
   border: 1px solid black;
 }
 
+ul.quality_report {
+  list-style-type: '⮕';
+  ::marker {
+    color: red;
+  }
+  li {
+    padding: 0.2em;
+  }
+}
+
 @media screen and (prefers-color-scheme: dark) {
   :root {
     --non-working-days-color: #2f2f2f;

data/lib/jirametrics/issue.rb

@@ -141,7 +141,7 @@ class Issue
     @board.project_config.file_system.log(
       "Warning: Status name #{name.inspect} for issue #{key} not found in" \
       " #{board.possible_statuses.collect(&:name).inspect}" \
-      "\n  See Q1 in the FAQ for more details: https://github.com/mikebowler/jirametrics/wiki/FAQ\n",
+      "\n  See https://jirametrics.org/faq/#q1\n",
       also_write_to_stderr: true
     )
     status = Status.new(name: name, category_name: 'In Progress')

data/lib/jirametrics/project_config.rb

@@ -31,6 +31,10 @@ class ProjectConfig
     instance_eval(&@block) if @block
   end
 
+  def data_downloaded?
+    File.exist? File.join(@target_path, "#{file_prefix}_meta.json")
+  end
+
   def load_data
     return if @has_loaded_data
 
@@ -43,6 +47,8 @@ class ProjectConfig
   end
 
   def run load_only: false
+    return if @exporter.downloading?
+
     load_data unless aggregated_project?
     anonymize_data if @anonymizer_needed
 
@@ -304,6 +310,10 @@ class ProjectConfig
         raise 'This is an aggregated project and issues should have been included with the include_issues_from ' \
           'declaration but none are here. Check your config.'
       end
+
+      return @issues = [] if @exporter.downloading?
+      raise 'No data found. Must do a download before an export' unless data_downloaded?
+
       load_data if all_boards.empty?
 
       timezone_offset = exporter.timezone_offset

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: '2.7'
+  version: 2.7.2
 platform: ruby
 authors:
 - Mike Bowler
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-27 00:00:00.000000000 Z
+date: 2024-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: random-word
@@ -106,7 +106,6 @@ files:
 - lib/jirametrics/html/cycletime_histogram.erb
 - lib/jirametrics/html/cycletime_scatterplot.erb
 - lib/jirametrics/html/daily_wip_chart.erb
-- lib/jirametrics/html/data_quality_report.erb
 - lib/jirametrics/html/estimate_accuracy_chart.erb
 - lib/jirametrics/html/expedited_chart.erb
 - lib/jirametrics/html/flow_efficiency_scatterplot.erb
@@ -132,14 +131,14 @@ files:
 - lib/jirametrics/tree_organizer.rb
 - lib/jirametrics/trend_line_calculator.rb
 - lib/jirametrics/value_equality.rb
-homepage: https://github.com/mikebowler/jirametrics
+homepage: https://jirametrics.org
 licenses:
 - Apache-2.0
 metadata:
   rubygems_mfa_required: 'true'
   bug_tracker_uri: https://github.com/mikebowler/jirametrics/issues
-  changelog_uri: https://github.com/mikebowler/jirametrics/wiki/Changes
-  documentation_uri: https://github.com/mikebowler/jirametrics/wiki
+  changelog_uri: https://jirametrics.org/changes
+  documentation_uri: https://jirametrics.org
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/jirametrics/html/data_quality_report.erb

@@ -1,138 +0,0 @@
-<% 
-  problems = problems_for :discarded_changes
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= 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>
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :completed_but_not_started
-  unless problems.empty?
-    percentage_work_included = ((issues.size - problems.size).to_f / issues.size * 100).to_i
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> were discarded from all charts using cycletime (scatterplot, histogram, etc) as we couldn't determine when they started. 
-    <% if percentage_work_included < 85 %>
-      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://en.wikipedia.org/wiki/Survivorship_bias">Survivorship Bias</a>.
-    <% end %>
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :status_changes_after_done
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= 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.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :backwards_through_status_categories
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= 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.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :backwords_through_statuses
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= 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.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :status_not_on_board
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> were not visible on the board for some period of time. This may impact timings as the work was likely to have been forgotten if it wasn't visible.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :created_in_wrong_status
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> were created in a status not designated as Backlog. This will impact the measurement of start times and will therefore impact whether it's shown as in progress or not.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :stopped_before_started
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= 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.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :issue_not_started_but_subtasks_have
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= 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.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :incomplete_subtasks_when_issue_done
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> issues were marked as done while subtasks were still not done.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :issue_on_multiple_boards
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> 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.
-    <%= collapsible_issues_panel problems, :hide_board_column %>
-  </p>
-<% 
-  end
-%>