pivotal-github 0.5.1 → 0.5.2

data/README.md

@@ -1,22 +1,21 @@
 # pivotal-github
 
-This gem facilitates a Pivotal Tracker–GitHub workflow inspired by [Logical Reality](http://lrdesign.com/). As per usual, there are several projects (notably [git-flow](https://github.com/nvie/gitflow) and [git-pivotal](https://github.com/trydionel/git-pivotal)) that implement similar solutions, but none met my exact needs.
+The `pivotal-github` gem facilitates a Pivotal Tracker–GitHub workflow inspired by [Logical Reality](http://lrdesign.com/). As per usual, there are several projects (notably [git-flow](https://github.com/nvie/gitflow) and [git-pivotal](https://github.com/trydionel/git-pivotal)) that implement similar solutions, but none met my exact needs.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'pivotal-github'
+    gem 'pivotal-github', '~> 0.5.0'
 
-And then execute:
+Then install the gem with Bundler:
 
-    $ bundle
+    $ bundle install
 
-Or install it yourself as:
+You can also install it directly as follows:
 
     $ gem install pivotal-github
 
-
 ## Usage
 
 The `pivotal-github` gem adds several additional Git commands to the local environment. There is only one non-trivial addition, `git story-commit`; the others are simple (tiny) bash scripts. (In fact, the current Ruby code looks over-engineered: there is a base `Command` class with only one derived class, `StoryCommit`. This is an artifact of history, as there used to be other commands, but I decided that the other cases were better served by plain bash scripts.) The `git story-commit` command automatically incorporates the Pivotal Tracker story id into the commit messages, while adding options to mark the story **Finished** or **Delivered**. 
@@ -27,7 +26,7 @@ The full set of commands is as follows:
 
 ### git story-commit
 
-`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 at GitHub. 
+`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:
 	
@@ -39,7 +38,7 @@ 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
 
-Here's the full usage info:
+#### Options
 
 	$ git story-commit -h
 	    Usage: git story-commit [options]
@@ -49,7 +48,7 @@ Here's the full usage info:
 	        -a, --all                        commit all changed files
 	        -h, --help                       this usage guide
 
-Additionally, `git story-commit` accepts any options valid for `git commit`. (`git story-commit` supports the `-a` flag so that `git story-commit -am "message"` works.)
+Additionally, `git story-commit` accepts any options valid for `git commit`. (`git story-commit` supports the `-a` flag even though that's a valid option to `git commit` so that the compound flag in `git story-commit -am "message"` works.)
 
 ### git story-push
 
@@ -58,7 +57,13 @@ Additionally, `git story-commit` accepts any options valid for `git commit`. (`g
     $ git story-push
     * [new branch]      6283185-add-markdown-support -> 6283185-add-markdown-support
 
-`git story-push` accepts any options valid for `git push`.
+#### Options
+
+	Usage: git story-push [options]
+	    -t, --target TARGET              push to a given target (defaults to origin)
+	    -h, --help                       this usage guide
+
+Additionall, `git story-push` accepts any options valid for `git push`.
 
 ### git story-pull
 
@@ -79,13 +84,35 @@ The purpose of `git story-pull` it to prepare the local story branch for rebasin
     $ git rebase origin/master
 
 but I don't like having `master` and `origin/master` be different since that means you have to remember to run `git pull` on `master` some time down the line.)
+
+#### Options
+
+    Usage: git story-pull [options]
+        -d, --development BRANCH         development branch (defaults to master)
+        -h, --help                       this usage guide
+
+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 checkout master
-    $ git merge 6283185-add-markdown-support
+    $ git merge --no-ff 6283185-add-markdown-support
+
+Note that this effectively changes the default merge behavior from fast-forward to no-fast-forward, which makes it possible to see from `git log` 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/),
+
+> The `--no-ff` flag causes the merge to always create a new commit object, even if the merge could be performed with a fast-forward. This avoids losing information about the historical existence of a feature branch and groups together all commits that together added the feature… Yes, it will create a few more (empty) commit objects, but the gain is much bigger that that cost.
+
+Because of the way options are chained, passing the option `--ff` to `git story-merge` will override the `--no-ff` flag and restore the fast-forward behavior.
+
+#### Options
+
+		Usage: git story-merge [options]
+		    -d, --development BRANCH         development branch (defaults to master)
+		    -h, --help                       this usage guide
+
+Additionally, `git story-merge` accepts any options valid for `git merge`.
 
 ## Configuration
 
@@ -134,16 +161,16 @@ Here's the process in detail:
 4. Push up with `git push`
 6. At the GitHub page for the repo, select **Branches** and submit a pull request
 7. **(experimental)** Add a story of type Chore to Pivotal Tracker and assign it to Developer #2 (Bob)
-
+8. Continue working, taking care to branch off of the current story branch if its changes are required to continue
 
 ### Developer #2 (Bob)
 
 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. **(experimental)** If the branch cannot be automatically merged, make a Chore to resolve any conflicts and assign it to Alice
+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. **(experimental)** If the branch can't be automatically merged, make a Chore to resolve any conflicts and assign it to Alice
 
-Until Bob accepts the pull request, Alice can continue working on new stories, taking care to branch off of the current branch if she needs its changes to continue. Note that the commits will appear on the story as soon as Alice creates a remote branch (and as she pushes to it), but it won't be marked **Finished** or **Delivered** until Bob merges the pull request into `master`.
+Note that the commits will appear on the story as soon as Alice creates a remote branch (and as she pushes to it), but it won't be marked **Finished** or **Delivered** until Bob merges the pull request into `master`.
 
 ## Merge conflicts
 

data/bin/git-story-merge

@@ -1,5 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'pivotal-github/story_merge'
 
-branch=`git rev-parse --abbrev-ref HEAD`
-git checkout master
-git merge $branch
+exit Command.run!(StoryMerge, ARGV.dup)

data/bin/git-story-pull

@@ -1,6 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'pivotal-github/story_pull'
 
-branch=`git rev-parse --abbrev-ref HEAD`
-git checkout master
-git pull $@
-git checkout $branch
+exit Command.run!(StoryPull, ARGV.dup)

data/bin/git-story-push

@@ -1,3 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'pivotal-github/story_push'
 
-git push $@ origin `git rev-parse --abbrev-ref HEAD`
+exit Command.run!(StoryPush, ARGV.dup)

data/bin/story-open

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'pivotal-github/story_open'
+
+exit Command.run!(StoryOpen, ARGV.dup)

data/lib/pivotal-github.rb

@@ -2,3 +2,7 @@ require "pivotal-github/version"
 require "pivotal-github/options"
 require "pivotal-github/command"
 require "pivotal-github/story_commit"
+require "pivotal-github/story_push"
+require "pivotal-github/story_pull"
+require "pivotal-github/story_merge"
+require "pivotal-github/story_open"

data/lib/pivotal-github/command.rb

@@ -1,25 +1,32 @@
+require 'optparse'
+require 'ostruct'
+require 'pivotal-github/options'
+
 class Command
   attr_accessor :args, :cmd, :options, :known_options, :unknown_options
 
   def initialize(args = [])
     self.args = args
+    self.options = OpenStruct.new
     parse
   end
 
   def parse
-    raise "Define in derived class"
+    self.known_options   = Options::known_options(parser, args)
+    self.unknown_options = Options::unknown_options(parser, args)
+    parser.parse(known_options)
   end
 
-  def current_branch
-    `git rev-parse --abbrev-ref HEAD`.strip
+  def parser
+    OptionParser.new
   end
 
-  def story_id
-    current_branch.scan(/\d+/).first
+  def story_branch
+    `git rev-parse --abbrev-ref HEAD`.strip
   end
 
-  def options
-    @options ||= parse
+  def story_id
+    story_branch.scan(/\d+/).first
   end
 
   # Runs a command

data/lib/pivotal-github/story_commit.rb

@@ -1,35 +1,27 @@
-require 'optparse'
-require 'ostruct'
-require 'pivotal-github/options'
 require 'pivotal-github/command'
 
 class StoryCommit < Command
 
-  def parse
-    options = OpenStruct.new
-    parser = OptionParser.new do |opts|
+  def parser
+    OptionParser.new do |opts|
       opts.banner = "Usage: git story-commit [options]"
       opts.on("-m", "--message MESSAGE",
               "add a commit message (including story #)") do |m|
-        options.message = m
+        self.options.message = m
       end
       opts.on("-f", "--finish", "mark story as finished") do |f|
-        options.finish = f
+        self.options.finish = f
       end
       opts.on("-d", "--deliver", "mark story as delivered") do |d|
-        options.deliver = d
+        self.options.deliver = d
       end
       opts.on("-a", "--all", "commit all changed files") do |a|
-        options.all = a
+        self.options.all = a
       end
       opts.on_tail("-h", "--help", "this usage guide") do
         puts opts.to_s; exit 0
       end
     end
-    self.known_options   =  Options::known_options(parser, args)
-    self.unknown_options = Options::unknown_options(parser, args)
-    parser.parse(known_options)
-    options
   end
 
   def message

data/lib/pivotal-github/story_merge.rb

@@ -0,0 +1,40 @@
+require 'pivotal-github/command'
+
+class StoryMerge < Command
+
+  def parser
+    OptionParser.new do |opts|
+      opts.banner = "Usage: git story-merge [options]"
+      opts.on("-d", "--development BRANCH",
+              "development branch (defaults to master)") do |opt|
+        self.options.development = opt
+      end
+      opts.on_tail("-h", "--help", "this usage guide") do
+        puts opts.to_s; exit 0
+      end
+    end
+  end
+
+  # Returns a command appropriate for executing at the command line
+  # For example:
+  #   git checkout master
+  #   git merge --no-ff <story branch>
+  def cmd
+    lines = ["git checkout #{development_branch}"]
+    c = ['git merge --no-ff']
+    c << argument_string(unknown_options) unless unknown_options.empty?
+    c << story_branch
+    lines << c.join(' ')
+    lines.join("\n")
+  end
+
+  def run!
+    system cmd
+  end
+
+  private
+
+    def development_branch
+      options.development || 'master'
+    end
+end

data/lib/pivotal-github/story_open.rb

@@ -0,0 +1,14 @@
+require 'pivotal-github/command'
+
+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}"
+  end
+
+  def run!
+    system cmd
+  end
+end

data/lib/pivotal-github/story_pull.rb

@@ -0,0 +1,41 @@
+require 'pivotal-github/command'
+
+class StoryPull < Command
+
+  def parser
+    OptionParser.new do |opts|
+      opts.banner = "Usage: git story-pull [options]"
+      opts.on("-d", "--development BRANCH",
+              "development branch (defaults to master)") do |opt|
+        self.options.development = opt
+      end
+      opts.on_tail("-h", "--help", "this usage guide") do
+        puts opts.to_s; exit 0
+      end
+    end
+  end
+
+  # Returns a command appropriate for executing at the command line
+  # For example:
+  #   git checkout master
+  #   git pull
+  #   git checkout <story branch>
+  def cmd
+    lines = ["git checkout #{development_branch}"]
+    c = ['git pull']
+    c << argument_string(unknown_options) unless unknown_options.empty?
+    lines << c.join(' ')
+    lines << ["git checkout #{story_branch}"]
+    lines.join("\n")
+  end
+
+  def run!
+    system cmd
+  end
+
+  private
+  
+    def development_branch
+      options.development || 'master'
+    end
+end

data/lib/pivotal-github/story_push.rb

@@ -0,0 +1,36 @@
+require 'pivotal-github/command'
+
+class StoryPush < Command
+
+  def parser
+    OptionParser.new do |opts|
+      opts.banner = "Usage: git story-push [options]"
+      opts.on("-t", "--target TARGET",
+              "push to a given target (defaults to origin)") do |t|
+        self.options.target = t
+      end
+      opts.on_tail("-h", "--help", "this usage guide") do
+        puts opts.to_s; exit 0
+      end
+    end
+  end
+
+  # Returns a command appropriate for executing at the command line
+  def cmd
+    c = ['git push']
+    c << argument_string(unknown_options) unless unknown_options.empty?
+    c << target
+    c << story_branch
+    c.join(' ')
+  end
+
+  def run!
+    system cmd
+  end
+
+  private
+
+    def target
+      options.target || 'origin'
+    end
+end

data/lib/pivotal-github/version.rb

@@ -1,5 +1,5 @@
 module Pivotal
   module Github
-    VERSION = "0.5.1"
+    VERSION = "0.5.2"
   end
 end

data/spec/commands/command_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe Command do
+  let(:command) { Command.new }
+  before { command.stub(:story_branch).and_return('6283185-tau-manifesto') }
+  subject { command }
+
+  it { should respond_to(:cmd) }
+  it { should respond_to(:args) }
+  it { should respond_to(:options) }
+  it { should respond_to(:parse) }
+  it { should respond_to(:story_id) }
+end

data/spec/commands/story_commit_spec.rb

@@ -1,19 +1,14 @@
-  require 'spec_helper'
+require 'spec_helper'
 
 describe StoryCommit do
 
-  before { command.stub(:current_branch).and_return('6283185-tau-manifesto') }
   let(:command) { StoryCommit.new(['-m', 'message', '-a', '-z', '--foo']) }
+  before { command.stub(:story_branch).and_return('6283185-tau-manifesto') }
   subject { command }
 
-  it { should respond_to(:cmd) }
-  it { should respond_to(:args) }
-  it { should respond_to(:options) }
-  it { should respond_to(:parse) }
   it { should respond_to(:message) }
-  it { should respond_to(:story_id) }
 
-  shared_examples "record with known options" do
+  shared_examples "story-commit with known options" do
     subject { command }
 
     its(:cmd)      { should =~ /git commit/ }
@@ -31,18 +26,18 @@ describe StoryCommit do
 
   describe "with only known options" do
     let(:command) { StoryCommit.new(['-m', 'message', '-a']) }
-    it_should_behave_like "record with known options"
+    it_should_behave_like "story-commit with known options"
   end
 
   describe "with a compound argument" do
     let(:command) { StoryCommit.new(['-am', 'message']) }
-    it_should_behave_like "record with known options"
+    it_should_behave_like "story-commit with known options"
   end
 
   describe "with some unknown options" do
     let(:command) { StoryCommit.new(['-m', 'message', '-a', '-z', '--foo']) }
     
-    it_should_behave_like "record with known options"
+    it_should_behave_like "story-commit with known options"
     
     it "should not raise an error" do
       expect { command.parse }.not_to raise_error(OptionParser::InvalidOption)
@@ -80,7 +75,7 @@ describe StoryCommit do
   end
 
   describe "command with no story id" do
-    before { command.stub(:current_branch).and_return('tau-manifesto') }
+    before { command.stub(:story_branch).and_return('tau-manifesto') }
     its(:cmd) do
       should == %(git commit -a -m "message" -z --foo)
     end    

data/spec/commands/story_merge_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe StoryMerge do
+
+  let(:command) { StoryMerge.new }
+  before { command.stub(:story_branch).and_return('6283185-tau-manifesto') }
+  subject { command }
+
+  its(:cmd) { should =~ /git merge/ }
+
+  shared_examples "story-merge with known options" do
+    subject { command }
+    it "should not raise an error" do
+      expect { command.parse }.not_to raise_error(OptionParser::InvalidOption)
+    end
+  end
+
+  describe "with no options" do
+    its(:cmd) { should =~ /git checkout master/ }
+    its(:cmd) { should =~ /git merge --no-ff #{command.story_branch}/ }
+  end
+
+  describe "with a custom development branch" do
+    let(:command) { StoryPull.new(['-d', 'develop']) }
+    its(:cmd) { should =~ /git checkout develop/ }
+  end
+
+  describe "with some unknown options" do
+    let(:command) { StoryPull.new(['-d', 'develop', '-a', '-z', '--foo']) }
+    it_should_behave_like "story-merge with known options"
+    its(:cmd) { should =~ /git pull -a -z --foo/ }
+  end
+
+  describe "command-line command" do
+    subject { `bin/git-story-merge --debug -ff -d develop` }
+    it { should =~ /git checkout develop/ }
+    it { should =~ /git merge --no-ff -ff/ }
+  end
+end

data/spec/commands/story_open_spec.rb

@@ -0,0 +1,16 @@
+require 'spec_helper'
+
+describe StoryOpen do
+
+  let(:command) { StoryOpen.new }
+  let(:uri) { "https://www.pivotaltracker.com/story/show/#{command.story_id}" }
+  before { command.stub(:story_branch).and_return('6283185-tau-manifesto') }
+  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

data/spec/commands/story_push_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe StoryPush do
+
+  let(:command) { StoryPush.new }
+  before { command.stub(:story_branch).and_return('6283185-tau-manifesto') }
+  subject { command }
+
+  its(:cmd) { should =~ /git push/ }
+
+  shared_examples "story-push with known options" do
+    subject { command }
+    it "should not raise an error" do
+      expect { command.parse }.not_to raise_error(OptionParser::InvalidOption)
+    end
+  end
+
+  describe "with no options" do
+    its(:cmd) { should == "git push origin #{command.story_branch}" }
+  end
+
+  describe "with a target option" do
+    let(:command) { StoryPush.new(['-t', 'heroku']) }
+    its(:cmd) { should =~ /git push heroku/ }
+  end
+
+  describe "with some unknown options" do
+    let(:command) { StoryPush.new(['-p', 'develop', '-a', '-z', '--foo']) }
+    it_should_behave_like "story-push with known options"
+    its(:cmd) { should =~ /-a -z --foo/ }
+  end
+
+  describe "command-line command" do
+    subject { `bin/git-story-push --debug -z -t heroku` }
+    it { should =~ /git push -z heroku/ }
+  end
+end

data/spec/options/story_pull_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+
+describe StoryPull do
+
+  let(:command) { StoryPull.new }
+  before { command.stub(:story_branch).and_return('6283185-tau-manifesto') }
+  subject { command }
+
+  its(:cmd) { should =~ /git pull/ }
+
+  shared_examples "story-pull with known options" do
+    subject { command }
+    it "should not raise an error" do
+      expect { command.parse }.not_to raise_error(OptionParser::InvalidOption)
+    end
+  end
+
+  describe "with no options" do
+    its(:cmd) { should =~ /git checkout master/ }
+    its(:cmd) { should =~ /git pull/ }
+    its(:cmd) { should =~ /git checkout #{command.story_branch}/ }
+  end
+
+  describe "with a custom development branch" do
+    let(:command) { StoryPull.new(['-d', 'develop']) }
+    its(:cmd) { should =~ /git checkout develop/ }
+  end
+
+  describe "with some unknown options" do
+    let(:command) { StoryPull.new(['-d', 'develop', '-a', '-z', '--foo']) }
+    it_should_behave_like "story-pull with known options"
+    its(:cmd) { should =~ /git pull -a -z --foo/ }
+  end
+
+  describe "command-line command" do
+    subject { `bin/git-story-pull --debug -z -d develop` }
+    it { should =~ /git checkout develop/ }
+    it { should =~ /git pull -z/ }
+  end
+end

data/spec/spec_helper.rb

@@ -4,6 +4,4 @@ RSpec.configure do |config|
   config.treat_symbols_as_metadata_keys_with_true_values = true
   config.run_all_when_everything_filtered = true
   config.filter_run :focus
-
-
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pivotal-github
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-07 00:00:00.000000000 Z
+date: 2013-02-08 00:00:00.000000000 Z
 dependencies: []
 description: Add commands for Pivotal Tracker–GitHub integration
 email:
@@ -19,6 +19,7 @@ executables:
 - git-story-merge
 - git-story-pull
 - git-story-push
+- story-open
 extensions: []
 extra_rdoc_files: []
 files:
@@ -32,14 +33,24 @@ files:
 - bin/git-story-merge
 - bin/git-story-pull
 - bin/git-story-push
+- bin/story-open
 - lib/pivotal-github.rb
 - lib/pivotal-github/command.rb
 - lib/pivotal-github/options.rb
 - lib/pivotal-github/story_commit.rb
+- lib/pivotal-github/story_merge.rb
+- lib/pivotal-github/story_open.rb
+- lib/pivotal-github/story_pull.rb
+- lib/pivotal-github/story_push.rb
 - lib/pivotal-github/version.rb
 - pivotal-github.gemspec
+- spec/commands/command_spec.rb
 - spec/commands/story_commit_spec.rb
+- spec/commands/story_merge_spec.rb
+- spec/commands/story_open_spec.rb
+- spec/commands/story_push_spec.rb
 - spec/options/options_spec.rb
+- spec/options/story_pull_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/mhartl/pivotal-github
 licenses: []
@@ -66,6 +77,11 @@ signing_key:
 specification_version: 3
 summary: See the README for full documentation
 test_files:
+- spec/commands/command_spec.rb
 - spec/commands/story_commit_spec.rb
+- spec/commands/story_merge_spec.rb
+- spec/commands/story_open_spec.rb
+- spec/commands/story_push_spec.rb
 - spec/options/options_spec.rb
+- spec/options/story_pull_spec.rb
 - spec/spec_helper.rb