github-pivotal-flow 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a4e63d5c7d9eda8c218b536bf973127a9ed3fd48
+  data.tar.gz: fcc22c50ee4958a67ffdad288bd13bdb86adaa90
+SHA512:
+  metadata.gz: 85fb6cea0fbc88c4abd12b1622557378db19758037bb495b3132471fd01403a66fbfd7a724918a6316655d9a19bd455adbf2037ab34970be48a9828b45011df1
+  data.tar.gz: bec91a2d14f3cc3e597a0de10e03917ff8eef9efb8d65a3378d1c249a4a084a4c387775952eafa6bf0d0b3b3950e132f5d731ff051a36d7298ed11a8ab15b65f

data/LICENSE

@@ -0,0 +1,14 @@
+# Git Pivotal Tracker Integration
+# Copyright (c) 2013 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

data/README.md

@@ -0,0 +1,183 @@
+# Github Pivotal Flow
+
+`github-pivotal-flow` provides a set of additional Git commands to help developers when working with [Pivotal Tracker][pivotal-tracker], git-flow and Github pull requests.
+It follows the branch structure recommended by [Git flow][git-flow].
+
+This is the tool we use internally to speed up our development process.
+
+[pivotal-tracker]: http://www.pivotaltracker.com
+[git-flow]: https://github.com/nvie/gitflow
+
+## Installation
+`github-pivotal-flow` requires at least **Ruby 1.8.7**, **Git 1.8.2.1** in order to run.  It is tested against Rubies _1.8.7_, _1.9.3_, and _2.0.0_.  In order to install it, do the following:
+
+```plain
+$ gem install github-pivotal-flow
+```
+
+
+## Usage
+`github-pivotal-flow` is intended to vastly speed up your development workflow.
+The typical workflow looks something like the following:
+
+```plain
+$ git start       # Creates branch, opens a pull request on Github and starts story
+$ git commit ...
+$ git commit ...  # Your existing development process
+$ git commit ...
+$ git finish      # Merges back into the main branch. Pushes to origin, destroys branch and finishes story.
+```
+
+
+## Configuration
+
+### Git Client
+In order to use `github-pivotal-flow`, a few Git client configuration properties must be set.  If these properties have not been set, you will be prompted for them and your Git configuration will be updated.
+
+| Name | Description
+| ---- | -----------
+| `pivotal.api-token` | Your Pivotal Tracker API Token.  This can be found in [your profile][profile] and should be set globally.
+| `pivotal.project-id` | The Pivotal Tracker project id for the repository your are working in.  This can be found in the project's URL and should be set.
+| `gitflow.branch.master` | The Git-flow master branch name. If you've used Git-flow before this will already be set up. Otherwise this is the branch considered 'production'.
+| `gitflow.branch.development` | The Git-flow development branch name. The branch that is commonly used for your development.
+| `gitflow.prefix.feature` | Git-flow feature branch name prefix.
+| `gitflow.prefix.hotfix` | Git-flow hotfix branch name prefix.
+| `gitflow.prefix.feature` | Git-flow feature branch name prefix.
+| `gitflow.prefix.release` | Git-flow release branch name prefix.
+
+[profile]: https://www.pivotaltracker.com/profile
+
+
+### Git Server
+In order to take advantage of automatic issue completion, the [Pivotal Tracker Source Code Integration][integration] must be enabled.  If you are using GitHub, this integration is easy to enable by navgating to your project's 'Service Hooks' settings and configuring it with the proper credentials.
+
+[integration]: https://www.pivotaltracker.com/help/integrations?version=v3#scm
+
+
+## Commands
+
+### `git start [ type | story-id ]`
+This command starts a story by creating a Git branch and changing the story's state to `started`.  This command can be run in three ways.  First it can be run specifying the id of the story that you want to start.
+
+```plain
+$ git start 12345678
+```
+
+The second way to run the command is by specyifying the type of story that you would like to start.  In this case it will then offer you the first five stories (based on the backlog's order) of that type to choose from.
+
+```plain
+$ git start feature
+
+1. Lorem ipsum dolor sit amet, consectetur adipiscing elit
+2. Pellentesque sit amet ante eu tortor rutrum pharetra
+3. Ut at purus dolor, vel ultricies metus
+4. Duis egestas elit et leo ultrices non fringilla ante facilisis
+5. Ut ut nunc neque, quis auctor mauris
+Choose story to start:
+```
+
+Finally the command can be run without specifying anything.  In this case, it will then offer the first five stories (based on the backlog's order) of any type to choose from.
+
+```plain
+$ git start
+
+1. FEATURE Donec convallis leo mi, dictum ornare sem
+2. CHORE   Sed et magna lectus, sed auctor purus
+3. FEATURE In a nunc et enim tincidunt interdum vitae et risus
+4. FEATURE Fusce facilisis varius lorem, at tristique sem faucibus in
+5. BUG     Donec iaculis ante neque, ut tempus augue
+Choose story to start:
+```
+
+Once a story has been selected by one of the three methods, the command then prompts for the name of the branch to create.
+
+```plain
+$ git start 12345678
+        Title: Lorem ipsum dolor sit amet, consectetur adipiscing elitattributes
+  Description: Ut consequat sapien ut erat volutpat egestas. Integer venenatis lacinia facilisis.
+
+Enter branch name (12345678-<branch-name>):
+```
+
+The value entered here will be prepended with the story id such that the branch name is `<story-id>-<branch-name>`.  This branch is then created and checked out.
+
+If it doesn't exist already, a `prepare-commit-msg` commit hook is added to your repository.  This commit hook augments the existing commit messsage pattern by appending the story id to the message automatically.
+
+```plain
+
+[#12345678]
+# Please enter the commit message for your changes. Lines starting
+# with '#' will be ignored, and an empty message aborts the commit.
+# On branch 12345678-lorem-ipsum
+# Changes to be committed:
+#   (use "git reset HEAD <file>..." to unstage)
+#
+#	new file:   dolor.txt
+#
+```
+
+### `git finish [--no-complete]`
+This command finishes a story by merging and cleaning up its branch and then pushing the changes to a remote server.  This command can be run in two ways.  First it can be run without the `--no-complete` option.
+
+```plain
+$ git finish
+Checking for trivial merge from 12345678-lorem-ipsum to master... OK
+Merging 12345678-lorem-ipsum to master... OK
+Deleting 12345678-lorem-ipsum... OK
+Pushing to origin... OK
+```
+
+The command checks that it will be able to do a trivial merge from the development branch to the target branch before it does anything.  The check has the following constraints
+
+1.  The local repository must be up to date with the remote repository (e.g. `origin`)
+2.  The local merge target branch (e.g. `master`) must be up to date with the remote merge target branch (e.g. `origin/master`)
+3.  The common ancestor (i.e. the branch point) of the development branch (e.g. `12345678-lorem-ipsum`) must be tip of the local merge target branch (e.g. `master`)
+
+If all of these conditions are met, the development branch will be merged into the target branch with a message of:
+
+```plain
+Merge 12345678-lorem-ipsum to master
+
+[Completes #12345678]
+```
+
+The second way is with the `--no-complete` option specified. In this case `finish` performs the same actions except the `Completes`... statement in the commit message will be supressed.
+
+```plain
+Merge 12345678-lorem-ipsum to master
+
+[#12345678]
+```
+
+After merging, the development branch is deleted and the changes are pushed to the remote repository.
+
+### `git release [story-id]`
+This command creates a release for a story.  It does this by updating the version string in the project and creating a tag.  This command can be run in two ways.  First it can be run specifying the release that you want to create.
+
+```plain
+$ git release 12345678
+```
+The other way the command can be run without specifying anything.  In this case, it will select the first release story (based on the backlog's order).
+
+```plain
+$ git release
+      Title: Lorem ipsum dolor sit amet, consectetur adipiscing elitattributes
+```
+
+Once a story has been selected by one of the two methods, the command then prompts for the release version and next development version.
+
+```plain
+$ git release
+      Title: Lorem ipsum dolor sit amet, consectetur adipiscing elitattributes
+
+Enter release version (current: 1.0.0.BUILD-SNAPSHOT): 1.0.0.M1
+Enter next development version (current: 1.0.0.BUILD-SNAPSHOT): 1.1.0.BUILD-SNAPSHOT
+Creating tag v1.0.0.M1... OK
+Pushing to origin... OK
+```
+
+Once these have been entered, the version string for the current project is updated to the release version and a tag is created.  Then the version string for the current project is updated to the next development version and a new commit along the original branch is created.  Finally the tag and changes are pushed to the remote sever.
+
+Version update is currently supported for the following kinds of projects.  If you do not see a project type that you would like supported, please open an issue or submit a pull request.
+
+* Gradle

data/bin/git-finish

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby -U
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'github_pivotal_flow'
+
+exit GithubPivotalFlow::Finish.new(STDIN, STDOUT, *ARGV).run!

data/bin/git-start

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby -U
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'github_pivotal_flow'
+
+exit GithubPivotalFlow::Start.new(STDIN, STDOUT, *ARGV).run!

data/lib/core_ext/object/blank.rb

@@ -0,0 +1,105 @@
+# encoding: utf-8
+
+class Object
+  # An object is blank if it's false, empty, or a whitespace string.
+  # For example, '', '   ', +nil+, [], and {} are all blank.
+  #
+  # This simplifies:
+  #
+  #   if address.nil? || address.empty?
+  #
+  # ...to:
+  #
+  #   if address.blank?
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end
+
+  # An object is present if it's not <tt>blank?</tt>.
+  def present?
+    !blank?
+  end
+
+  # Returns object if it's <tt>present?</tt> otherwise returns +nil+.
+  # <tt>object.presence</tt> is equivalent to <tt>object.present? ? object : nil</tt>.
+  #
+  # This is handy for any representation of objects where blank is the same
+  # as not present at all. For example, this simplifies a common check for
+  # HTTP POST/query parameters:
+  #
+  #   state   = params[:state]   if params[:state].present?
+  #   country = params[:country] if params[:country].present?
+  #   region  = state || country || 'US'
+  #
+  # ...becomes:
+  #
+  #   region = params[:state].presence || params[:country].presence || 'US'
+  def presence
+    self if present?
+  end
+end
+
+class NilClass
+  # +nil+ is blank:
+  #
+  #   nil.blank? # => true
+  def blank?
+    true
+  end
+end
+
+class FalseClass
+  # +false+ is blank:
+  #
+  #   false.blank? # => true
+  def blank?
+    true
+  end
+end
+
+class TrueClass
+  # +true+ is not blank:
+  #
+  #   true.blank? # => false
+  def blank?
+    false
+  end
+end
+
+class Array
+  # An array is blank if it's empty:
+  #
+  #   [].blank?      # => true
+  #   [1,2,3].blank? # => false
+  alias_method :blank?, :empty?
+end
+
+class Hash
+  # A hash is blank if it's empty:
+  #
+  #   {}.blank?                # => true
+  #   { key: 'value' }.blank?  # => false
+  alias_method :blank?, :empty?
+end
+
+class String
+  # A string is blank if it's empty or contains whitespaces only:
+  #
+  #   ''.blank?                 # => true
+  #   '   '.blank?              # => true
+  #   '　'.blank?               # => true
+  #   ' something here '.blank? # => false
+  def blank?
+    self !~ /[^[:space:]]/
+  end
+end
+
+class Numeric #:nodoc:
+  # No number is blank:
+  #
+  #   1.blank? # => false
+  #   0.blank? # => false
+  def blank?
+    false
+  end
+end

data/lib/github_pivotal_flow.rb

@@ -0,0 +1,31 @@
+# Git Pivotal Tracker Integration
+# Copyright (c) 2013 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+$:.unshift(File.dirname(__FILE__))
+
+require 'highline/import'
+require 'pivotal-tracker'
+
+require File.join('core_ext', 'object', 'blank')
+
+require File.join('github_pivotal_flow', 'shell')
+require File.join('github_pivotal_flow', 'git')
+require File.join('github_pivotal_flow', 'project')
+require File.join('github_pivotal_flow', 'configuration')
+require File.join('github_pivotal_flow', 'github_api')
+require File.join('github_pivotal_flow', 'story')
+require File.join('github_pivotal_flow', 'command')
+require File.join('github_pivotal_flow', 'start')
+require File.join('github_pivotal_flow', 'finish')

data/lib/github_pivotal_flow/command.rb

@@ -0,0 +1,57 @@
+# An abstract base class for all commands
+# @abstract Subclass and override {#run} to implement command functionality
+module GithubPivotalFlow
+  class Command
+
+    attr_reader :options, :configuration
+
+    # Common initialization functionality for all command classes.  This
+    # enforces that:
+    # * the command is being run within a valid Git repository
+    # * the user has specified their Pivotal Tracker API token
+    # * all communication with Pivotal Tracker will be protected with SSL
+    # * the user has configured the project id for this repository
+    def initialize(*args)
+      @options = {}
+      args = parse_argv(*args)
+      @options[:args] = args
+
+      @repository_root = Git.repository_root
+      @configuration = Configuration.new
+
+      PivotalTracker::Client.token = @configuration.api_token
+      PivotalTracker::Client.use_ssl = true
+
+      @project = PivotalTracker::Project.find @configuration.project_id
+
+      # Make sure that all the git flow config options are set up
+      @configuration.development_branch
+      @configuration.master_branch
+      @configuration.feature_prefix
+      @configuration.hotfix_prefix
+    end
+
+    # The main entry point to the command's execution
+    # @abstract Override this method to implement command functionality
+    def run!
+      raise NotImplementedError
+    end
+
+    protected
+
+    def parse_argv(*args)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: git start <feature|chore|bug|story_id> | git finish"
+        opts.on("-t", "--api-token=", "Pivotal Tracker API key") { |k| options[:api_token] = k }
+        opts.on("-p", "--project-id=", "Pivotal Tracker project id") { |p| options[:project_id] = p }
+        opts.on("-n", "--full-name=", "Your Pivotal Tracker full name") { |n| options[:full_name] = n }
+        opts.on_tail("-h", "--help", "This usage guide") { put opts.to_s; exit 0 }
+      end.parse!(args)
+    end
+
+    def current_branch_name
+      Git.branch_name
+    end
+
+  end
+end

data/lib/github_pivotal_flow/configuration.rb

@@ -0,0 +1,251 @@
+require 'highline/import'
+require 'uri'
+
+module GithubPivotalFlow
+  # A class that exposes configuration that commands can use
+  class Configuration
+    def initialize
+      @github_password_cache = {}
+    end
+
+    # Returns the user's Pivotal Tracker API token.  If this token has not been
+    # configured, prompts the user for the value.  The value is checked for in
+    # the _inherited_ Git configuration, but is stored in the _global_ Git
+    # configuration so that it can be used across multiple repositories.
+    #
+    # @return [String] The user's Pivotal Tracker API token
+    def api_token
+      api_token =  Git.get_config KEY_API_TOKEN, :inherited
+
+      if api_token.empty?
+        api_token = ask('Pivotal API Token (found at https://www.pivotaltracker.com/profile): ').strip
+        Git.set_config KEY_API_TOKEN, api_token, :global
+        puts
+      end
+
+      api_token
+    end
+
+    # Returns the Pivotal Tracker project id for this repository.  If this id
+    # has not been configuration, prompts the user for the value.  The value is
+    # checked for in the _inherited_ Git configuration, but is stored in the
+    # _local_ Git configuration so that it is specific to this repository.
+    #
+    # @return [String] The repository's Pivotal Tracker project id
+    def project_id
+      project_id = Git.get_config KEY_PROJECT_ID, :inherited
+
+      if project_id.empty?
+        project_id = choose do |menu|
+          menu.prompt = 'Choose project associated with this repository: '
+
+          PivotalTracker::Project.all.sort_by { |project| project.name }.each do |project|
+            menu.choice(project.name) { project.id }
+          end
+        end
+
+        Git.set_config KEY_PROJECT_ID, project_id, :local
+        puts
+      end
+
+      project_id
+    end
+
+    # Returns the story associated with the current development branch
+    #
+    # @param [PivotalTracker::Project] project the project the story belongs to
+    # @return [PivotalTracker::Story] the story associated with the current development branch
+    def story(project)
+      story_id = Git.get_config(KEY_STORY_ID, :branch)
+      Story.new(project.stories.find(story_id.to_i), :branch_name => Git.current_branch)
+    end
+
+    # Stores the story associated with the current development branch
+    #
+    # @param [PivotalTracker::Story] story the story associated with the current development branch
+    # @return [void]
+    def story=(story)
+      Git.set_config KEY_STORY_ID, story.id, :branch
+    end
+
+    def feature_prefix
+      feature_prefix = Git.get_config KEY_FEATURE_PREFIX, :inherited
+
+      if feature_prefix.empty?
+        feature_prefix = ask('Please enter your git-flow feature branch prefix: [feature]').strip
+        feature_prefix = 'feature' if feature_prefix.blank?
+        Git.set_config KEY_FEATURE_PREFIX, feature_prefix, :local
+        puts
+      end
+
+      feature_prefix
+    end
+
+    def hotfix_prefix
+      hotfix_prefix = Git.get_config KEY_HOTFIX_PREFIX, :inherited
+
+      if hotfix_prefix.empty?
+        hotfix_prefix = ask('Please enter your git-flow hotfix branch prefix: [hotfix]').strip
+        hotfix_prefix = 'hotfix' if hotfix_prefix.blank?
+        Git.set_config KEY_HOTFIX_PREFIX, hotfix_prefix, :local
+        puts
+      end
+
+      hotfix_prefix
+    end
+
+    def release_prefix
+      release_prefix = Git.get_config KEY_RELEASE_PREFIX, :inherited
+
+      if release_prefix.empty?
+        release_prefix = ask('Please enter your git-flow release branch prefix: [release]').strip
+        release_prefix = 'release' if release_prefix.blank?
+        Git.set_config KEY_RELEASE_PREFIX, release_prefix, :local
+        puts
+      end
+
+      release_prefix
+    end
+
+    def development_branch
+      development_branch = Git.get_config KEY_DEVELOPMENT_BRANCH, :inherited
+
+      if development_branch.empty?
+        development_branch = ask('Please enter your git-flow development branch name: [development]').strip
+        development_branch = 'development' if development_branch.nil? || development_branch.empty?
+        Git.set_config KEY_DEVELOPMENT_BRANCH, development_branch, :local
+        puts
+      end
+      Git.ensure_branch_exists(development_branch)
+
+      development_branch
+    end
+
+    def master_branch
+      master_branch = Git.get_config KEY_MASTER_BRANCH, :inherited
+
+      if master_branch.blank?
+        master_branch = ask('Please enter your git-flow production branch name: [master]').strip
+        master_branch = 'master' if master_branch.nil? || master_branch.empty?
+        Git.set_config KEY_MASTER_BRANCH, master_branch, :local
+        puts
+      end
+      Git.ensure_branch_exists(master_branch)
+
+      master_branch
+    end
+
+    def github_project
+      @github_project ||= Project.from_url(URI(Git.get_config("remote.#{Git.get_remote}.url")))
+    end
+
+    def github_username(host)
+      return ENV['GITHUB_USER'] unless ENV['GITHUB_USER'].to_s.blank?
+      github_username = Git.get_config KEY_GITHUB_USERNAME, :inherited
+      if github_username.blank?
+        github_username = ask('Github username: ').strip
+        Git.set_config KEY_GITHUB_USERNAME, github_username, :local
+      end
+      github_username
+    end
+
+    def github_username=(github_username)
+      Git.set_config KEY_GITHUB_USERNAME, github_username, :local unless github_username.blank?
+    end
+
+    def github_password(host, user)
+      return ENV['GITHUB_PASSWORD'] unless ENV['GITHUB_PASSWORD'].to_s.empty?
+      @github_password_cache["#{user}"] ||= ask_password(user)
+    end
+
+    def github_api_token(host, user)
+      github_token = Git.get_config KEY_GITHUB_API_TOKEN, :inherited
+      if github_token.blank?
+        github_token = yield
+        Git.set_config KEY_GITHUB_API_TOKEN, github_token, :local
+      end
+      github_token
+    end
+
+    # special prompt that has hidden input
+    def ask_password(user)
+      print "Github password for #{user} (never stored): "
+      if $stdin.tty?
+        password = askpass
+        puts ''
+        password
+      else
+        # in testing
+        $stdin.gets.chomp
+      end
+    rescue Interrupt
+      abort
+    end
+
+    def ask_auth_code
+      print "two-factor authentication code: "
+      $stdin.gets.chomp
+    rescue Interrupt
+      abort
+    end
+
+    def askpass
+      noecho $stdin do |input|
+        input.gets.chomp
+      end
+    end
+
+    def noecho io
+      require 'io/console'
+      io.noecho { yield io }
+    rescue LoadError
+      fallback_noecho io
+    end
+
+    def fallback_noecho io
+      tty_state = `stty -g 2>#{NULL}`
+      system 'stty raw -echo -icanon isig' if $?.success?
+      pass = ''
+      while char = getbyte(io) and !(char == 13 or char == 10)
+        if char == 127 or char == 8
+          pass[-1,1] = '' unless pass.empty?
+        else
+          pass << char.chr
+        end
+      end
+      pass
+    ensure
+      system "stty #{tty_state}" unless tty_state.empty?
+    end
+
+    def getbyte(io)
+      if io.respond_to?(:getbyte)
+        io.getbyte
+      else
+        # In Ruby <= 1.8.6, getc behaved the same
+        io.getc
+      end
+    end
+
+    def proxy_uri(with_ssl)
+      env_name = "HTTP#{with_ssl ? 'S' : ''}_PROXY"
+      if proxy = ENV[env_name] || ENV[env_name.downcase] and !proxy.empty?
+        proxy = "http://#{proxy}" unless proxy.include? '://'
+        URI.parse proxy
+      end
+    end
+
+    private
+
+    KEY_API_TOKEN = 'pivotal.api-token'.freeze
+    KEY_PROJECT_ID = 'pivotal.project-id'.freeze
+    KEY_STORY_ID = 'pivotal-story-id'.freeze
+    KEY_FEATURE_PREFIX = 'gitflow.prefix.feature'.freeze
+    KEY_HOTFIX_PREFIX = 'gitflow.prefix.hotfix'.freeze
+    KEY_RELEASE_PREFIX = 'gitflow.prefix.release'.freeze
+    KEY_DEVELOPMENT_BRANCH = 'gitflow.branch.develop'.freeze
+    KEY_MASTER_BRANCH = 'gitflow.branch.master'.freeze
+    KEY_GITHUB_USERNAME = 'github.username'.freeze
+    KEY_GITHUB_API_TOKEN = 'github.api-token'.freeze
+  end
+end