pivotal-github 0.6.14 → 0.7.0

data/README.md

@@ -11,9 +11,9 @@ You can install the `pivotal-github` gem directly as follows:
 
 ## Usage
 
-The `pivotal-github` gem adds several additional Git commands to the local environment. The main addition, `git story-commit`, automatically incorporates the Pivotal Tracker story id into the commit messages, while adding options to mark the story **Finished** or **Delivered**. 
+The `pivotal-github` gem adds several additional Git commands to the local environment. The main addition, `git story-commit`, automatically incorporates the Pivotal Tracker story id(s) into the commit messages, while adding options to mark the story **Finished** or **Delivered**. 
 
-The `git story-commit` command makes the assumption that the first string of digits in the branch name is the story id. This means that, when the story id is `6283185`, the branch names `6283185-add-markdown-support`, `6283185_add_markdown_support`, and `add-markdown-support-6283185` all work, but `add-42-things-6283185` doesn't.
+The `git story-commit` command makes the assumption that any string of digits in the branch name is a story id. This means that, when the story id is `6283185`, the branch names `6283185-add-markdown-support`, `6283185_add_markdown_support`, and `add-markdown-support-6283185` all correspond to story id `6283185`, while `add-things-6283185-3141592` corresponds to both `6283185` *and* `3141592`.
 
 The full set of commands is as follows:
 
@@ -21,15 +21,29 @@ The full set of commands is as follows:
 
 `git story-commit` makes a standard `git commit` with the story number added to the commit message. This automatically adds a link at Pivotal Tracker between the story and the diff when the branch gets pushed up to GitHub. 
 
-For example, when on a branch called `6283185-add-markdown-support`, the `git story-commit` command automatically adds `[#6283185]` to the commit message:
+For example, when on a branch called `add-markdown-support-6283185`, the `git story-commit` command automatically adds `[#6283185]` to the commit message:
 	
     $ git story-commit -am "Add foo bars"
