README.md in pivotal-github-0.6.14 vs README.md in pivotal-github-0.7.0

- old
+ new

@@ -9,30 +9,44 @@ $ gem install pivotal-github ## 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 into the commit messages, while adding options to mark the story **Finished** or **Delivered**. +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 the first string of digits in the branch name is the story id. This means that, when the story id is `6283185`, the branch names `6283185-add-markdown-support`, `6283185_add_markdown_support`, and `add-markdown-support-6283185` all work, but `add-42-things-6283185` doesn't. +The `git story-commit` command makes the assumption that any string of digits in the branch name is a story id. This means that, when the story id is `6283185`, 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 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 `6283185-add-markdown-support`, the `git story-commit` command automatically adds `[#6283185]` to the commit message: +For example, when on a branch called `add-markdown-support-6283185`, 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 + [add-markdown-support-6283185 6f56414] [#6283185] Add foo bars 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 + [add-markdown-support-6283185 7g56429] [Finishes #6283185] Remove baz quuxes +To mark a story as **Delivered**, add the `-d` flag: + + $ git story-commit -d -am "Remove baz quuxes" + [add-markdown-support-6283185 7g56429] [Delivers #6283185] Remove baz quuxes + +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 -dam "Remove baz quuxes" + [add-things-6283185-3141592 7g56429] [Delivers #6283185 #3141592] Remove baz quuxes + #### Options $ git story-commit -h Usage: git story-commit [options] -m, --message MESSAGE add a commit message (including story #) @@ -46,11 +60,11 @@ ### 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 + * [new branch] add-markdown-support-6283185 -> add-markdown-support-6283185 #### Options Usage: git story-push [options] -t, --target TARGET push to a given target (defaults to origin) @@ -58,15 +72,15 @@ Additionall, `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 story-pull` syncs the local `master` with the remote `master`. On a branch called `add-markdown-support-6283185`, `git story-pull` is equivalent to the following: $ git checkout master $ git pull - $ git checkout 6283185-add-markdown-support + $ git checkout add-markdown-support-6283185 The purpose of `git story-pull` is to prepare the local story branch for rebasing against `master`: $ git story-pull $ git rebase master @@ -97,14 +111,14 @@ 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 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 checkout master - $ git merge --no-ff --log 6283185-add-markdown-support + $ git merge --no-ff --log add-markdown-support-6283185 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 that that cost. @@ -147,23 +161,23 @@ $ 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 past 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: +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.sp story-push git config --global alias.sl story-pull git config --global alias.sm story-merge git config --global alias.spr story-pull-request A single-developer workflow would then look like this: - $ git co -b 6283185-add-markdown-support + $ git co -b add-markdown-support-6283185 $ git sp <work> $ git sc -am "Added foo" $ git push <more work> @@ -184,31 +198,37 @@ 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 6283185-add-markdown-support` +2. Create a branch in the local Git repository containing the story id and a brief description: `git checkout -b add-markdown-support-6283185` 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** using `git story-commit -f -am "Add paragraph breaks"` or as **Delivered** using `git story-commit -d -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 6. (On OS X, replace the previous two steps with `git story-pull-request`) 6. Assign the pull request to Bob at GitHub -7. On the Pivotal Tracker story, change the **Owner** to Developer #2 (Bob) and add a comment with the pull request URL +7. On the Pivotal Tracker story, add a comment with the pull request URL 8. Continue working, taking care to branch off of the current story branch if its changes are required to continue Rather than immediately submitting a pull request, Alice can also continue by branching off the previous story branch, working on a set of related features, and then issue Bob a pull request for the final branch when she reaches a natural stopping place. ### 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. If the branch can't be automatically merged, mark the story as **Rejected** and change the **Owner** back to Alice +4. If the branch can't be automatically merged, mark the story as **Rejected** + +### Developer #1 (Alice) + +1. After getting the GitHub notification that the pull request has been merged, mark the Pivotal Tracker story finished. (In principle, Bob could do this, but Alice probably knows the PR-to-story mapping better than Bob, and experience shows that it is difficult for Bob to remember to update Pivotal Tracker after accepting the pull request.) +2. If the pull request was rejected, make the necessary changes and follow the previous steps above. + ## 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: