cardigan 0.1.0 → 0.1.1

data/HISTORY.md

@@ -0,0 +1,12 @@
+# 0.1.1 (unreleased)
+
+* fixed bug - cardigan would crash when entering workflow shell if no workflow existed yet
+* fixed bug - csv import didn't use correct 1.9 csv api
+* fixed bug - import was ignoring id when a card with that id did not already exist
+* fixed bug - cards were not saved after cd unless an attribute other than name was set
+* added .cardigan file to store display and sort columns and filter
+* added direct execution of commands (to bypass entering the shell)
+* added zsh completion
+* removed support for 1.9
+* added heaps of testing
+* documentation now published to relishapp/cardigan

data/README.md

@@ -0,0 +1,126 @@
+# Cardigan
+
+A simple command line project task tracking tool.
+
+## Rationale
+
+* command line tools are faster and cooler than any gui or web interface
+* it makes sense to store work items in your source repository 
+* tab completion is awesome
+
+## Installation
+
+  gem install cardigan
+
+## Usage
+
+  cardigan
+
+This will prompt for your name and email address (and store them in ~/.cardigan), create a folder called .cards in the current directory and enter a shell.  The idea is that you will run this at the root of a git/hg/svn/whatever repository and manage the cards in the same way you manage your source code.
+
+  cardigan >
+
+So what now?
+
+## Listing mode
+
+You start in listing mode.
+
+To get the list of available commands:
+
+    ?
+
+To get help for a specific command:
+
+    ? filter
+
+Here are a few of the commands:
+
+    touch write some documentation
+
+... will create a new card called 'write some documentation'
+
+    cd write some documentation
+
+... enters edit mode for the 'write some documentation' card (note that tab completion is provided for the card name)
+
+    ls
+
+... will present a list of the current set of cards
+
+    columns name estimate
+    
+... will change the display columns to 'name' and 'estimate'
+
+    filter card['owner'] == me
+
+... will filter the list of cards to show only the ones owned by you
+
+    claim 2 4 5
+
+... assigns cards 2, 4 and 5 to you (by setting the 'owner'). Note that these numbers are the indexes presented by the 'ls' command
+
+    unclaim 4 5
+  
+... unsets the owner of cards 4 and 5
+
+    destroy 4
+
+... destroys card 4
+
+    set priority 4 6 7
+
+... prompts for a new value for the priority field on cards 4, 6 and 7
+
+    workflow
+
+... enters the workflow editing mode
+
+    count priority complexity
+
+... counts the number of cards with each value of the available combinations of priority and complexity
+
+    count estimate priority
+
+... presents the total of estimate for cards group in each value of priority
+
+    export foo
+
+... exports all cards (according to the current filter) to a csv file called foo.csv    
+
+    import foo
+
+... imports the contents of foo.csv - cards will be updated with a matching id, otherwise new cards will be created.
+
+## Editing mode
+
+* quit or exit or ctrl-d - exit
+* list - dumps the values of all card field values
+* set <key> - creates a new field and prompts for the new value
+* now <status> - changes the status of the card to the given status (the tab completion will be populated with the valid subsequent statuses from the current status)
+
+## Workflow mode
+
+Workflow is pretty simple - it is just for convenience in specifiying the set of valid transitions for cards with a specific status.
+
+The only purpose is to populate tab completion for the 'now' command in edit mode for a card.
+
+* quit or exit or ctrl-d - exit
+* list - dumps the current workflow (statuses with their valid subsequent statuses)
+* create <status> - creates a new status
+* add <status> <statuses> - add the specified statuses as valid transitions from status
+* remove <status> <statuses> - remove the specified statuses as valid transitions from status
+
+## Other tools
+
+All cardigan commands can be executed directly without entering a shell:
+
+    cardigan touch create the first card
+    cardigan touch create the second card
+    cardigan ls
+
+zsh command line completion for this can be configured by creating a symlink to the gem tools/zsh/_cardigan from one of the directories in $fpath.
+
+## Future plans
+
+Refer to the .cards for detailed story breakdown but automatic vcs interaction and generating pretty html reports/charts seem to be the most important missing features.

data/Rakefile

@@ -1,6 +1,19 @@
 require 'bundler/gem_tasks'
 
+task :default => :test
+
 desc 'execute specifications'
 task :test do
-  sh 'bundle exec rspec spec'
+  sh 'rspec spec'
+  sh 'cucumber'
+end
+
+SHARED_DOCS=%w{README HISTORY}
+
+desc "Push feature documentation to relishapp using the relish-client-gem"
+task :relish, :version do |t, args|
+  raise "rake relish[VERSION]" unless args[:version]
+  SHARED_DOCS.each {|doc| sh "cp #{doc}.md features/" }
+  sh "relish push cardigan/cardigan:#{args[:version]}"
+  SHARED_DOCS.each {|doc| sh "rm features/#{doc}.md" }
 end

data/features/commands/cd.feature

@@ -0,0 +1,24 @@
+Feature: cd
+
+  In order to manage my ideas
+  As a command line junkie
+  I want to be able to edit individual attributes of a card
+
+  The cd command is so named because within the shell, you are 'changing directory' to
+  edit a card.
+
+  Within the cardigan shell, note that 'cd' enters a nested shell (so you need to exit or
+  ctrl-d twice).
+
+  Scenario: open a card for editing
+    When I run `cardigan cd a very interesting card` interactively
+    And I type "set estimate"
+    And I type "10"
+    And I type "ls"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+    estimate: "10"
+    name: "a very interesting card"
+    """

data/features/commands/claim.feature

@@ -0,0 +1,20 @@
+Feature: claim
+
+  In order to indicate to others I am allocated to a card
+  As a command line junkie
+  I want to claim cards
+
+  Scenario: claim cards
+    When I run `cardigan touch a very interesting card`
+    And I run `cardigan claim 1`
+    And I run `cardigan columns name owner`
+    And I run `cardigan ls`
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     ---------------------------------------------------------------------
+    | index | name                    | owner                             |
+     ---------------------------------------------------------------------
+    | 1     | a very interesting card | "Ms Crazy Person" <you@there.com> |
+     ---------------------------------------------------------------------
+    """

data/features/commands/columns.feature

@@ -0,0 +1,24 @@
+Feature: columns
+
+  In order to see relevant information
+  As a command line junkie
+  I want to control the attributes that are displayed
+
+  Scenario: claim cards
+    When I run `cardigan` interactively
+    And I type "touch another interesting card"
+    And I type "set release 1"
+    And I type "ocelot"
+    And I type "set iteration 1"
+    And I type "3"
+    And I type "columns name release"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     --------------------------------------------
+    | index | name                     | release |
+     --------------------------------------------
+    | 1     | another interesting card | ocelot  |
+     --------------------------------------------
+    """

data/features/commands/count.feature

@@ -0,0 +1,66 @@
+Feature: count
+
+  In order to see relevant information
+  As a command line junkie
+  I want to count the cards that are displayed
+
+  Scenario: count total cards
+    When I run `cardigan` interactively
+    And I create the following cards:
+     | name   |
+     | card 1 |
+     | card 2 |
+    And I type "count"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     -------
+    | count |
+     -------
+    | 2     |
+     -------
+    """
+
+  Scenario: count total cards grouped by an attribute
+    When I run `cardigan` interactively
+    And I create the following cards:
+     | name   | release |
+     | card 1 | ocelot  |
+     | card 2 | ocelot  |
+     | card 3 | margay  |
+    And I type "count release"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     -----------------
+    | release | count |
+     -----------------
+    | margay  | 1     |
+    | ocelot  | 2     |
+    |         | 3     |
+     -----------------
+    """
+
+  Scenario: count total cards grouped by an attribute
+    When I run `cardigan` interactively
+    And I create the following cards:
+     | name   | release |
+     | card 1 | ocelot  |
+     | card 2 | margay  |
+     | card 3 |         |
+    And I type "count release"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     -----------------
+    | release | count |
+     -----------------
+    |         | 1     |
+    | margay  | 1     |
+    | ocelot  | 1     |
+    |         | 3     |
+     -----------------
+    """

data/features/commands/export.feature