-	[6283185-add-markdown-support 6f56414] [#6283185] Add foo bars
+	[add-markdown-support-6283185 6f56414] [#6283185] Add foo bars
 
 To mark a story as **Finished**, add the `-f` flag:
 
     $ git story-commit -f -am "Remove baz quuxes"
-	[6283185-add-markdown-support 7g56429] [Finishes #6283185] Remove baz quuxes
+	[add-markdown-support-6283185 7g56429] [Finishes #6283185] Remove baz quuxes
+
+To mark a story as **Delivered**, add the `-d` flag:
+
+    $ git story-commit -d -am "Remove baz quuxes"
+	[add-markdown-support-6283185 7g56429] [Delivers #6283185] Remove baz quuxes
+
+Either the `-f` flag or the `-d` flag can be combined with other flags, yielding commands like
+
+    $ git story-commit -dam "Remove baz quuxes"
+
+`git story commit` supports multiple story numbers as well. For example, with a branch called `add-things-6283185-3141592`, we could deliver both stories as follows 
+
+    $ git story-commit -dam "Remove baz quuxes"
+	[add-things-6283185-3141592 7g56429] [Delivers #6283185 #3141592] Remove baz quuxes
 
 #### Options
 
@@ -48,7 +62,7 @@ Additionally, `git story-commit` accepts any options valid for `git commit`. (`g
 `git story push` creates a remote branch at `origin` with the name of the current branch:
 
     $ git story-push
-    * [new branch]      6283185-add-markdown-support -> 6283185-add-markdown-support
+    * [new branch]      add-markdown-support-6283185 -> add-markdown-support-6283185
 
 #### Options
 
@@ -60,11 +74,11 @@ Additionall, `git story-push` accepts any options valid for `git push`.
 
 ### git story-pull
 
-`git story-pull` syncs the local `master` with the remote `master`. On a branch called `6283185-add-markdown-support`, `git story-pull` is equivalent to the following:
+`git story-pull` syncs the local `master` with the remote `master`. On a branch called `add-markdown-support-6283185`, `git story-pull` is equivalent to the following:
 
     $ git checkout master
     $ git pull
-    $ git checkout 6283185-add-markdown-support
+    $ git checkout add-markdown-support-6283185
 
 The purpose of `git story-pull` is to prepare the local story branch for rebasing against `master`:
 
@@ -99,10 +113,10 @@ Additionally, `git story-pull` accepts any options valid for `git pull`.
     
 ### git story-merge
 
-`git story-merge` merges the current branch into `master`. On a branch called `6283185-add-markdown-support`, `git story-merge` is equivalent to the following: 
+`git story-merge` merges the current branch into `master`. On a branch called `add-markdown-support-6283185`, `git story-merge` is equivalent to the following: 
 
     $ git checkout master
-    $ git merge --no-ff --log 6283185-add-markdown-support
+    $ git merge --no-ff --log add-markdown-support-6283185
 
 Note that this effectively changes the default merge behavior from fast-forward to no-fast-forward, which makes it possible to use `git log` to see which of the commit objects together have implemented a story. As noted in [A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/),
 
@@ -149,9 +163,9 @@ The `story-open` command (without `git`) opens the current story in the default
 
 ## Configuration
 
-In order to use the `pivotal-github` gem, you need to configure a post-receive hook for your repository. At GitHub, navigate to `Settings > Service Hooks > Pivotal Tracker` and past in your Pivotal Tracker API token. (To find your Pivotal Tracker API token, go to your user profile and scroll to the bottom.) Be sure to check the **Active** box to activate the post-receive hook. At BitBucket, click on the gear icon to view the settings, click on `Services`, select `Pivotal Tracker`, and paste in your Pivotal Tracker API key.
+In order to use the `pivotal-github` gem, you need to configure a post-receive hook for your repository. At GitHub, navigate to `Settings > Service Hooks > Pivotal Tracker` and paste in your Pivotal Tracker API token. (To find your Pivotal Tracker API token, go to your user profile and scroll to the bottom.) Be sure to check the **Active** box to activate the post-receive hook. At BitBucket, click on the gear icon to view the settings, click on `Services`, select `Pivotal Tracker`, and paste in your Pivotal Tracker API key.
 
-The `pivotal-github` command names follow the Git convention of being verbose (e.g., unlike Subversion, Git doesn't natively support `co` for `checkout`), but I recommend setting up aliases as necessary. Here are some suggestions:
+The `pivotal-github` command names follow the Git convention of being verbose (e.g., unlike Subversion, Git doesn't natively support `co` for `checkout`), but I recommend setting up aliases as necessary. Here are some suggestions, formatted so that they can be pasted directly into a terminal window:
 
     git config --global alias.sc story-commit
     git config --global alias.sp story-push    
@@ -161,7 +175,7 @@ The `pivotal-github` command names follow the Git convention of being verbose (e
 
 A single-developer workflow would then look like this:
 
-    $ git co -b 6283185-add-markdown-support
+    $ git co -b add-markdown-support-6283185
     $ git sp
     <work>
     $ git sc -am "Added foo"
@@ -186,7 +200,7 @@ Here's the process in detail:
 ### Developer #1 (Alice)
 
 1. Start an issue at [Pivotal Tracker](http://pivotaltracker.com/) and copy the story id to your buffer
-2. Create a branch in the local Git repository containing the story id and a brief description: `git checkout -b 6283185-add-markdown-support`
+2. Create a branch in the local Git repository containing the story id and a brief description: `git checkout -b add-markdown-support-6283185`
 3. Create a remote branch at [GitHub](http://github.com/) using `git story-push`
 3. Use `git story-commit` to make commits, which includes the story number in the commit message: `git story-commit -am "Add syntax highlighting"`
 4. Continue pushing up after each commit using `git push` as usual
@@ -196,7 +210,7 @@ Here's the process in detail:
 6. At the GitHub page for the repo, select **Branches** and submit a pull request
 6. (On OS X, replace the previous two steps with `git story-pull-request`)
 6. Assign the pull request to Bob at GitHub
-7. On the Pivotal Tracker story, change the **Owner** to Developer #2 (Bob) and add a comment with the pull request URL
+7. On the Pivotal Tracker story, add a comment with the pull request URL
 8. Continue working, taking care to branch off of the current story branch if its changes are required to continue
 
 Rather than immediately submitting a pull request, Alice can also continue by branching off the previous story branch, working on a set of related features, and then issue Bob a pull request for the final branch when she reaches a natural stopping place.
@@ -207,7 +221,13 @@ Rather than immediately submitting a pull request, Alice can also continue by br
 1. Select **Pull Requests** at GitHub and review the pull request diffs
 2. If acceptable, merge the branch by clicking on the button at GitHub
 3. If not acceptable, manually change the state at Pivotal Tracker to **Rejected** and leave a note (at GitHub or at Pivotal Tracker) indicating the reason
-4. If the branch can't be automatically merged, mark the story as **Rejected** and change the **Owner** back to Alice
+4. If the branch can't be automatically merged, mark the story as **Rejected**
+
+### Developer #1 (Alice)
+
+1. After getting the GitHub notification that the pull request has been merged, mark the Pivotal Tracker story finished. (In principle, Bob could do this, but Alice probably knows the PR-to-story mapping better than Bob, and experience shows that it is difficult for Bob to remember to update Pivotal Tracker after accepting the pull request.)
+2. If the pull request was rejected, make the necessary changes and follow the previous steps above.
+
 
 ## Merge conflicts
 

data/lib/pivotal-github/command.rb

@@ -25,8 +25,19 @@ class Command
     `git rev-parse --abbrev-ref HEAD`.strip
   end
 
+  # Returns the story id (or ids).
+  # We extract the story id(s) from the branch name, so that, e.g.,
+  # the branch `add-markdown-support-6283185` gives story_id '6283185'.
+  # New as of version 0.7, we support multiple story ids in a single 
+  # branch name, so that `add-markdown-support-6283185-3141592` can be used
+  # to update story 6283185 and story 3141592 simultaneously.
+  def story_ids
+    story_branch.scan(/\d+/)
+  end
+
+  # Returns the single story id for the common case of one id.
   def story_id
-    story_branch.scan(/\d+/).first
+    story_ids.first
   end
 
   # Runs a command.

data/lib/pivotal-github/story_commit.rb

@@ -25,21 +25,29 @@ class StoryCommit < Command
   end
 
   def message
-    if story_id.nil?
+    if story_ids.empty?
       # Arranges to fall through to regular 'git commit'
       options.message
     else
       if finish?
-        label = "Finishes ##{story_id}"
+        label = "Finishes #{message_ids}"
       elsif deliver?
-        label = "Delivers ##{story_id}"
+        label = "Delivers #{message_ids}"
       else
-        label = "##{story_id}"
+        label = message_ids
       end
       "[#{label}] #{options.message}"
     end
   end
 
+  # Returns the story ids formatted for story commits.
+  # For single-id stories, this is just the number preceded by '#', as in
+  # '#6283185'. For multiple-id stories, each story id is precede by '#', as in
+  # '#6283185 #3141592'
+  def message_ids
+    story_ids.map { |id| "##{id}" }.join(' ')
+  end
+
   # Returns a command appropriate for executing at the command line.
   # We take care to insert the story number and, if necessary, an indication
   # that the commit finishes the story.

data/lib/pivotal-github/story_open.rb

@@ -5,7 +5,9 @@ class StoryOpen < Command
   # Returns a command appropriate for executing at the command line
   # I.e., 'open https://www.pivotaltracker.com/story/show/6283185'
   def cmd
-    "open https://www.pivotaltracker.com/story/show/#{story_id}"
+    story_ids.map do |id|
+      "open https://www.pivotaltracker.com/story/show/#{id}"
+    end.join(' ; ')
   end
 
   def run!

data/lib/pivotal-github/version.rb

@@ -1,5 +1,5 @@
 module Pivotal
   module Github
-    VERSION = "0.6.14"
+    VERSION = "0.7.0"
   end
 end

data/spec/commands/command_spec.rb

@@ -9,5 +9,13 @@ describe Command do
   it { should respond_to(:args) }
   it { should respond_to(:options) }
   it { should respond_to(:parse) }
-  it { should respond_to(:story_id) }
+  it { should respond_to(:story_ids) }
+  its(:story_ids) { should eq ['6283185']}
+
+  describe "branches with multiple stories" do
+    before do
+      command.stub(:story_branch).and_return('6283185-tau-manifesto-3141592')
+    end
+    its(:story_ids) { should eq ['6283185', '3141592'] }
+  end
 end

data/spec/commands/story_commit_spec.rb

@@ -53,6 +53,16 @@ describe StoryCommit do
     its(:cmd) do
       should == %(git commit -a -m "[##{command.story_id}] message" -z --foo)
     end
+
+    describe "when used with branches containing multiple stories" do
+      before do
+        command.stub(:story_branch).and_return('6283185-tau-manifesto-3141592')
+      end
+      its(:cmd) do
+        delivered_ids = '#6283185 #3141592'
+        should == %(git commit -a -m "[#{delivered_ids}] message" -z --foo)
+      end
+    end
   end
 
   describe "command with no message" do
@@ -65,6 +75,16 @@ describe StoryCommit do
     its(:cmd) do
       should == %(git commit -m "[Finishes ##{command.story_id}] message")
     end      
+
+    describe "when used with branches containing multiple stories" do
+      before do
+        command.stub(:story_branch).and_return('6283185-tau-manifesto-3141592')
+      end
+      its(:cmd) do
+        delivered_ids = '#6283185 #3141592'
+        should == %(git commit -m "[Finishes #{delivered_ids}] message")
+      end
+    end
   end
 
   describe "command with deliver flag" do
@@ -72,6 +92,16 @@ describe StoryCommit do
     its(:cmd) do
       should == %(git commit -m "[Delivers ##{command.story_id}] message")
     end
+
+    describe "when used with branches containing multiple stories" do
+      before do
+        command.stub(:story_branch).and_return('6283185-tau-manifesto-3141592')
+      end
+      its(:cmd) do
+        delivered_ids = '#6283185 #3141592'
+        should == %(git commit -m "[Delivers #{delivered_ids}] message")
+      end
+    end
   end
 
   describe "command with no story id" do

data/spec/commands/story_open_spec.rb

@@ -8,9 +8,4 @@ describe StoryOpen do
   subject { command }
 
   its(:cmd) { should == "open #{uri}" }
-
-  describe "command-line command" do
-    subject { `bin/story-open --debug` }
-    it { should =~ /open https:\/\/www.pivotaltracker.com\/story\/show/ }
-  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pivotal-github
 version: !ruby/object:Gem::Version
-  version: 0.6.14
+  version: 0.7.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-25 00:00:00.000000000 Z
+date: 2013-05-26 00:00:00.000000000 Z
 dependencies: []
 description: Add commands for Pivotal Tracker-GitHub integration
 email: