trollolo 0.0.3

data/lib/version.rb

@@ -0,0 +1,5 @@
+module Trollolo
+
+  VERSION = "0.0.3"
+
+end

data/man/.gitignore

@@ -0,0 +1,4 @@
+*.1
+*.5
+*.8
+*.html

data/man/trollolo.1.md

@@ -0,0 +1,152 @@
+# Trollolo -- Trello command line client
+
+## SYNOPSIS
+
+`trollolo` [command] [options]
+
+`trollolo` help [command]
+
+
+## DESCRIPTION
+
+**Trollolo** is a command line client for Trello. It supports fetching lists
+and cards and has functionality for extracting data for burndown charts.
+
+
+## GENERAL OPTIONS
+
+  * `--version`:
+    Give out version of trollolo tool. Exit when done.
+
+  * `--verbose`:
+    Run in verbose mode.
+
+  * `--board-id`:
+    Most commands take a `board-id` parameter. This is the id of the Trello
+    board. It is the cryptic part of the URL of the Trello board.
+
+  * `--raw`:
+    Some of the commands take a `raw` option. If this is provided the commands
+    put out the raw JSON returned by the server instead of processing it to
+    a more human-readable version.
+
+
+## COMMANDS
+
+### burndown-init -- Initialize burndown chart
+
+`trollolo burndown-init --board-id=<board id> --output=<directory>`
+
+Initialize the given directory for the generation of burndown charts. It stores
+the given board id in the directory in a YAML file together with other
+configuration data. The YAML file also is used to store the data for the
+burndown charts. The `burndown` command can be used to update the file with
+data from the specified Trello board.
+
+The directory also gets a script to do the actual generation of the burndown
+chart. Just run this script after each update of the data to get the latest
+burndown chart.
+
+### burndown -- Process data for burndown chart
+
+`trollolo burndown --output=<directory>`
+
+Update the burndown data in the given directory from the Trello board
+specified in the YAML file in the directory. The given directory has to be
+initialized before running the `burndown` command by running the
+`burndown-init` command.
+
+The actual generation of the burndown chart is done by running the script
+which is put into the directory by the `burndown-init` command.
+
+For correct generation of the burndown chart, the Trello board has to follow
+a few convention. They are described in the section `CONVENTIONS for SCRUM
+BOARDS`.
+
+### plot -- Plot burndown chart
+
+`trollolo plot <sprint-number>`
+
+Plot the burndown chart for given sprint. This command assumes that you are in
+the burndown directory (initially created with `burndown-init`) and that the
+corresponding file `burndown-data-<sprint-number>.yaml` exists there.
+
+### fetch-burndown-data -- Read data for burndown chart
+
+`trollolo fetch-burndown-data --board-id=<board id>`
+
+Reads data from the specified Trello board, extracts it according to the
+conventions for Scrum boards, and reports burndown data.
+
+### get-cards -- Get card data for a board
+
+Read all card data for a given board.
+
+### get-checklists -- Get checklist data for a board
+
+Read all checklist data for a given board
+
+### get-lists -- Get list data for a board
+
+Read all list data for a given board.
+
+
+## EXAMPLES
+
+Fetch burndown data of a Trello board configured in the configuration file:
+
+`trollolo fetch-burndown-data --board-id=CRdddpdy`
+
+Fetch raw data of all cards of a Trello board:
+
+`trollolo get-cards --raw --board-id=CRdddpdy`
+
+
+## CONFIGURATION
+
+Trollolo reads a configuration file `.trollolorc` in the home directory of the
+user running the command line tool. It reads the data required to authenticate
+with the Trello server from it. It's two values (the example shows random data):
+
+```yaml
+developer_public_key: 87349873487ef8732487234
+member_token: 87345897238957a29835789b2374580927f3589072398579820345
+```
+
+These values have to be set with the personal access data for the Trello API
+and the id of the board, which is processed.
+
+For creating a developer key go to the
+[Developer API Keys](https://trello.com/1/appKey/generate) page on Trello. It's
+the key in the first box.
+
+For creating a member token go follow the
+[instructions](https://trello.com/docs/gettingstarted/index.html#getting-a-token-from-a-user)
+in the Trello API documentation.
+
+The board id is the cryptic string in the URL of your board.
+
+
+## CONVENTIONS FOR SCRUM BOARDS
+
+The burndown functionality expects the board to follow a certain naming scheme,
+so that Trollolo can process it as a Scrum board.
+
+It expects a list `Sprint Backlog` with open items, a list `Doing` with items in
+progress, and a list `Done Sprint X` with done items, where `X` is the number
+of the sprint. For burndown data calculation the list with the highest number
+is taken.
+
+On work item cards the tool takes a bracketed number as suffix as size of the
+item in story points. E.g. a card with the title `(3) Build magic tool` would
+have three story points.
+
+Cards under the waterline not part of the actual sprint commitment are expected
+to have a label with the name "Under waterline".
+
+An example for a board which follow this conventions is the [Trollolo Testing
+Board](https://trello.com/b/CRdddpdy/trollolo-testing-board).
+
+## COPYRIGHT
+
+Trollolo is Copyright (C) 2013-2014 SUSE LLC

data/scripts/create_burndown.py

@@ -0,0 +1,149 @@
+#!/usr/bin/python
+import matplotlib.pyplot as plt
+import numpy as np
+import sys
+import yaml
+
+if len(sys.argv) != 2:
+  print "Usage: machinery-burndown.py <sprint-number>"
+  sys.exit(1)
+
+sprint = sys.argv[1]
+
+with open('burndown-data-' + sprint + '.yaml', 'r') as f:
+  burndown = yaml.load(f)
+
+meta = burndown["meta"]
+
+total_days = meta["total_days"]
+
+current_day = 1
+x_days = []
+y_open_story_points = []
+y_open_tasks = []
+total_tasks = []
+total_story_points = []
+x_days_extra = []
+x_day_extra_start = []
+y_story_points_done_extra = [0]
+y_tasks_done_extra = [0]
+
+for day in burndown["days"]:
+  x_days.append(current_day)
+  y_open_story_points.append(day["story_points"]["open"])
+  y_open_tasks.append(day["tasks"]["open"])
+  total_tasks.append(day["tasks"]["total"])
+  total_story_points.append(day["story_points"]["total"])
+
+  if "story_points_extra" in day or "tasks_extra" in day:
+    x_days_extra.append(current_day)
+    tasks = 0
+    if day.has_key("tasks_extra"):
+      tasks = -day["tasks_extra"]["done"]
+    y_tasks_done_extra.append(tasks)
+    points = 0
+    if day.has_key("story_points_extra"):
+      points = -day["story_points_extra"]["done"]
+    y_story_points_done_extra.append(points)
+
+  current_day += 1
+
+# Add a day at the beginning of the extra days, so the curve starts at zero
+if x_days_extra:
+  x_days_extra = [x_days_extra[0] - 1] + x_days_extra
+
+scalefactor = float(total_tasks[0]) / float(y_open_story_points[0])
+
+# Calculate minimum and maximum 'y' values for the axis
+ymin_t_extra = 0
+ymin_s_extra = 0
+ymax = y_open_story_points[0] + 3
+
+if len(y_tasks_done_extra) > 0:
+  ymin_t_extra = y_tasks_done_extra[len(y_tasks_done_extra) -1] -3
+if len(y_story_points_done_extra) > 0:
+  ymin_s_extra = y_story_points_done_extra[len(y_story_points_done_extra) -1] -3
+if ymin_t_extra < ymin_s_extra:
+  ymin = ymin_t_extra
+else:
+  ymin = ymin_s_extra
+if ymin_t_extra == 0 and ymin_s_extra == 0:
+  ymin = -3
+
+# Plot in xkcd style
+plt.xkcd()
+
+plt.figure(1, figsize=(11, 6))
+
+# Title of the burndown chart
+plt.suptitle('Sprint ' + sprint, fontsize='large')
+
+plt.xlabel('Days')
+plt.axis([0, total_days + 1, ymin, ymax])
+plt.plot([1, total_days] , [y_open_story_points[0], 0], color='grey')
+plt.plot([0, total_days + 1], [0, 0], color='blue', linestyle=':')
+
+# Weekend lines
+for weekend_line in meta["weekend_lines"]:
+  plt.plot([weekend_line, weekend_line], [ymin+1, ymax-1], color='grey', linestyle=':')
+
+# Story points
+plt.ylabel('Story Points', color='black')
+plt.plot(x_days, y_open_story_points, 'ko-', linewidth=2)
+if x_days_extra:
+  plt.plot(x_days_extra, y_story_points_done_extra, 'ko-', linewidth=2)
+
+# Tasks
+plt.twinx()
+plt.ylabel('Tasks', color='green')
+plt.tick_params(axis='y', colors='green')
+plt.axis([0, total_days + 1, ymin*scalefactor, ymax * scalefactor])
+plt.plot(x_days, y_open_tasks, 'go-', linewidth=2)
+if x_days_extra:
+  plt.plot(x_days_extra, y_tasks_done_extra, 'go-', linewidth=2)
+
+# Calculation of new tasks
+if len(total_tasks) > 1:
+  new_tasks = [0]
+  for i in range(1, len(total_tasks)):
+    new_tasks.append(total_tasks[i] - total_tasks[i - 1])
+  effective_new_tasks_days = []
+  effective_new_tasks = []
+  for i in range(len(new_tasks)):
+    if new_tasks[i] != 0:
+      effective_new_tasks_days.append(i - 0.25 + 1)
+      effective_new_tasks.append(new_tasks[i])
+  if len(effective_new_tasks) > 0:
+    plt.bar(effective_new_tasks_days, effective_new_tasks, .2, color='green')
+
+# Calculation of new story points
+if len(total_story_points) > 1:
+  new_story_points = [0]
+  for i in range(1, len(total_story_points)):
+    new_story_points.append(total_story_points[i] - total_story_points[i - 1])
+  effective_new_story_points_days = []
+  effective_new_story_points = []
+  for i in range(len(new_story_points)):
+    if new_story_points[i] != 0:
+      effective_new_story_points_days.append(i + 0.05 + 1)
+      effective_new_story_points.append(new_story_points[i])
+  if len(effective_new_story_points) > 0:
+    plt.bar(effective_new_story_points_days, effective_new_story_points, .2, color='black')
+
+# Draw arrow showing already done tasks at begin of sprint
+tasks_done = burndown["days"][0]["tasks"]["total"] - burndown["days"][0]["tasks"]["open"]
+
+if tasks_done > 5:
+  plt.annotate("", 
+	       xy=(x_days[0], scalefactor * y_open_story_points[0] - 0.5 ), xycoords='data',
+	       xytext=(x_days[0], y_open_tasks[0] + 0.5), textcoords='data',
+	       arrowprops=dict(arrowstyle="<|-|>", connectionstyle="arc3", color='green')
+	      )
+
+  plt.text(0.7, y_open_story_points[0], str(tasks_done) + " tasks done",
+	   rotation='vertical', verticalalignment='center', color='green'
+	  )
+
+# Save the burndown chart
+plt.savefig('burndown-' + sprint + '.png',bbox_inches='tight')
+plt.show()

data/spec/burndown_chart_spec.rb

@@ -0,0 +1,307 @@
+require_relative 'spec_helper'
+
+include GivenFilesystemSpecHelpers
+
+describe BurndownChart do
+
+  before(:each) do
+    @settings = dummy_settings
+    @burndown_data = BurndownData.new(@settings)
+    @chart = BurndownChart.new(@settings)
+  end
+
+  describe "initializer" do
+    it "sets initial meta data" do
+      expect(@chart.data["meta"]["sprint"]).to eq 1
+      expect(@chart.data["meta"]["total_days"]).to eq 10
+      expect(@chart.data["meta"]["weekend_lines"]).to eq [3.5, 8.5]
+    end
+  end
+  
+  describe "data" do
+    use_given_filesystem
+    
+    before(:each) do
+      @raw_data = [
+        {
+          "date" => '2014-04-23',
+          "story_points" =>
+          {
+            "total" => 30,
+            "open" => 23
+          },
+          "tasks" =>
+          {
+            "total" => 25,
+            "open" => 21
+          }
+        },
+        {
+          "date" => '2014-04-24',
+          "story_points" =>
+          {
+            "total" => 30,
+            "open" => 21
+          },
+          "tasks" =>
+          {
+            "total" => 26,
+            "open" => 19
+          },
+          "story_points_extra" =>
+          {
+            "done" => 3
+          },
+          "tasks_extra" =>
+          {
+            "done" => 2
+          }
+        }
+      ]
+    end
+
+    it "creates first data entry" do
+      @burndown_data.story_points.open = 16
+      @burndown_data.story_points.done = 7
+      @burndown_data.tasks.open = 10
+      @burndown_data.tasks.done = 11
+
+      @chart.add_data(@burndown_data,Date.parse("2014-05-30"))
+      
+      expect( @chart.data["days"].first["story_points"] ).to eq(
+        {
+          "total" => 23,
+          "open" => 16
+        } )
+      expect( @chart.data["days"].first["tasks"] ).to eq(
+        {
+          "total" => 21,
+          "open" => 10
+        } )
+    end
+    
+    it "returns sprint number" do
+      expect(@chart.sprint).to eq 1
+    end
+    
+    it "adds data" do
+      @chart.data["days"] = @raw_data
+      
+      @burndown_data.story_points.open = 16
+      @burndown_data.story_points.done = 7
+      @burndown_data.tasks.open = 10
+      @burndown_data.tasks.done = 11
+      @burndown_data.extra_story_points.open = 2
+      @burndown_data.extra_story_points.done = 3
+      @burndown_data.extra_tasks.open = 5
+      @burndown_data.extra_tasks.done = 2
+      
+      @chart.add_data(@burndown_data,Date.parse("2014-05-30"))
+      
+      expect( @chart.data["days"].count ).to eq 3
+      expect( @chart.data["days"].last["date"] ).to eq ( "2014-05-30" )
+      expect( @chart.data["days"].last["story_points"] ).to eq ( {
+        "total" => 23,
+        "open" => 16
+      } )
+      expect( @chart.data["days"].last["tasks"] ).to eq ( {
+        "total" => 21,
+        "open" => 10
+      } )
+      expect( @chart.data["days"].last["story_points_extra"] ).to eq ( {
+        "done" => 3
+      } )
+      expect( @chart.data["days"].last["tasks_extra"] ).to eq ( {
+        "done" => 2
+      } )
+    end
+
+    it "replaces data of same day" do
+      @chart.data["days"] = @raw_data
+      
+      @burndown_data.story_points.open = 16
+      @burndown_data.story_points.done = 7
+      @burndown_data.tasks.open = 10
+      @burndown_data.tasks.done = 11
+      
+      @chart.add_data(@burndown_data,Date.parse("2014-05-30"))
+      
+      expect( @chart.data["days"].count ).to eq 3
+      expect( @chart.data["days"].last["story_points"] ).to eq ( {
+        "total" => 23,
+        "open" => 16
+      } )
+
+      @burndown_data.story_points.done = 8
+      @chart.add_data(@burndown_data,Date.parse("2014-05-30"))
+      
+      expect( @chart.data["days"].count ).to eq 3
+      expect( @chart.data["days"].last["story_points"] ).to eq ( {
+        "total" => 24,
+        "open" => 16
+      } )
+    end
+
+    it "reads data" do
+      @chart.read_data given_file('burndown-data.yaml')
+
+      expect(@chart.data["days"]).to eq @raw_data
+    end
+    
+    it "writes data" do
+      read_path = given_file('burndown-data.yaml')
+      @chart.read_data(read_path)
+
+      write_path = given_dummy_file
+      @chart.write_data(write_path)
+
+      expect(File.read(write_path)).to eq File.read(read_path)
+    end
+
+    it "doesn't write extra entries with 0 values" do
+      raw_data = [
+        {
+          "date" => '2014-04-24',
+          "story_points" =>
+          {
+            "total" => 30,
+            "open" => 21
+          },
+          "tasks" =>
+          {
+            "total" => 26,
+            "open" => 19
+          },
+          "story_points_extra" =>
+          {
+            "done" => 0
+          },
+          "tasks_extra" =>
+          {
+            "done" => 0
+          }
+        }
+      ]
+      @chart.data["days"] = raw_data
+      @chart.data["meta"]["board_id"] = "1234"
+
+      write_path = given_dummy_file
+      @chart.write_data(write_path)
+
+      expected_file_content = <<EOT
+---
+meta:
+  board_id: '1234'
+  sprint: 1
+  total_days: 10
+  weekend_lines:
+  - 3.5
+  - 8.5
+days:
+- date: '2014-04-24'
+  story_points:
+    total: 30
+    open: 21
+  tasks:
+    total: 26
+    open: 19
+EOT
+      expect(File.read(write_path)).to eq expected_file_content
+    end
+
+  end
+  
+  describe "commands" do
+    use_given_filesystem(keep_files: true)
+
+    describe "setup" do
+      it "initializes new chart" do
+        path = given_directory
+        @chart.setup(path,"myboardid")
+
+        expect(File.exist?(File.join(path,"burndown-data-01.yaml"))).to be true
+
+        chart = BurndownChart.new(@settings)
+        chart.read_data(File.join(path,"burndown-data-01.yaml"))
+
+        expect(chart.board_id).to eq "myboardid"
+      end
+    end
+    
+    describe "update" do
+      it "updates chart with latest data" do
+        card_url_match = /https:\/\/trello.com\/1\/boards\/myboardid\/cards\?-*/
+
+        stub_request(:any,card_url_match).to_return(:status => 200,
+          :body => load_test_file("cards.json"), :headers => {})
+
+        list_url_match = /https:\/\/trello.com\/1\/boards\/myboardid\/lists\?-*/
+
+        stub_request(:any,list_url_match).to_return(:status => 200,
+          :body => load_test_file("lists.json"), :headers => {})
+
+        path = given_directory_from_data("burndown_dir")
+
+        before = BurndownChart.new(@settings)
+        before.read_data(File.join(path,'burndown-data-02.yaml'))
+
+        @chart.update(path)
+
+        after = BurndownChart.new(@settings)
+        after.read_data(File.join(path,'burndown-data-02.yaml'))
+
+        expect(after.days.size).to eq before.days.size + 1
+      end
+
+      it "overwrites data on same date" do
+        card_url_match = /https:\/\/trello.com\/1\/boards\/myboardid\/cards\?-*/
+
+        stub_request(:any,card_url_match).to_return(:status => 200,
+          :body => load_test_file("cards.json"), :headers => {})
+
+        list_url_match = /https:\/\/trello.com\/1\/boards\/myboardid\/lists\?-*/
+
+        stub_request(:any,list_url_match).to_return(:status => 200,
+          :body => load_test_file("lists.json"), :headers => {})
+
+        path = given_directory_from_data("burndown_dir")
+
+        before = BurndownChart.new(@settings)
+        before.read_data(File.join(path,'burndown-data-02.yaml'))
+
+        @chart.update(path)
+        @chart.update(path)
+
+        after = BurndownChart.new(@settings)
+        after.read_data(File.join(path,'burndown-data-02.yaml'))
+
+        expect(after.days.size).to eq before.days.size + 1
+      end
+    end
+
+    describe "create_next_sprint" do
+      it "create new sprint file" do
+        path = given_directory_from_data("burndown_dir")
+        chart = BurndownChart.new(@settings)
+        chart.create_next_sprint(path)
+
+        next_sprint_file = File.join(path, "burndown-data-03.yaml")
+        expect(File.exist?(next_sprint_file)).to be true
+
+        expected_file_content = <<EOT
+---
+meta:
+  board_id: myboardid
+  sprint: 3
+  total_days: 9
+  weekend_lines:
+  - 3.5
+  - 7.5
+days: []
+EOT
+        expect(File.read(next_sprint_file)).to eq expected_file_content
+      end
+    end
+  end
+  
+end