pivotal-github 0.6.14 → 0.7.0
Sign up to get free protection for your applications and to get access to all the features.
- data/README.md +36 -16
- data/lib/pivotal-github/command.rb +12 -1
- data/lib/pivotal-github/story_commit.rb +12 -4
- data/lib/pivotal-github/story_open.rb +3 -1
- data/lib/pivotal-github/version.rb +1 -1
- data/spec/commands/command_spec.rb +9 -1
- data/spec/commands/story_commit_spec.rb +30 -0
- data/spec/commands/story_open_spec.rb +0 -5
- metadata +2 -2
data/README.md
CHANGED
@@ -11,9 +11,9 @@ You can install the `pivotal-github` gem directly as follows:
|
|
11
11
|
|
12
12
|
## Usage
|
13
13
|
|
14
|
-
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**.
|
14
|
+
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**.
|
15
15
|
|
16
|
-
The `git story-commit` command makes the assumption that
|
16
|
+
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`.
|
17
17
|
|
18
18
|
The full set of commands is as follows:
|
19
19
|
|
@@ -21,15 +21,29 @@ The full set of commands is as follows:
|
|
21
21
|
|
22
22
|
`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.
|
23
23
|
|
24
|
-
For example, when on a branch called `
|
24
|
+
For example, when on a branch called `add-markdown-support-6283185`, the `git story-commit` command automatically adds `[#6283185]` to the commit message:
|
25
25
|
|
26
26
|
$ git story-commit -am "Add foo bars"
|
27
|
-
[
|
27
|
+
[add-markdown-support-6283185 6f56414] [#6283185] Add foo bars
|
28
28
|
|
29
29
|
To mark a story as **Finished**, add the `-f` flag:
|
30
30
|
|
31
31
|
$ git story-commit -f -am "Remove baz quuxes"
|
32
|
-
[
|
32
|
+
[add-markdown-support-6283185 7g56429] [Finishes #6283185] Remove baz quuxes
|
33
|
+
|
34
|
+
To mark a story as **Delivered**, add the `-d` flag:
|
35
|
+
|
36
|
+
$ git story-commit -d -am "Remove baz quuxes"
|
37
|
+
[add-markdown-support-6283185 7g56429] [Delivers #6283185] Remove baz quuxes
|
38
|
+
|
39
|
+
Either the `-f` flag or the `-d` flag can be combined with other flags, yielding commands like
|
40
|
+
|
41
|
+
$ git story-commit -dam "Remove baz quuxes"
|
42
|
+
|
43
|
+
`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
|
44
|
+
|
45
|
+
$ git story-commit -dam "Remove baz quuxes"
|
46
|
+
[add-things-6283185-3141592 7g56429] [Delivers #6283185 #3141592] Remove baz quuxes
|
33
47
|
|
34
48
|
#### Options
|
35
49
|
|
@@ -48,7 +62,7 @@ Additionally, `git story-commit` accepts any options valid for `git commit`. (`g
|
|
48
62
|
`git story push` creates a remote branch at `origin` with the name of the current branch:
|
49
63
|
|
50
64
|
$ git story-push
|
51
|
-
* [new branch]
|
65
|
+
* [new branch] add-markdown-support-6283185 -> add-markdown-support-6283185
|
52
66
|
|
53
67
|
#### Options
|
54
68
|
|
@@ -60,11 +74,11 @@ Additionall, `git story-push` accepts any options valid for `git push`.
|
|
60
74
|
|
61
75
|
### git story-pull
|
62
76
|
|
63
|
-
`git story-pull` syncs the local `master` with the remote `master`. On a branch called `
|
77
|
+
`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:
|
64
78
|
|
65
79
|
$ git checkout master
|
66
80
|
$ git pull
|
67
|
-
$ git checkout
|
81
|
+
$ git checkout add-markdown-support-6283185
|
68
82
|
|
69
83
|
The purpose of `git story-pull` is to prepare the local story branch for rebasing against `master`:
|
70
84
|
|
@@ -99,10 +113,10 @@ Additionally, `git story-pull` accepts any options valid for `git pull`.
|
|
99
113
|
|
100
114
|
### git story-merge
|
101
115
|
|
102
|
-
`git story-merge` merges the current branch into `master`. On a branch called `
|
116
|
+
`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:
|
103
117
|
|
104
118
|
$ git checkout master
|
105
|
-
$ git merge --no-ff --log
|
119
|
+
$ git merge --no-ff --log add-markdown-support-6283185
|
106
120
|
|
107
121
|
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/),
|
108
122
|
|
@@ -149,9 +163,9 @@ The `story-open` command (without `git`) opens the current story in the default
|
|
149
163
|
|
150
164
|
## Configuration
|
151
165
|
|
152
|
-
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
|
166
|
+
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.
|
153
167
|
|
154
|
-
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:
|
168
|
+
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:
|
155
169
|
|
156
170
|
git config --global alias.sc story-commit
|
157
171
|
git config --global alias.sp story-push
|
@@ -161,7 +175,7 @@ The `pivotal-github` command names follow the Git convention of being verbose (e
|
|
161
175
|
|
162
176
|
A single-developer workflow would then look like this:
|
163
177
|
|
164
|
-
$ git co -b
|
178
|
+
$ git co -b add-markdown-support-6283185
|
165
179
|
$ git sp
|
166
180
|
<work>
|
167
181
|
$ git sc -am "Added foo"
|
@@ -186,7 +200,7 @@ Here's the process in detail:
|
|
186
200
|
### Developer #1 (Alice)
|
187
201
|
|
188
202
|
1. Start an issue at [Pivotal Tracker](http://pivotaltracker.com/) and copy the story id to your buffer
|
189
|
-
2. Create a branch in the local Git repository containing the story id and a brief description: `git checkout -b
|
203
|
+
2. Create a branch in the local Git repository containing the story id and a brief description: `git checkout -b add-markdown-support-6283185`
|
190
204
|
3. Create a remote branch at [GitHub](http://github.com/) using `git story-push`
|
191
205
|
3. Use `git story-commit` to make commits, which includes the story number in the commit message: `git story-commit -am "Add syntax highlighting"`
|
192
206
|
4. Continue pushing up after each commit using `git push` as usual
|
@@ -196,7 +210,7 @@ Here's the process in detail:
|
|
196
210
|
6. At the GitHub page for the repo, select **Branches** and submit a pull request
|
197
211
|
6. (On OS X, replace the previous two steps with `git story-pull-request`)
|
198
212
|
6. Assign the pull request to Bob at GitHub
|
199
|
-
7. On the Pivotal Tracker story,
|
213
|
+
7. On the Pivotal Tracker story, add a comment with the pull request URL
|
200
214
|
8. Continue working, taking care to branch off of the current story branch if its changes are required to continue
|
201
215
|
|
202
216
|
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.
|
@@ -207,7 +221,13 @@ Rather than immediately submitting a pull request, Alice can also continue by br
|
|
207
221
|
1. Select **Pull Requests** at GitHub and review the pull request diffs
|
208
222
|
2. If acceptable, merge the branch by clicking on the button at GitHub
|
209
223
|
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
|
210
|
-
4. If the branch can't be automatically merged, mark the story as **Rejected**
|
224
|
+
4. If the branch can't be automatically merged, mark the story as **Rejected**
|
225
|
+
|
226
|
+
### Developer #1 (Alice)
|
227
|
+
|
228
|
+
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.)
|
229
|
+
2. If the pull request was rejected, make the necessary changes and follow the previous steps above.
|
230
|
+
|
211
231
|
|
212
232
|
## Merge conflicts
|
213
233
|
|
@@ -25,8 +25,19 @@ class Command
|
|
25
25
|
`git rev-parse --abbrev-ref HEAD`.strip
|
26
26
|
end
|
27
27
|
|
28
|
+
# Returns the story id (or ids).
|
29
|
+
# We extract the story id(s) from the branch name, so that, e.g.,
|
30
|
+
# the branch `add-markdown-support-6283185` gives story_id '6283185'.
|
31
|
+
# New as of version 0.7, we support multiple story ids in a single
|
32
|
+
# branch name, so that `add-markdown-support-6283185-3141592` can be used
|
33
|
+
# to update story 6283185 and story 3141592 simultaneously.
|
34
|
+
def story_ids
|
35
|
+
story_branch.scan(/\d+/)
|
36
|
+
end
|
37
|
+
|
38
|
+
# Returns the single story id for the common case of one id.
|
28
39
|
def story_id
|
29
|
-
|
40
|
+
story_ids.first
|
30
41
|
end
|
31
42
|
|
32
43
|
# Runs a command.
|
@@ -25,21 +25,29 @@ class StoryCommit < Command
|
|
25
25
|
end
|
26
26
|
|
27
27
|
def message
|
28
|
-
if
|
28
|
+
if story_ids.empty?
|
29
29
|
# Arranges to fall through to regular 'git commit'
|
30
30
|
options.message
|
31
31
|
else
|
32
32
|
if finish?
|
33
|
-
label = "Finishes
|
33
|
+
label = "Finishes #{message_ids}"
|
34
34
|
elsif deliver?
|
35
|
-
label = "Delivers
|
35
|
+
label = "Delivers #{message_ids}"
|
36
36
|
else
|
37
|
-
label =
|
37
|
+
label = message_ids
|
38
38
|
end
|
39
39
|
"[#{label}] #{options.message}"
|
40
40
|
end
|
41
41
|
end
|
42
42
|
|
43
|
+
# Returns the story ids formatted for story commits.
|
44
|
+
# For single-id stories, this is just the number preceded by '#', as in
|
45
|
+
# '#6283185'. For multiple-id stories, each story id is precede by '#', as in
|
46
|
+
# '#6283185 #3141592'
|
47
|
+
def message_ids
|
48
|
+
story_ids.map { |id| "##{id}" }.join(' ')
|
49
|
+
end
|
50
|
+
|
43
51
|
# Returns a command appropriate for executing at the command line.
|
44
52
|
# We take care to insert the story number and, if necessary, an indication
|
45
53
|
# that the commit finishes the story.
|
@@ -5,7 +5,9 @@ class StoryOpen < Command
|
|
5
5
|
# Returns a command appropriate for executing at the command line
|
6
6
|
# I.e., 'open https://www.pivotaltracker.com/story/show/6283185'
|
7
7
|
def cmd
|
8
|
-
|
8
|
+
story_ids.map do |id|
|
9
|
+
"open https://www.pivotaltracker.com/story/show/#{id}"
|
10
|
+
end.join(' ; ')
|
9
11
|
end
|
10
12
|
|
11
13
|
def run!
|
@@ -9,5 +9,13 @@ describe Command do
|
|
9
9
|
it { should respond_to(:args) }
|
10
10
|
it { should respond_to(:options) }
|
11
11
|
it { should respond_to(:parse) }
|
12
|
-
it { should respond_to(:
|
12
|
+
it { should respond_to(:story_ids) }
|
13
|
+
its(:story_ids) { should eq ['6283185']}
|
14
|
+
|
15
|
+
describe "branches with multiple stories" do
|
16
|
+
before do
|
17
|
+
command.stub(:story_branch).and_return('6283185-tau-manifesto-3141592')
|
18
|
+
end
|
19
|
+
its(:story_ids) { should eq ['6283185', '3141592'] }
|
20
|
+
end
|
13
21
|
end
|
@@ -53,6 +53,16 @@ describe StoryCommit do
|
|
53
53
|
its(:cmd) do
|
54
54
|
should == %(git commit -a -m "[##{command.story_id}] message" -z --foo)
|
55
55
|
end
|
56
|
+
|
57
|
+
describe "when used with branches containing multiple stories" do
|
58
|
+
before do
|
59
|
+
command.stub(:story_branch).and_return('6283185-tau-manifesto-3141592')
|
60
|
+
end
|
61
|
+
its(:cmd) do
|
62
|
+
delivered_ids = '#6283185 #3141592'
|
63
|
+
should == %(git commit -a -m "[#{delivered_ids}] message" -z --foo)
|
64
|
+
end
|
65
|
+
end
|
56
66
|
end
|
57
67
|
|
58
68
|
describe "command with no message" do
|
@@ -65,6 +75,16 @@ describe StoryCommit do
|
|
65
75
|
its(:cmd) do
|
66
76
|
should == %(git commit -m "[Finishes ##{command.story_id}] message")
|
67
77
|
end
|
78
|
+
|
79
|
+
describe "when used with branches containing multiple stories" do
|
80
|
+
before do
|
81
|
+
command.stub(:story_branch).and_return('6283185-tau-manifesto-3141592')
|
82
|
+
end
|
83
|
+
its(:cmd) do
|
84
|
+
delivered_ids = '#6283185 #3141592'
|
85
|
+
should == %(git commit -m "[Finishes #{delivered_ids}] message")
|
86
|
+
end
|
87
|
+
end
|
68
88
|
end
|
69
89
|
|
70
90
|
describe "command with deliver flag" do
|
@@ -72,6 +92,16 @@ describe StoryCommit do
|
|
72
92
|
its(:cmd) do
|
73
93
|
should == %(git commit -m "[Delivers ##{command.story_id}] message")
|
74
94
|
end
|
95
|
+
|
96
|
+
describe "when used with branches containing multiple stories" do
|
97
|
+
before do
|
98
|
+
command.stub(:story_branch).and_return('6283185-tau-manifesto-3141592')
|
99
|
+
end
|
100
|
+
its(:cmd) do
|
101
|
+
delivered_ids = '#6283185 #3141592'
|
102
|
+
should == %(git commit -m "[Delivers #{delivered_ids}] message")
|
103
|
+
end
|
104
|
+
end
|
75
105
|
end
|
76
106
|
|
77
107
|
describe "command with no story id" do
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: pivotal-github
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.7.0
|
5
5
|
prerelease:
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
@@ -9,7 +9,7 @@ authors:
|
|
9
9
|
autorequire:
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
|
-
date: 2013-
|
12
|
+
date: 2013-05-26 00:00:00.000000000 Z
|
13
13
|
dependencies: []
|
14
14
|
description: Add commands for Pivotal Tracker-GitHub integration
|
15
15
|
email:
|