monte 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe28c6cadcd331c236ef5dd53e43b9d32d18b9585fbcc7debc820e1abcb28394
-  data.tar.gz: 998b21dbf4105649811833eef488e9ad858876759f9bb974f5805937655bacad
+  metadata.gz: ecddb357e33227ebed1a3149df0a58bc61b0762a76c895a10d329cb27c504460
+  data.tar.gz: 0163ead370cdc96747a039961fcb5a8835cf93998bf3737d05ca0f8d409b6fe1
 SHA512:
-  metadata.gz: 26eb9d0115fad3fc93ecf4dd3d007d35573da5e0468ca6fa04c91fedc85499a79edda481a7af08a1be643e0a14229ce5b5a23d8e5388d61e652f63ea55b177b8
-  data.tar.gz: 8c1bc63cefcde03c48e2d2217415b20469ed9937d75c428b9ad701c12bff625ff59040025ae2954597f6fe3e7ad434980a39180c4cbcd3cdcdff3c4d97c01f16
+  metadata.gz: '0298468a2c201f869396178d9429bab012a9fc2f873912079c07d0952af3c66e435915b5d804efbae30855669cffcb6c15ace1430cc29b7f4b6eecc2dfd052db'
+  data.tar.gz: 1ed6f3bf20fe4a997493a453263372ecc46a4bdbad30db511423c71c32d26b3ea49567edd4f8eaf218522569c3dd95d53c269e01f4990068e6e8d44201642bfd

data/.gitignore

@@ -9,5 +9,7 @@
 /log/
 /lib/github_cli/man/u
 
+#built gem
+monte-*
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Change log
 
-## [v0.0.1] - 2020-11-08
+## [v0.2.0] - 2020-11-21
+
+### Added
+* Updated the `carlo` command to ask for a JIRA data export that can be used to
+  build a distribution of historic throughput based on a JQL filter
+
+## [v0.1.0] - 2020-11-08
 
 ### Added
 * Added core command: `carlo`

data/README.md

@@ -22,32 +22,63 @@ have little previous data with which to build your forecast.
 
 ```sh
 $ monte carlo
->
->   __  __                   _
->  |  \/  |   ___    _ __   | |_    ___
->  | |\/| |  / _ \  | '_ \  | __|  / _ \
->  | |  | | | (_) | | | | | | |_  |  __/
->  |_|  |_|  \___/  |_| |_|  \__|  \___|
->
-> Please answer the following:
->
-> How many items do you have in your backlog? 40
-> How certain are you with regard to the scope of the work? medium
-> When will you start work (e.g. 28/04/2021) 2020-11-15
-> What is the smallest number of tasks/tickets you have completed in a week? 2
-> What is the largest number of tasks/tickets you have completed in a week? 6
-> How many simulations would you like to run 10000
->
->
-> Your Results
->
-> ┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
-> │    5%    │   15%    │   30%    │   50%    │   70%    │   85%    │   95%    │
-> ├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
-> │2021-02-14│2021-02-21│2021-02-28│2021-02-28│2021-03-07│2021-03-14│2021-03-21│
-> └──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
+ |  \/  |   ___    _ __   | |_    ___
+ | |\/| |  / _ \  | '_ \  | __|  / _ \
+ | |  | | | (_) | | | | | | |_  |  __/
+ |_|  |_|  \___/  |_| |_|  \__|  \___|
+
+Welcome to Monte, a tool to help you answer the question: 'When will the work be done?'
+
+
+Please answer the following questions
+How many tasks/tickets do you have left to complete? 40
+Do you have a JIRA csv export to use? no
+Enter the smallest number of tasks/tickets you have finished in a week? 2
+Enter the largest number of tasks/tickets you have finished in a week? 6
+When will you start work (e.g. 28/04/2021) 2020-11-21
+How certain are you with regard to the scope of the work? high
+How many simulations would you like to run? 10000
+┌──────────────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
+│Forecast Certainty│    5%    │   15%    │   30%    │   50%    │   70%    │   85%    │   95%    │
+├──────────────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
+│  Forecast Date   │2021-02-06│2021-02-06│2021-02-13│2021-02-13│2021-02-20│2021-02-27│2021-03-06│
+└──────────────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
 ```
 