@@ -0,0 +1,20 @@
+Feature: export
+
+  In order to interoperate with other tracking systems
+  As a command line junkie
+  I want to export my cards to csv
+
+  Scenario: export cards to csv
+    When I run `cardigan` interactively
+    And I create the following cards:
+     | name   |
+     | qwer   |
+     | asdf   |
+     | zxcv   |
+    And I type "export cards"
+    And I type "exit"
+    Then the exit status should be 0
+    And the file "cards.csv" should match /^id,name$/
+    And the file "cards.csv" should match /^\w{8}-\w{4}-\w{4}-\w{4}-\w{12},qwer$/
+    And the file "cards.csv" should match /^\w{8}-\w{4}-\w{4}-\w{4}-\w{12},asdf$/
+    And the file "cards.csv" should match /^\w{8}-\w{4}-\w{4}-\w{4}-\w{12},zxcv$/

data/features/commands/filter.feature

@@ -0,0 +1,42 @@
+Feature: filter
+
+  In order to see relevant information
+  As a command line junkie
+  I want to filter the cards that are displayed
+
+  Scenario: filter cards
+    When I run `cardigan` interactively
+    And I create the following cards:
+     | name                         | release |
+     | another interesting card     | margay  |
+     | a seriously interesting card | ocelot  |
+    And I type "filter card['release'] == 'ocelot'"
+    And I type "ls"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     --------------------------------------
+    | index | name                         |
+     --------------------------------------
+    | 1     | a seriously interesting card |
+     --------------------------------------
+    """
+
+  Scenario: filter cards by owner
+    When I run `cardigan` interactively
+    And I type "touch another interesting card"
+    And I type "touch a seriously interesting card"
+    And I type "claim 2"
+    And I type "filter card['owner'] == me"
+    And I type "ls"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     ----------------------------------
+    | index | name                     |
+     ----------------------------------
+    | 1     | another interesting card |
+     ----------------------------------
+    """

data/features/commands/import.feature

@@ -0,0 +1,32 @@
+Feature: import
+
+  In order to interoperate with other tracking systems
+  As a command line junkie
+  I want to import cards from csv
+
+  Scenario: import cards containing ids from csv
+    Given a file named "cards1.csv" with:
+    """
+    id,name,estimate
+    10,qwer,1
+    11,adsf,2
+    12,zxcv,3
+    """
+    When I run `cardigan import cards1`
+    And I run `cardigan ls`
+    And I run `cardigan export cards2`
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     --------------
+    | index | name |
+     --------------
+    | 1     | adsf |
+    | 2     | qwer |
+    | 3     | zxcv |
+     --------------
+    """
+    And the file "cards2.csv" should contain "id,estimate,name"
+    And the file "cards2.csv" should contain "10,1,qwer"
+    And the file "cards2.csv" should contain "11,2,adsf"
+    And the file "cards2.csv" should contain "12,3,zxcv"

data/features/commands/ls.feature

@@ -0,0 +1,29 @@
+Feature: ls
+
+  In order to manage my ideas
+  As a command line junkie
+  I want to list my cards
+
+  Scenario: empty card repository
+    When I run `cardigan ls`
+    Then the exit status should be 0
+    And the stdout should contain "There are no cards to display"
+
+  Scenario: a single card is added in shell
+    When I run `cardigan` interactively
+    And I create the following cards:
+     | name   |
+     | card 1 |
+     | card 2 |
+    And I type "ls"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+     ----------------
+    | index | name   |
+     ----------------
+    | 1     | card 1 |
+    | 2     | card 2 |
+     ----------------
+    """

data/features/commands/rm.feature

@@ -0,0 +1,27 @@
+Feature: rm
+
+  In order to manage my ideas
+  As a command line junkie
+  I want to be able to remove cards that are no longer required
+
+  Scenario: remove a card
+    When I run `cardigan` interactively
+    And I create the following cards:
+     | name   |
+     | card 1 |
+     | card 2 |
+     | card 3 |
+     | card 4 |
+    And I type "rm 2 3"
+    And I type "ls"
+    And I type "exit"
+    Then the exit status should be 0
+    And the stdout should contain:
+    """
+    ----------------
+    | index | name   |
+     ----------------
+    | 1     | card 1 |
+    | 2     | card 4 |
+     ----------------
+    """