README.md in pivotal-github-0.8.0 vs README.md in pivotal-github-0.8.1
- old
+ new
@@ -1,8 +1,8 @@
# pivotal-github
-The `pivotal-github` gem facilitates a [Pivotal Tracker](http://pivotaltracker.com/)–[GitHub](http://github.com/) workflow inspired by the workflow used by [Logical Reality](http://lrdesign.com/). (Despite its name, `pivotal-github` also works fine with [BitBucket](http://bitbucket.com/); see **Configuration** below.) 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, so I rolled my own.
+The `pivotal-github` gem facilitates a [Pivotal Tracker](http://pivotaltracker.com/)–[GitHub](http://github.com/) workflow inspired by the workflow used by [Logical Reality](http://lrdesign.com/). (Despite its name, `pivotal-github` also works fine with [Bitbucket](http://bitbucket.com/); see **Configuration** below.) 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, so I rolled my own.
## Installation
You can install the `pivotal-github` gem directly as follows:
@@ -12,28 +12,28 @@
## 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(s) into the commit messages, while adding options to mark the story **Finished** or **Delivered**.
-The `git story-commit` command makes the assumption that any string of digits in the branch name is a story id. This means that 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 `git story-commit` command makes the assumption that any string of eight or more digits in the branch name is a story id. (As of this writing, Pivotal Tracker ids are eight digits long, so shorter digit strings aren't valid ids.) This means that the branch names `62831853-add-markdown-support`, `62831853_add_markdown_support`, `add-markdown-support-62831853`, and `rails_4_0_62831853` all correspond to story id `62831853`, while `add-things-62831853-31415926` corresponds to both `62831853` *and* `31415926`.
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 when the branch gets pushed up to GitHub.
-For example, when on a branch called `add-markdown-support-6283185`, the `git story-commit` command automatically adds `[#6283185]` to the commit message:
+For example, when on a branch called `add-markdown-support-62831853`, the `git story-commit` command automatically adds `[#62831853]` to the commit message:
$ git story-commit -am "Add foo bars"
- [add-markdown-support-6283185 6f56414] Add foo bars
+ [add-markdown-support-62831853 6f56414] Add foo bars
The commit message is multiline and includes the story id:
Add foo bars
- [#6283185]
+ [#62831853]
(Previous versions of `pivotal-github` put the story id on the same line as the commit summary (per the usage at the [Pivotal Tracker API](https://www.pivotaltracker.com/help/api?version=v3)), but placing it in a separate line gives the user direct control over the length of the message. It also looks less cluttered.)
To mark a story as **Finished**, add the `-f` flag:
@@ -41,36 +41,36 @@
This gives the message
Remove baz quuxes
- [Finishes #6283185]
+ [Finishes #62831853]
To mark a story as **Delivered**, add the `-d` flag:
$ git story-commit -d -am "Remove baz quuxes"
The message in this case is
Remove baz quuxes
- [Delivers #6283185]
+ [Delivers #62831853]
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` supports multiple story numbers as well. For example, with a branch called `add-things-62831853-31415926`, we could deliver both stories as follows:
$ git story-commit -dam "Remove baz quuxes"
- [add-things-6283185-3141592 7g56429] Remove baz quuxes
+ [add-things-62831853-31415926 7g56429] Remove baz quuxes
The message here is
Remove baz quuxes
- [Delivers #6283185 #3141592]
+ [Delivers #62831853 #31415926]
#### Options
$ git story-commit -h
Usage: git story-commit [options]
@@ -82,14 +82,14 @@
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-merge
-`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 story-merge` merges the current branch into `master`. On a branch called `add-markdown-support-62831853`, `git story-merge` is equivalent to the following:
$ git checkout master
- $ git merge --no-ff --log add-markdown-support-6283185
+ $ git merge --no-ff --log add-markdown-support-62831853
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/),
> 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 than that cost.
@@ -108,15 +108,15 @@
Additionally, `git story-merge` accepts any options valid for `git merge`.
### git story-pull-request
-`git story-pull-request` opens the proper remote URI to issue a pull request for the current branch (OS X–only):
+`git story-pull-request` opens the proper remote URL to issue a pull request for the current branch (OS X–only):
$ git story-pull-request
-By default, `git story-pull-request` issues a `git push-branch` as well, just in case the local branch hasn't yet been pushed up to the remote repository.
+By default, `git story-pull-request` issues a `git push-branch` as well (from [git-utils](https://github.com/mhartl/git-utils)), just in case the local branch hasn't yet been pushed up to the remote repository.
As with `git story-merge`, by default `git story-pull-request` exits with a warning if the most recent commit doesn't finish the story.
#### Options
@@ -124,18 +124,18 @@
-f, --force override unfinished story warning
-h, --help this usage guide
### story-open
-The `story-open` command (*note*: no `git`) opens the current story in the default browser (OS X–only):
+The `story-open` command (no `git`) opens the current story in the default browser (OS X–only):
$ story-open
## 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 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.
+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, formatted so that they can be pasted directly into a terminal window:
git config --global alias.sc story-commit
git config --global alias.sm story-merge
@@ -145,11 +145,11 @@
git config --global alias.pb push-branch
A single-developer workflow would then look like this:
- $ git co -b add-markdown-support-6283185
+ $ git co -b add-markdown-support-62831853
$ git pb
<work>
$ git sc -am "Added foo"
$ git push
<more work>
@@ -159,23 +159,25 @@
$ git push
$ git sync
$ git rebase master
$ git sm
+Here `git sync` is also from [git-utils](https://github.com/mhartl/git-utils).
+
## Workflow with integrated code reivew
The `pivotal-github` gem is degined to support a workflow involving integrated code review, which has the usual benefits: at least two pairs of eyes see any committed code, and at least two brains know basically what the committed code does. The cost is that having a second developer involved can slow you down. I suggest using your judgment to determine which workflow makes the most sense on a story-by-story basis.
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 add-markdown-support-6283185`
+2. Create a branch in the local Git repository containing the story id and a brief description: `git checkout -b add-markdown-support-62831853`
3. Create a remote branch at [GitHub](http://github.com/) using `git push-branch`
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** using `git story-commit -f -am "Add paragraph breaks"` or as **Delivered** using `git story-commit -d -am "Add paragraph breaks"`
+4. When done with the story, add `-f` to mark the story as **Finished** using `git story-commit -fam "Add paragraph breaks"` or as **Delivered** using `git story-commit -dam "Add paragraph breaks"`
4. Rebase against `master` using `git sync` 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
6. (On OS X, replace the previous two steps with `git story-pull-request`)
6. Assign the pull request to Bob at GitHub