+Forecasting like this works better when you use real data from the past to model
+what the future will look like. To enable this Monte can use a JIRA export of
+tasks completed over whatever historic timeframe you would like. Once you have
+created your JQL filter ensure that you include the "Resolved" column and then
+export as a csv. When running the app you will be given the option to specify
+the path of the file and this will then build a distribution of previous
+throughputs for use in the simulations. The following is a runthrough using a
+test data file.
+
+```sh
+  __  __                   _
+ |  \/  |   ___    _ __   | |_    ___
+ | |\/| |  / _ \  | '_ \  | __|  / _ \
+ | |  | | | (_) | | | | | | |_  |  __/
+ |_|  |_|  \___/  |_| |_|  \__|  \___|
+
+Welcome to Monte, a tool to help you answer the question: 'When will the work be done?'
+
+
+Please answer the following questions
+How many tasks/tickets do you have left to complete? 40
+Do you have a JIRA csv export to use? Yes
+what is the absolute file path to the csv file /Users/user/directory/monte/spec/test_data/data.csv
+When will you start work (e.g. 28/04/2021) 2020-11-21
+How certain are you with regard to the scope of the work? medium
+How many simulations would you like to run? 10000
+┌──────────────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
+│Forecast Certainty│    5%    │   15%    │   30%    │   50%    │   70%    │   85%    │   95%    │
+├──────────────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
+│  Forecast Date   │2021-02-06│2021-02-13│2021-02-20│2021-03-06│2021-03-13│2021-03-27│2021-04-10│
+└──────────────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
+```
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/monte/cli.rb

@@ -26,7 +26,7 @@ module Monte
         invoke :help, ['carlo']
       else
         require_relative 'commands/carlo'
-        Monte::Commands::Carlo.new(options).execute
+        Monte::Commands::Carlo.new.execute
       end
     end
   end

data/lib/monte/commands/carlo.rb

@@ -3,52 +3,84 @@
 require 'date'
 require_relative '../command'
 require_relative '../simulation'
+require_relative '../csv_data'
 
 module Monte
   module Commands
     # Runs Monte Carlo Simulation to estimate how long a piece of work will take
     class Carlo < Monte::Command
       include Simulation
-      CERTAINTY = { 'low' => 1.8, 'medium' => 1.5, 'high' => 1.2 }.freeze
+      include CSVData
+      BLURB = %(Welcome to Monte, a tool to help you answer the question: 'When will the work be done?'\n\n
+Please answer the following questions\n)
+      CERTAINTY = { 'certain' => 1.0, 'high' => 1.2, 'medium' => 1.5, 'low' => 1.8 }.freeze
       RUNS = { '10000' => 10_000, '1000' => 1000, '500' => 500 }.freeze
-      HEADERS = ['5%', '15%', '30%', '50%', '70%', '85%', '95%'].freeze
+      HEADERS = ['Forecast Certainty', '5%', '15%', '30%', '50%', '70%', '85%', '95%'].freeze
       PERCENTILES = [0.05, 0.15, 0.3, 0.5, 0.7, 0.85, 0.95].freeze
 
-      def initialize(options)
-        @options = options
-      end
-
-      def execute(output: $stdout)
-        output.puts(create_header)
-        output.puts("Please answer the following:\n\n")
-        user_input = ask_questions!
+      def execute
+        puts(create_header, BLURB)
+        user_input = ask_questions({})
         results = percentiles(user_input)
-        output.puts("\n\nYour Results\n\n")
-        output.puts(create_table(results))
+        puts(create_table(results))
       end
 
       def create_table(rows)
-        table(HEADERS, [rows]).render(:unicode, alignment: [:center])
+        table(HEADERS, [rows.prepend('Forecast Date')])
+          .render(:unicode, alignment: [:center])
       end
 
       def create_header
         large_title('Monte')
       end
 
