pivotal-github 0.5.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'rspec', '~> 2.12.0'
+gem 'httparty', '~> 0.10.0'
+
+# Specify your gem's dependencies in pivotal-github.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Michael Hartl
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# pivotal-github
+
+**NOTE:** This gem is as-yet unreleased. 
+
+This gem facilitates a Pivotal Tracker–GitHub workflow inspired by [Logical Reality](http://lrdesign.com/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pivotal-github'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pivotal-github
+
+
+## Usage
+
+The `pivotal-github` gem adds several additional Git commands to the local environment.
+
+### 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. 
+
+For example, when on a branch called `6283185-add-markdown-support`, 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
+
+
+Here's the full usage info:
+
+	$ git story-commit -h
+	    Usage: git story-commit [options]
+	        -m, --message MESSAGE            add a commit message (including story #)
+	        -f, --finish                     mark story as finished
+	        -d, --deliver                    mark story as delivered
+	        -a, --all                        commit all changed files
+	        -h, --help                       this usage guide
+
+Additionally, `git story-commit` accepts any options valid for `git commit`.
+
+### git story-push
+
+`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
+    
+                     this usage guide
+
+`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 checkout master
+    $ git pull
+    $ git checkout 6283185-add-markdown-support
+
+The purpose of `git story-pull` it to prepare the local story branch for rebasing against `master`:
+
+    $ git story-pull
+    $ git rebase master
+
+This is essentially equivalent to 
+
+    $ git fetch
+    $ git rebase origin/master
+
+but I don't like having `master` and `origin/master` be different since it forces you to remember to run `git pull` on `master` some time down the line. 
+    
+### 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
+
+## Configuration
+
+In order to use the `pivotal-github` gem, you need to configure a [post-receive hook for Pivotal Tracker at GitHub](https://www.pivotaltracker.com/help/api?version=v3#github_hooks) for your repository. (To find your Pivotal Tracker API token, go to your user profile and scroll to the bottom.) 
+
+The `pivotal-github` command names follow the Git convention of being verbose (it's telling that, unlike Subversion, Git doesn't natively support `co` for `checkout`), but I recommend setting up aliases as necessary. Here are some suggestions:
+
+    $ git config --global alias.sc story-commit
+    $ git config --global alias.sp story-push    
+    $ git config --global alias.sl story-pull
+    $ git config --global alias.sm story-merge
+
+A single-developer workflow would then look like this:
+
+    $ git co -b 6283185-add-markdown-support
+    $ git sp
+    <work>
+    $ git sc -am "Added foo"
+    $ git push
+    <more work>
+    $ git sc -am "Added bar"
+    <complete story>
+    $ git sc -f -am "Added baz"
+    $ git push
+    $ git sl
+    $ git rebase master
+    $ git sm
+
+Note that this workflow uses `git sp` (and subsequent invocations of `git push`) only to create a remote storage backup. The principal purpose of `git story-push` is to support the integrated code review workflow described below.
+    
+## Workflow
+
+The `pivotal-github` gem is degined to support a workflow that involves integrated code review, which has the usual advantages: at least two pairs of eyes see any committed code, and at least two brains know basically what the committed code does. Here's the process in detail:
+
+### Developer #1 (Alice)
+
+1. Start an issue at [Pivotal Tracker](http://pivotaltracker.com/)
+2. Create a branch in the local Git repository containing the story number and a brief description: `git checkout -b 6283185-add-markdown-support`
+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
+4. When done with the story, add `-f` to mark the story as finished: `git story-commit -f -am "Add paragraph breaks"` 
+4. Rebase against `master` using `git story-pull` followed by `git rebase master` or `git rebase master --interactive` (optionally squashing commit messages as described in the article [A Git Workflow for Agile Teams](http://reinh.com/blog/2009/03/02/a-git-workflow-for-agile-teams.html))
+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)
+
+
+### Developer #2 (Bob)
+
+1. Review the pull request diffs
+2. If acceptable, merge the branch
+3. If not acceptable, manually change the state at Pivotal Tracker to Rejected
+4. **(experimental)** If there are conflicts, make a Chore to resolve the 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`.
+
+## Merge conflicts
+
+This section contains some suggestions for resolving merge conflicts. First, set up a visual merge tool by installing [diffmerge](http://www.sourcegear.com/diffmerge/). Then add the following to the `.gitconfig` file in your home directory:
+
+    [mergetool "diffmerge"]
+      cmd = diffmerge --merge --result=$MERGED $LOCAL $BASE $REMOTE
+      trustExitCode = false
+
+When the branch can't automatically be merged at GitHub, follow these steps:
+
+### Devleloper #1 (Alice)
+
+1. While on the story branch, run `git story-pull`
+2. Rebase against `master` with `git rebase master` **or** merge with `master` using `git merge master`
+4. Either handle resulting conflicts by hand or use the visual merge tool: `git mergetool`
+5. Commit the change: `git commit -a`
+6. Push up the modified branch: `git push`
+7. **(experimental)** Add a Chore to revisit the pull request and assign to Developer #2 (Bob) 
+
+
+Now Bob should be able to merge in the pull request automatically using the nice big green button at GitHub.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/git-story-commit

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

data/bin/git-story-merge

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+branch=`git rev-parse --abbrev-ref HEAD`
+git checkout master
+git merge $branch

data/bin/git-story-pull

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+branch=`git rev-parse --abbrev-ref HEAD`
+git checkout master
+git pull $@
+git checkout $branch

data/bin/git-story-push

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+git push $@ origin `git rev-parse --abbrev-ref HEAD`

data/lib/pivotal-github.rb

@@ -0,0 +1,4 @@
+require "pivotal-github/version"
+require "pivotal-github/options"
+require "pivotal-github/command"
+require "pivotal-github/story_commit"

data/lib/pivotal-github/command.rb

@@ -0,0 +1,52 @@
+class Command
+  attr_accessor :args, :cmd, :options, :known_options, :unknown_options
+
+  def initialize(args = [])
+    self.args = args
+    parse
+  end
+
+  def parse
+    raise "Define in derived class"
+  end
+
+  def current_branch
+    `git rev-parse --abbrev-ref HEAD`.strip
+  end
+
+  def story_id
+    current_branch.scan(/\d+/).first
+  end
+
+  def options
+    @options ||= parse
+  end
+
+  # Runs a command
+  # If the argument array contains '--debug', returns the command that would
+  # have been run
+  def self.run!(command_class, args)
+    debug = args.delete('--debug')
+    command = command_class.new(args)
+    if debug
+      puts command.cmd 
+      return 1
+    else
+      command.run!
+      return 0
+    end
+  end    
+
+  private
+
+    # Returns an argument string based on given arguments
+    # The main trick is to add in quotes for option
+    # arguments when necessary.
+    # For example, ['-a', '-m', 'foo bar'] becomes
+    # '-a -m "foo bar"'
+    def argument_string(args)
+      args.inject([]) do |opts, opt|
+        opts << (opt =~ /^-/ ? opt : opt.inspect)
+      end.join(' ')      
+    end  
+end

data/lib/pivotal-github/options.rb

@@ -0,0 +1,33 @@
+require 'optparse'
+
+module Options
+
+  # Returns a list of options unknown to a particular options parser
+  # For example, if '-a' is a known option but '-b' and '-c' are not,
+  # unknown_options(parser, ['-a', '-b', '-c']) returns ['-b', '-c'].
+  # It also preserves arguments, so 
+  # unknown_options(parser, ['-a', '-b', '-c', 'foo bar']) returns 
+  # ['-b', '-c', 'foo bar'].
+  def self.unknown_options(parser, args)
+    unknown = []                                     
+    recursive_parse = Proc.new do |arg_list|                   
+      begin
+        parser.parse!(arg_list)
+      rescue OptionParser::InvalidOption => e
+        unknown.concat(e.args)
+        while !arg_list.empty? && arg_list.first[0] != "-"
+          unknown << arg_list.shift
+        end
+        recursive_parse.call(arg_list)
+      end
+    end
+    recursive_parse.call(args.dup)
+    unknown
+  end
+
+  # Returns a list of options with unknown options removed
+  def self.known_options(parser, args)
+    unknown = unknown_options(parser, args)
+    args.reject { |arg| unknown.include?(arg) }
+  end
+end

data/lib/pivotal-github/story_commit.rb

@@ -0,0 +1,83 @@
+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|
+      opts.banner = "Usage: git story-commit [options]"
+      opts.on("-m", "--message MESSAGE",
+              "add a commit message (including story #)") do |m|
+        options.message = m
+      end
+      opts.on("-f", "--finish", "mark story as finished") do |f|
+        options.finish = f
+      end
+      opts.on("-d", "--deliver", "mark story as delivered") do |d|
+        options.deliver = d
+      end
+      opts.on("-a", "--all", "commit all changed files") do |a|
+        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
+    if story_id.nil?
+      # Arranges to fall through to regular 'git commit'
+      options.message
+    else
+      if finish?
+        label = "Finishes ##{story_id}"
+      elsif deliver?
+        label = "Delivers ##{story_id}"
+      else
+        label = "##{story_id}"
+      end
+      "[#{label}] #{options.message}"
+    end
+  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.
+  def cmd
+    c = ['git commit']
+    c << '-a' if all?
+    c << %(-m "#{message}") if message?
+    c << argument_string(unknown_options) unless unknown_options.empty?
+    c.join(' ')
+  end
+
+  def run!
+    system cmd
+  end
+
+  private
+
+    def finish?
+      options.finish
+    end
+
+    def deliver?
+      options.deliver
+    end
+
+    def message?
+      !options.message.nil?
+    end
+
+    def all?
+      options.all
+    end
+end

data/lib/pivotal-github/version.rb

@@ -0,0 +1,5 @@
+module Pivotal
+  module Github
+    VERSION = "0.5.0"
+  end
+end

data/pivotal-github.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pivotal-github/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "pivotal-github"
+  gem.version       = Pivotal::Github::VERSION
+  gem.authors       = ["Michael Hartl"]
+  gem.email         = ["michael@michaelhartl.com"]
+  gem.description   = %q{Add commands for Pivotal Tracker–GitHub integration}
+  gem.summary       = %q{See the README for full documentation}
+  gem.homepage      = "https://github.com/mhartl/pivotal-github"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/spec/commands/story_commit_spec.rb

@@ -0,0 +1,97 @@
+  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']) }
+  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
+    subject { command }
+
+    its(:cmd)      { should =~ /git commit/ }
+    its(:message)  { should_not be_empty }
+    its(:message?) { should be_true }
+    its(:all?)     { should be_true }
+
+    describe "parse" do
+      subject { command.options }
+
+      its(:message) { should == 'message' }
+      its(:all)     { should be_true }
+    end
+  end
+
+  describe "with only known options" do
+    let(:command) { StoryCommit.new(['-m', 'message', '-a']) }
+    it_should_behave_like "record with known options"
+  end
+
+  describe "with a compound argument" do
+    let(:command) { StoryCommit.new(['-am', 'message']) }
+    it_should_behave_like "record 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 not raise an error" do
+      expect { command.parse }.not_to raise_error(OptionParser::InvalidOption)
+    end
+  end
+
+  describe '#story_id' do
+    subject { command.story_id }
+    it { should == '6283185' }
+  end
+
+  describe "command with message" do
+    its(:cmd) do
+      should == %(git commit -a -m "[##{command.story_id}] message" -z --foo)
+    end
+  end
+
+  describe "command with no message" do
+    let(:command) { StoryCommit.new(['-a', '-z', '--foo']) }
+    its(:cmd) { should == %(git commit -a -z --foo) }      
+  end
+
+  describe "command with finish flag" do
+    let(:command) { StoryCommit.new(['-m', 'message', '-f']) }
+    its(:cmd) do
+      should == %(git commit -m "[Finishes ##{command.story_id}] message")
+    end      
+  end
+
+  describe "command with deliver flag" do
+    let(:command) { StoryCommit.new(['-m', 'message', '-d']) }
+    its(:cmd) do
+      should == %(git commit -m "[Delivers ##{command.story_id}] message")
+    end
+  end
+
+  describe "command with no story id" do
+    before { command.stub(:current_branch).and_return('tau-manifesto') }
+    its(:cmd) do
+      should == %(git commit -a -m "message" -z --foo)
+    end    
+  end
+
+  describe "command-line command" do
+    let(:command) { `bin/git-story-commit -a -m "message" -z --debug` }
+    subject { command }
+    it { should =~ /git commit -a -m/ }
+    it { should =~ /message/ }
+    it { should =~ /-z/ }
+    it { should_not =~ /--debug/ }
+  end
+end

data/spec/options/options_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+require 'ostruct'
+
+describe Options do
+
+  let(:options) { OpenStruct.new }
+
+  let(:parser) do
+    OptionParser.new do |opts|
+      opts.banner = "Usage: git record [options]"
+      opts.on("-m", "--message MESSAGE",
+              "add a commit message (with ticket #)") do |m| 
+        options.message = m
+      end
+      opts.on("-a", "--all", "commit all changed files") do |a|
+        options.all = a
+      end
+      opts.on("-f", "--finish", "mark story as finished") do |f|
+        options.finish = f
+      end
+      opts.on_tail("-h", "--help", "this usage guide") do
+        puts opts.to_s; exit 0
+      end
+    end    
+  end
+
+  let(:args) { ['-a', '-m', '"A message"', '--finish', '-z', '--foo', 'b ar'] }
+
+  it { should respond_to(:unknown_options) }
+  it { should respond_to(:known_options) }
+
+  describe '#unknown_options' do
+    subject { Options::unknown_options(parser, args) }
+
+    it { should     include('-z') }
+    it { should     include('--foo') }
+    it { should     include('b ar') }
+    it { should_not include('-a') }
+    it { should_not include('-m') }
+    it { should_not include('"A message"') }
+    it { should_not include('--finish') }
+  end
+
+  describe '#known_options' do
+    subject { Options::known_options(parser, args) }
+
+    it { should_not include('-z') }
+    it { should_not include('--foo') }
+    it { should_not include('b ar') }
+    it { should     include('-a') }
+    it { should     include('-m') }
+    it { should     include('"A message"') }
+    it { should     include('--finish') }  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'pivotal-github'
+
+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

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: pivotal-github
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+  prerelease: 
+platform: ruby
+authors:
+- Michael Hartl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-07 00:00:00.000000000 Z
+dependencies: []
+description: Add commands for Pivotal Tracker–GitHub integration
+email:
+- michael@michaelhartl.com
+executables:
+- git-story-commit
+- git-story-merge
+- git-story-pull
+- git-story-push
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/git-story-commit
+- bin/git-story-merge
+- bin/git-story-pull
+- bin/git-story-push
+- lib/pivotal-github.rb
+- lib/pivotal-github/command.rb
+- lib/pivotal-github/options.rb
+- lib/pivotal-github/story_commit.rb
+- lib/pivotal-github/version.rb
+- pivotal-github.gemspec
+- spec/commands/story_commit_spec.rb
+- spec/options/options_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/mhartl/pivotal-github
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: See the README for full documentation
+test_files:
+- spec/commands/story_commit_spec.rb
+- spec/options/options_spec.rb
+- spec/spec_helper.rb