1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
---
layout: default
title: Sending pull requests
description: How to notify others of your changes using Pull Requests.
categories: collaborating
main_category: collaborating
---
<style type="text/css">
.main img {
border:1px solid #eee;
padding:5px;
}
.main img.inline {
vertical-align:middle;
border:0;
}
</style>
Pull requests let you tell others about changes you've pushed to a GitHub
repository. Once a pull request is sent, interested parties can review the set
of changes, discuss potential modifications, and even push follow-up commits if
necessary.
This guide walks through the process of sending a hypothetical pull request and
using the various code review and management tools to take the change to
completion.
## A Quick Note on Collaborative Development Models
There are two popular models of collaborative development on GitHub:
1. The *Fork + Pull Model* lets anyone fork an existing repository and
push changes to their personal fork without requiring access be granted
to the source repository. The changes must then be pulled into the source
repository by the project maintainer. This model reduces the amount of
friction for new contributors and is popular with open source projects
because it allows people to work independently without upfront
coordination.
2. The *Shared Repository Model* is more prevalent with small teams and
organizations collaborating on private projects. Everyone is granted push
access to a single shared repository and topic branches are used to isolate
changes.
Pull requests are especially useful in the *Fork + Pull Model* because they
provide a way to notify project maintainers about changes in your fork. However,
they're also useful in the *Shared Repository Model* where they're used to
initiate code review and general discussion about a set of changes before being
merged into a mainline branch.
## Before You Begin
This guide assumes that [you have a GitHub account](http://github.com/signup),
that you've forked an existing repository and pushed your changes. For help with
forking and pushing changes, see the [Forking a project](/forking/) topic.
## Initiating The Pull Request
In the following example, **kneath** has completed some work on an error page
for the GitHub Jobs web application, pushed three commits to a topic branch in
his fork, and would like someone to review and merge.
Navigate to your repository with the changes you want someone else to pull and
press the *Pull Request* button.
Pull requests can be sent from any branch or commit but it's recommended that a
topic branch be used so that follow-up commits can be pushed to update the pull
request if necessary.
## Previewing The Pull Request
After pressing the *Pull Request* button, you are presented with a preview page
where you can enter a title and optional description, see exactly what
commits will be included when the pull request is sent, and also see who the
pull request will be sent to:
If you're sending from a topic branch, the title is pre-filled based on the name
of the branch. Markdown is supported in the description, so you can embed images
or use preformatted text blocks.
Switch to the *Commits* tab to ensure that the correct set of changes is being
sent:
Review the diff of all changes by switching to the *Files Changed* tab:
## Changing The Commit Range and Destination Repository
By default, pull requests are assumed to be based on the parent-most
repository's integration branch. In this case, the `kneath/jobs` repository was
forked from `github/jobs` so the pull request is assumed to be based on the
`master` branch of the `github/jobs` repository. In a great majority of cases,
the defaults will be right; however, if any of this information is incorrect, press
the *Change Commits* button.
The commit range selector will expand, allowing the base repository, base
branch, and head branch to be customized:
The easiest way of thinking about the commit range is this: the *base branch* is
**where** you think changes should be applied, the *head branch* is **what** you
would like to be applied.
Changing the base repository changes who is notified of the pull request.
Everyone that can push to the base repository will receive an email notification
and see the new pull request in their dashboard the next time they log in.
Once you're happy with the commit range, press the *Update Commit Range* button
to update the commit and files changed preview areas.
## Sending The Pull Request
Once you've entered the title and description, made any necessary customizations
to the commit range, and reviewed the commits and file changes to be sent, press
the *Send pull request* button.
The pull request is sent immediately. You're taken to the main pull request
discussion and review page. Additionally, all repository collaborators and
followers will see an event in their dashboard:
## Managing Pull Requests
All pull requests sent or received by you are browseable through the pull
request dashboard.
Pull requests for a specific repository are also browseable by anyone with
access by visiting the *Network -> Pull Requests* page.
The pull request dashboard and the repository pull request list support a wide
range of filtering and sorting controls. Use them to narrow down the list to
the pull requests you're interested in.
## Reviewing Proposed Changes
When you receive a pull request, the first thing to do is review the set of
proposed changes. Pull requests are tightly integrated with the underlying git
repository, so you can see exactly what commits would be merged should the
request be accepted:
You can also review the cumulative diff of all file changes across all commits.
## Pull Request Discussion
After reviewing the basic description, commits, and cumulative diff, the person
tasked with applying the changes may have questions or comments. Perhaps the
coding style doesn't match project guideline, or the change is missing unit
tests, or maybe everything looks great and some props are in order. The
discussion view is designed to encourage and capture this type of discussion.
The discussion view starts with the pull request's original title and
description and then captures additional activity to display chronologically
from there. Any of the following types of activity are captured as they happen:
* Comments left on the pull request itself.
* Additional commits pushed to the pull request's branch.
* File and line notes left on any of the commits included in the pull request's range.
Pull request comments are Markdown compatibility, so you can embed images, use
preformatted text blocks, and other formatting supported by Markdown.
## Merging a Pull Request
Once the pull request is deemed satisfactory, someone with push access to the
destination repository must apply the changes and push the updated branch.
There are a variety of ways to accomplish this. Two popular methods are
described below.
#### Fetch and Merge
This is the most common method of fetching and applying changes. It requires
adding a remote for the person that sent the pull request, fetching from that
repository, merging the requested branch, fixing any conflicts, and pushing
the newly merged branch back to the repository:
<pre class="console">
<span>$</span> git checkout master
<span>$</span> git remote add kneath git://github.com/kneath/jobs.git
<span>$</span> git fetch kneath
<span>$</span> git merge kneath/error-page
<span>$</span> git push origin master
</pre>
#### Patch and Apply
The *fetch and merge* approach works great when you're working on a team or
repeatedly applying changes from the same small group of people. Another
approach that's a bit quicker in one-off cases is to use `git-am`.
Every pull request has a `.patch` URL where you can grab a textual patch file
to feed into the `git-am` command:
<pre class="console">
<span>$</span> git checkout master
<span>$</span> curl http://github.com/github/jobs/pull/25.patch | git am
<span>$</span> git push origin master
</pre>
## Closing a Pull Request
Pull Requests are automatically closed when the requested commits are merged
into the destination repository. An event is generated to let all repository
collaborators and followers know that the merge occurred:
It's also possible to manually close a pull request in cases where the set of
changes are rejected. This is also sometimes necessary if the changes are
applied with `git-cherry-pick` or using some other mechanism that disallows the
merge from being detected.
|
