git_workflow 0.0.5

data/README.markdown

@@ -0,0 +1,77 @@
+Git Workflow Tools
+==================
+These are a set of [git](http://git-scm.org/) extensions to integrate with [Pivotal Tracker](http://www.pivotaltracker.com/).
+
+* `git workflow-setup` configures your environment appropriately
+* `git start` starts a new branch with an associated PT story
+* `git finish` finishes the current, or given, branch and associated PT story
+
+Usage
+-----
+First you run `git workflow-setup` and follow the instructions.
+
+If you want to start a PT story all you need to do is:
+
+  `git start NNNNNN`
+
+Where `NNNNNN` is the PT story number.
+
+When you have finished it your can either do:
+
+  `git finish`
+
+If you're on a branch you want to mark as finished, or:
+
+  `git finish NNNNNN`
+
+To finish the story `NNNNNN`.
+
+Settings
+--------
+They require certain git configuration settings, either globally or on the project:
+
+* `user.name`                       your name as it appears on PT
+* `pt.username`                     your name as it appears on PT (only required if `user.name` is not correct)
+* `pt.token`                        your PT API token (find it on your [PT Profile](https://www.pivotaltracker.com/profile) page)
+* `pt.projectid`                    the PT ID for your project (the number from the PT URL)
+* `workflow.localbranchconvention`  used to generate the name of the local branch
+* `workflow.remotebranchconvention` used to generate the name of the remote branch
+* `workflow.callbacks`              the style of interaction you have with git
+
+You are *strongly* advised to use `git workflow-setup` to configure these settings.
+
+Obviously these settings can be set globally (`user.name`, `pt.username` and `pt.token` are good candidates for this) or at the individual git repository level.  It is highly recommended that `pt.projectid` be set on a per-project basis, obviously.  Remember that if these are set in the project then they override the global settings, which can be useful if you work with several different PT accounts across several different projects.
+
+Callbacks/Hooks
+---------------
+The behaviour of what happens when you issue `git start` or `git finish` is driven by hooks.  At the moment there a couple of forms of hooks included in the code:
+
+* `default`     creates a branch or merges a branch
+* `debug`       built on top of `default`, this simply adds more debugging output
+* `mine`        performs the steps I use for this (and other) projects
+* `sanger`      performs the steps used by Production Software at [The Wellcome Trust Sanger Institute](http://www.sanger.ac.uk/)
+
+The workflow for `sanger` is easy to describe:
+
+* `git start`   creates a branch from the head of master and marks the PT story started
+* `git finish`  runs `rake test features` and the pushes the branch to the remote repository
+
+My workflow, used by `mine`, is a little more complex:
+
+* `git start`   creates a branch from the head of master and marks the PT story started
+* `git finish`  runs `rake spec features`, merges the branch into master, runs `rake spec features`, then pushes master to the remote repository
+
+Should the `rake` steps fail for either of these workflows then the subsequent steps are not performed, i.e. the branch won't be pushed for `git finish` if `sanger` is being used.
+
+Branch conventions
+------------------
+The idea for `workflow.localbranchconvention` and `workflow.remotebranchconvention` is that you can have your personal preference for naming branches in your local repository, and a common format for the branch names in the remote repository.  For instance, I might have story ID followed by title as a local convention, you might have the reverse, and the remote repository might have a completely different convention.
+
+The two branch convention settings are freeform text with substitutions.  Values that can be substituted are:
+
+* `number` is the PT story number for the story
+* `name`   is the name of the PT story
+
+For instance, "`${number}_${name}`" will generate a branch of the form `12345_some_new_feature`, if this is for story 12345 and that story has the name 'Some new feature'.  The final branch will have non-alphanumeric characters replaced by underscore.
+
+*WARNING:* I've not properly tested this with other information being placed inside the convention settings, so you're on your own if you try something different!  The `git workflow-setup` command will only choose between the two possible combinations.

data/Rakefile

@@ -0,0 +1,33 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup(:build, :test)
+
+require 'rake'
+
+require 'yard'
+
+YARD::Rake::YardocTask.new do |rd|
+  rd.files   = [ 'README.markdown', 'lib/**/*.rb' ]
+  rd.options = [ '-o', 'doc' ]
+end
+
+require 'spec/rake/spectask'
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList[ 'spec/**/*_spec.rb' ]
+end
+
+require 'cucumber'
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new(:features) do |t|
+  options, features = [ '--format pretty' ], 'features'
+  options << "--tags '#{ ENV['tags'] }'" unless ENV['tags'].nil? or ENV['tags'].empty?
+  unless ENV['FEATURE'].nil? or ENV['FEATURE'].empty?
+    features = ENV['FEATURE'] 
+    options << '-r features/step_definitions'
+    options << '-r features/support'
+  end
+
+  t.cucumber_opts = "#{ options.join(' ') } '#{ features }'"
+end

data/bin/git-finish

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'git_workflow'
+
+GitWorkflow::Commands::Finish.new(ARGV).execute

data/bin/git-start

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'git_workflow'
+
+GitWorkflow::Commands::Start.new(ARGV).execute

data/bin/git-workflow-setup

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'git_workflow'
+
+GitWorkflow::Commands::Setup.new(ARGV).execute

data/features/core_functionality/4049578_need_the_ability_to_start_a_new_branch.feature

@@ -0,0 +1,15 @@
+# rake features FEATURE=features/core_functionality/4049578_need_the_ability_to_start_a_new_branch.feature
+@core_functionality @needs_service
+Feature: Need the ability to start a new branch
+
+  Scenario: Starting a new branch
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4049578 exists
+    And the name of story 4049578 is "Need the ability to start a new branch"
+
+    When I successfully execute "git start 4049578"
+
+    Then the branch "4049578_need_the_ability_to_start_a_new_branch" should be active
+    And the owner of story 4049578 should be "Matthew Denner"
+    And story 4049578 should be started

data/features/core_functionality/4049611_need_the_ability_to_finish_a_specified_branch.feature

@@ -0,0 +1,17 @@
+# rake features FEATURE=features/core_functionality/4049611_need_the_ability_to_finish_a_specified_branch.feature
+@core_functionality @needs_service
+Feature: Need the ability to finish a specified branch
+  Scenario: Finishing an existing branch
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4049611 exists
+    And the name of story 4049611 is "Need the ability to start a new branch"
+
+    Given the local branch "4049611_need_the_ability_to_start_a_new_branch" exists
+
+    When I successfully execute "git finish 4049611"
+
+    Then the branch "4049611_need_the_ability_to_start_a_new_branch" should be merged into master
+    And the owner of story 4049611 should be "Matthew Denner"
+    And story 4049611 should be finished
+

data/features/core_functionality/4056359_start_with_local_branch_already_present.feature

@@ -0,0 +1,16 @@
+# rake features FEATURE=features/core_functionality/4056359_start_with_local_branch_already_present.feature
+@core_functionality @needs_service
+Feature: Start with local branch already present
+  Scenario: The branch already exists
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4056359 exists
+    And the name of story 4056359 is "Start with local branch already present"
+
+    Given the local branch "4056359_start_with_local_branch_already_present" exists
+    
+    When I successfully execute "git start 4056359"
+
+    Then the branch "4056359_start_with_local_branch_already_present" should be active
+    And the owner of story 4056359 should be "Matthew Denner"
+    And story 4056359 should be started

data/features/core_functionality/4056363_finish_the_current_branch.feature

@@ -0,0 +1,17 @@
+# rake features FEATURE=features/core_functionality/4056363_finish_the_current_branch.feature
+@core_functionality @needs_service
+Feature: Finish the current branch
+  Scenario: When executed on the branch
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4056363 exists
+    And the name of story 4056363 is "Finish the current branch"
+
+    Given the local branch "4056363_finish_the_current_branch" exists
+    And the local branch "4056363_finish_the_current_branch" is active
+
+    When I successfully execute "git finish"
+
+    Then the branch "4056363_finish_the_current_branch" should be merged into master
+    And the owner of story 4056363 should be "Matthew Denner"
+    And story 4056363 should be finished

data/features/core_functionality/4056389_changes_to_pt_story_name_cause_branch_issues.feature

@@ -0,0 +1,25 @@
+# rake features FEATURE=features/core_functionality/4056389_changes_to_pt_story_name_cause_branch_issues.feature
+@core_functionality @needs_service
+Feature: Changing the name of a story
+  Background:
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4056389 exists
+    And the name of story 4056389 is "PT story name changes screws with branches"
+
+    Given the local branch "4056389_changes_to_pt_story_name_cause_branch_issues" exists
+
+  Scenario: Name changed after the story has started
+    When I successfully execute "git finish 4056389"
+
+    Then the branch "4056389_changes_to_pt_story_name_cause_branch_issues" should be merged into master
+    And the owner of story 4056389 should be "Matthew Denner"
+    And story 4056389 should be finished
+
+  Scenario: Name changed and trying to start it
+    When I successfully execute "git start 4056389"
+
+    Then the branch "4056389_changes_to_pt_story_name_cause_branch_issues" should be active
+    And the owner of story 4056389 should be "Matthew Denner"
+    And story 4056389 should be started
+

data/features/core_functionality/4135658_control_output_verbosity_using_v_switch.feature

@@ -0,0 +1,32 @@
+# rake features FEATURE=features/core_functionality/4135658_control_output_verbosity_using_v_switch.feature
+@core_functionality @needs_service @command_line
+Feature: Command line option parsing
+  Background:
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4135658 exists
+    And the name of story 4135658 is "Need the ability to start a new branch"
+
+    Given the local branch "4135658_control_output_verbosity_using_v_switch" exists
+
+  Scenario Outline: Usage displayed for --help
+    When I execute "git <command> --help"
+    Then the output should contain "Usage: git <command>"
+
+    Examples:
+      |command|
+      | start |
+      |finish |
+
+  Scenario Outline: Verbose output for --verbose
+    When I execute "git <command> 4135658"
+    Then the output should not contain "DEBUG"
+
+    When I execute "git <command> --verbose 4135658"
+    Then the output should contain "DEBUG"
+
+    Examples:
+      |command|
+      | start |
+      |finish |
+

data/features/core_functionality/4468313_get_config_value_for_is_producing_an_error_log.feature

@@ -0,0 +1,43 @@
+# rake features FEATURE=features/core_functionality/4468313_get_config_value_for_is_producing_an_error_log.feature
+@core_functionality @needs_service
+Feature: Separate the various logging information
+  Background:
+    # Note that this background does not set pt.username and uses user.name instead.
+    # Notice that this means that this will be reported with verbosity enable, but not
+    # without it.
+    Given my git username is "Matthew Denner"
+    And my Pivotal Tracker project ID is 93630
+    And my Pivotal Tracker token is 1234567890
+    And my local branch naming convention is "${number}_${name}"
+    And my remote branch naming convention is "${number}_${name}"
+
+    Given the story 4468313 exists
+    And the name of story 4468313 is "'get_config_value_for' is producing an error log"
+
+  Scenario: Starting a branch
+    When I successfully execute "git start 4468313"
+
+    Then the output should not contain "pt.username"
+    And the output should not contain "DEBUG"
+
+  Scenario: Finishing a branch
+    Given the local branch "4468313_get_config_value_for_is_producing_an_error_log" exists
+
+    When I successfully execute "git finish 4468313"
+
+    Then the output should not contain "pt.username"
+    And the output should not contain "DEBUG"
+
+  Scenario: Starting a branch with verbosity
+    When I successfully execute "git start --verbose 4468313"
+
+    Then the stderr should contain "pt.username"
+    And the stdout should not contain "pt.username"
+
+  Scenario: Finishing a branch with verbosity
+    Given the local branch "4468313_get_config_value_for_is_producing_an_error_log" exists
+
+    When I successfully execute "git finish --verbose 4468313"
+
+    Then the stderr should contain "pt.username"
+    And the stdout should not contain "pt.username"

data/features/extensions/4058326_display_story_description_on_start.feature

@@ -0,0 +1,14 @@
+# rake features FEATURE=features/extensions/4058326_display_story_description_on_start.feature
+@extension @needs_service
+Feature: Display the story description on start
+  Scenario: Displaying the description
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4058326 exists
+    And the name of story 4058326 is "Display the story description"
+    And the description of story 4058326 is "Please can we display the description of a story?"
+
+    When I successfully execute "git start 4058326"
+
+    Then the stdout should contain "Story 4058326: Display the story description"
+    And the stdout should contain "Please can we display the description of a story?"

data/features/git_branching/4135501_allow_branch_start_point_to_be_specified_from_command_line.feature

@@ -0,0 +1,27 @@
+# rake features FEATURE=features/git_branching/4135501_allow_branch_start_point_to_be_specified_from_command_line.feature
+@git_branching @needs_service
+Feature: Branching from a branch
+  Background:
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4135501 exists
+    And the name of story 4135501 is "Allow branch start point to be specified from command line"
+
+    Given the local branch "parent_branch" exists
+    And the local branch "parent_branch" is active
+    And an empty file named "I am empty"
+    And I commit "I am empty"
+
+  Scenario: When the user is on master and specifies the branch
+    And the local branch "master" is active
+
+    When I successfully execute "git start 4135501 parent_branch"
+
+    Then the branch "4135501_allow_branch_start_point_to_be_specified_from_command_line" should be active
+    And the parent of branch "4135501_allow_branch_start_point_to_be_specified_from_command_line" should be "parent_branch"
+
+  Scenario: When the user is on the parent branch and doesn't specify one
+    When I successfully execute "git start 4135501"
+
+    Then the branch "4135501_allow_branch_start_point_to_be_specified_from_command_line" should be active
+    And the parent of branch "4135501_allow_branch_start_point_to_be_specified_from_command_line" should be "parent_branch"

data/features/hooks/4069174_investigate_the_effort_required_to_add_pre_amp_post_hooks.feature

@@ -0,0 +1,24 @@
+# rake features FEATURE=features/hooks/4069174_investigate_the_effort_required_to_add_pre_amp_post_hooks.feature
+@hooks @needs_service
+Feature: Adding pre-and-post hooks
+  Background:
+    Given my Pivotal Tracker configuration is setup as normal
+
+    Given the story 4069174 exists
+    And the name of story 4069174 is "Investigate the effort required to add pre & post hooks"
+
+    Given I have "debug" callbacks enabled
+
+  Scenario: Hooked into start
+    When I successfully execute "git start 4069174"
+
+    Then the stdout should contain "start"
+    And the stderr should contain "start_story_on_pivotal_tracker!"
+
+  Scenario: Hooked into finish
+    Given the local branch "4069174_investigate_the_effort_required_to_add_pre_amp_post_hooks" exists
+
+    When I successfully execute "git finish 4069174"
+
+    Then the stdout should contain "finish"
+    And the stderr should contain "finish_story_on_pivotal_tracker!"

data/features/hooks/4199841_need_hooks_for_my_workflow.feature

@@ -0,0 +1,51 @@
+# rake features FEATURE=features/hooks/4199841_need_hooks_for_my_workflow.feature
+@hooks @needs_service @needs_remote_repository @my_workflow
+Feature: Need hooks for my workflow
+  Background:
+    Given my Pivotal Tracker configuration is setup as normal
+    And I have "mine" callbacks enabled
+
+    Given the story 4199841 exists
+    And the name of story 4199841 is "Need hooks for my workflow"
+
+    Given the local branch "4199841_need_hooks_for_my_workflow" exists
+
+  Scenario: Fails to merge when tests fail before merge
+    Given the local branch "4199841_need_hooks_for_my_workflow" is active
+    And the rake task "spec" will fail
+    And the rake task "features" will fail
+
+    When I execute "git finish"
+
+    Then the stderr should contain "The tests failed, please fix and try again"
+    And the branch "4199841_need_hooks_for_my_workflow" should be active
+    And the branch "4199841_need_hooks_for_my_workflow" should not be merged into master
+
+  Scenario: Leaves the branch being merged as active
+    Given the local branch "4199841_need_hooks_for_my_workflow" is active
+    And the rake task "spec" will fail
+    And the rake task "features" will fail
+    And the local branch "master" is active
+
+    When I execute "git finish 4199841"
+
+    Then the stderr should contain "The tests failed, please fix and try again"
+    And the branch "4199841_need_hooks_for_my_workflow" should be active
+    And the branch "4199841_need_hooks_for_my_workflow" should not be merged into master
+
+
+#  @wip
+#  Scenario: Drops into shell if tests fail after merge
+
+  Scenario: Completely successful pushes master to the remote repository
+    Given the local branch "4199841_need_hooks_for_my_workflow" is active
+    And the rake task "spec" will succeed
+    And the rake task "features" will succeed
+
+    When I execute "git finish"
+
+    Then the stderr should not contain "The tests failed, please fix and try again"
+    And the stderr should not contain "Unable to push branch 'master'"
+    And the branch "4199841_need_hooks_for_my_workflow" should be merged into master
+    And story 4199841 should be finished
+    And the local and remote "master" branches should agree

data/features/hooks/4199845_need_hooks_for_sanger_workflow.feature

@@ -0,0 +1,66 @@
+# rake features FEATURE=features/hooks/4199845_need_hooks_for_sanger_workflow.feature
+@hooks @needs_service @needs_remote_repository @sanger_workflow
+Feature: Need hooks for WTSI workflow
+  Background:
+    Given my Pivotal Tracker configuration is setup as normal
+    And I have "sanger" callbacks enabled
+
+    Given the story 4199845 exists
+    And the name of story 4199845 is "Need hooks for WTSI workflow"
+
+    Given the local branch "4199845_need_hooks_for_wtsi_workflow" exists
+
+  Scenario: Fails to push local branch if tests fail
+    Given the local branch "4199845_need_hooks_for_wtsi_workflow" is active
+    And the rake task "test" will fail
+    And the rake task "features" will fail
+
+    When I execute "git finish"
+
+    Then the stderr should contain "The tests failed, please fix and try again"
+    And the branch "4199845_need_hooks_for_wtsi_workflow" should be active
+    And the branch "4199845_need_hooks_for_wtsi_workflow" should not be merged into master
+
+  Scenario: Leaves the branch being merged as active
+    Given the local branch "4199845_need_hooks_for_wtsi_workflow" is active
+    And the rake task "test" will fail
+    And the rake task "features" will fail
+    And the local branch "master" is active
+
+    When I execute "git finish 4199845"
+
+    Then the stderr should contain "The tests failed, please fix and try again"
+    And the branch "4199845_need_hooks_for_wtsi_workflow" should be active
+    And the branch "4199845_need_hooks_for_wtsi_workflow" should not be merged into master
+
+  Scenario: Completely successful pushes branch to remote repository
+    Given my remote branch naming convention is "${number}_${name}"
+
+    Given the local branch "4199845_need_hooks_for_wtsi_workflow" is active
+    And the rake task "test" will succeed
+    And the rake task "features" will succeed
+
+    When I successfully execute "git finish"
+
+    Then the stderr should not contain "The tests failed, please fix and try again"
+    And the stderr should not contain "Unable to push branch '4199845_need_hooks_for_wtsi_workflow'"
+    And the branch "4199845_need_hooks_for_wtsi_workflow" should not be merged into master
+    And the local and remote "4199845_need_hooks_for_wtsi_workflow" branches should agree
+
+    Then story 4199845 should be finished
+    And story 4199845 should have a comment of "Fixed on 4199845_need_hooks_for_wtsi_workflow. Needs merging into master"
+
+  Scenario: Pushes remote name properly
+    Given my remote branch naming convention is "${name}_${number}"
+
+    Given the local branch "4199845_need_hooks_for_wtsi_workflow" is active
+    And the rake task "test" will succeed
+    And the rake task "features" will succeed
+
+    When I successfully execute "git finish"
+
+    Then the stderr should not contain "The tests failed, please fix and try again"
+    And the stderr should not contain "Unable to push branch '4199845_need_hooks_for_wtsi_workflow'"
+    And the branch "4199845_need_hooks_for_wtsi_workflow" should not be merged into master
+    And story 4199845 should be finished
+    And the local branch "4199845_need_hooks_for_wtsi_workflow" and remote branch "need_hooks_for_wtsi_workflow_4199845" should agree