-      def ask_questions!
-        prompt.collect do
-          key(:backlog).ask('How many items do you have in your backlog?', convert: :int)
-          key(:split_factor).select('How certain are you with regard to the scope of the work?', CERTAINTY)
-          key(:start_date).ask('When will you start work (e.g. 28/04/2021)') do |q|
-            q.default Date.today
-            q.convert ->(input) { Date.parse(input.to_s) }
-          end
-          key(:low).ask('What is the smallest number of tasks/tickets you have completed in a week?', convert: :int)
-          key(:high).ask('What is the largest number of tasks/tickets you have completed in a week?', convert: :int)
-          key(:runs).select('How many simulations would you like to run', RUNS)
+      def ask_questions(options)
+        q1 = ask_backlog(options)
+        q2 = ask_throughput(q1)
+        q3 = ask_start(q2)
+        q4 = ask_split(q3)
+        ask_runs(q4)
+      end
+
+      def ask_backlog(options)
+        options.merge(backlog:
+                      prompt.ask('How many tasks/tickets do you have left to complete?',
+                                 required: true,
+                                 convert: :int))
+      end
+
+      def ask_split(options)
+        options.merge(split:
+                      prompt.select('How certain are you with regard to the scope of the work?', CERTAINTY))
+      end
+
+      def ask_start(options)
+        options.merge(start:
+                      prompt.ask('When will you start work (e.g. 28/04/2021)') do |q|
+                        q.required true
+                        q.default Date.today
+                        q.convert ->(input) { Date.parse(input.to_s) }
+                      end)
+      end
+
+      def ask_throughput(options)
+        data_exists = prompt.yes?('Do you have a JIRA csv export to use?', required: true)
+        if data_exists
+          path = prompt.ask('what is the absolute file path to the csv file', required: true)
+          throughput = historic_throughput(path)
+        else
+          low = prompt.ask('Enter the smallest number of tasks/tickets you have finished in a week?', convert: :int)
+          high = prompt.ask('Enter the largest number of tasks/tickets you have finished in a week?', convert: :int)
+          throughput = (low..high).to_a
         end
+        options.merge(throughput: throughput)
       end
 
+      def ask_runs(options)
+        options.merge(
+          runs: prompt.select('How many simulations would you like to run?', RUNS)
+        )
+      end
     end
   end
 end

data/lib/monte/csv_data.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'date'
+
+# This module supports parsing an export of Jira data to build a sample of
+# historic throughputs that provide a more accurate forecast
+# It takes the absolute path to the csv export and returns an array containing
+# the number of tasks/tickets completed each week
+module CSVData
+  RESOLVED = 'Resolved'
+  def historic_throughput(path)
+    headers, *data = CSV.read(path)
+    resolved_column = headers.index(RESOLVED)
+    resolved_dates = data.flat_map { |row| Date.parse row[resolved_column] }
+    grouped_into_weeks = resolved_dates.group_by { |date| date - date.wday }
+    grouped_into_weeks.values.map(&:length)
+  end
+end

data/lib/monte/simulation.rb

@@ -10,32 +10,30 @@
 module Simulation
   PERCENTILES = [0.05, 0.15, 0.3, 0.5, 0.7, 0.85, 0.95].freeze
 
-  def percentiles(args)
-    results = run_simulations(args).sort
+  def percentiles(options)
+    results = run_simulations(options).sort
     PERCENTILES.map do |percentile|
-      index = args[:runs] * (percentile - 1)
+      index = options[:runs] * (percentile - 1)
       results[index]
     end
   end
 
-  def run_simulations(args)
-    estimated_backlog = args[:backlog] * args[:split_factor]
-    Array.new(args[:runs]) do |_|
-      args[:start_date] + simulate(
+  def run_simulations(options)
+    estimated_backlog = options[:backlog] * options[:split]
+    Array.new(options[:runs]) do |_|
+      options[:start] + simulate(
         estimated_backlog,
-        args[:low],
-        args[:high]
+        options[:throughput]
       ) * 7
     end
   end
 
-  def simulate(backlog, low, high, result = 0)
+  def simulate(backlog, throughput, result = 0)
     return result if backlog <= 0
 
     simulate(
-      backlog - rand(low..high),
-      low,
-      high,
+      backlog - throughput.sample,
+      throughput,
       result + 1
     )
   end

data/lib/monte/version.rb

@@ -1,3 +1,3 @@
 module Monte
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monte
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrew Werner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-11-15 00:00:00.000000000 Z
+date: 2020-11-21 00:00:00.000000000 Z
 dependencies: []
 description: |-
   If you are an engineer who is being asked, 'When will
@@ -37,6 +37,7 @@ files:
 - lib/monte/command.rb
 - lib/monte/commands/.gitkeep
 - lib/monte/commands/carlo.rb
+- lib/monte/csv_data.rb
 - lib/monte/simulation.rb
 - lib/monte/version.rb
 - monte.gemspec