| blob | 97e793d300116b92a25db169c26e7847c4c73434 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect1 id="tsvn-dug-patch">\r
4 <title>Creating and Applying Patches and Pull Requests</title>\r
5 <indexterm>\r
6 <primary>patch</primary>\r
7 </indexterm>\r
8 <indexterm>\r
9 <primary>diff</primary>\r
10 </indexterm>\r
11 <indexterm>\r
12 <primary>unified diff</primary>\r
13 </indexterm>\r
14 <indexterm>\r
15 <primary>pull request</primary>\r
16 </indexterm>\r
17 <indexterm>\r
18 <primary>request pull</primary>\r
19 </indexterm>\r
20 <?dbhh topicname="HIDD_FORMAT_PATCH"?>\r
21 <?dbhh topicname="HIDD_APPLY_PATCH_LIST"?>\r
22 <?dbhh topicname="HIDD_CREATEPATCH"?>\r
23 <?dbhh topicname="HIDD_REQUESTPULL"?>\r
24 <?dbhh topicname="HIDD_SENDMAIL"?>\r
25 <para>\r
26 For open source projects (like this one) everyone has read\r
27 access to the (main/public) repository, and anyone can make a contribution\r
28 to the project. So how are those contributions controlled?\r
29 If just anyone could commit changes this this central repository, the project would be permanently\r
30 unstable and probably permanently broken. In this situation the\r
31 change is managed by submitting a <firstterm>patch</firstterm> file or a <firstterm>pull request</firstterm>\r
32 to the development team, who do have write access.\r
33 They can review the changes first, and then either submit it to the\r
34 main repository or reject it back to the author.\r
35 </para>\r
36 <para>\r
37 Patch files are simply Unified-Diff files showing the differences\r
38 between your working tree and the base revision.\r
39 </para>\r
40 <para>\r
41 A pull request is an request to another repository owner to <link linkend="tsvn-dug-pull">pull</link>\r
42 changes from your repository. I.e. you must have access to a public repository where you can\r
43 <link linkend="tsvn-dug-push">push</link> your changes (normally a special branch).\r
44 </para>\r
45 <sect2 id="tsvn-dug-patch-createpatchserial">\r
46 <title>Creating a Patch Serial</title>\r
47 <para>\r
48 First you need to make <emphasis>and test</emphasis> your changes.\r
49 Then you commit your changes via\r
50 <menuchoice>\r
51 <guimenu>TortoiseGit</guimenu>\r
52 <guimenuitem>Commit...</guimenuitem>\r
53 </menuchoice>\r
54 on the parent folder, enter a good commit message. After that select\r
55 <menuchoice>\r
56 <guimenu>TortoiseGit</guimenu>\r
57 <guimenuitem>Create Patch Serial...</guimenuitem>\r
58 </menuchoice>\r
59 and choose the correct options to include your changes/commits.\r
60 </para>\r
61 <figure id="tsvn-dug-patch-dia-1">\r
62 <title>The Create Patch dialog</title>\r
63 <graphic fileref="../images/CreatePatch.png"/>\r
64 </figure>\r
65 <para>\r
66 <guilabel>Directory</guilabel> is output directory of patch.\r
67 Patch file name will be created by commit subject. \r
68 </para>\r
69 <para>\r
70 <guilabel>Since</guilabel> create patch from point. You can click\r
71 <guibutton>...</guibutton> to launch refbrowse dialog to choose branch or tag.\r
72 </para>\r
73 <para>\r
74 <guilabel>Number Commits</guilabel> is limited how much patch will created.\r
75 </para>\r
76 <para>\r
77 <guilabel>Range</guilabel> is choose range of <guilabel>from</guilabel> commit \r
78 to <guilabel>to</guilabel>. You can click <guibutton>...</guibutton> to launch\r
79 log dialog to choose commit.\r
80 </para>\r
81 <para>\r
82 <guilabel>Send Mail after create</guilabel> launch send mail dialog after patches created (see <xref linkend="tsvn-dug-patch-sendpatches"/>).\r
83 </para>\r
84 <para>\r
85 You can find more information at <xref linkend="git-format-patch(1)"/>.\r
86 </para>\r
87 <important>\r
88 <para>\r
89 Here is different to TortoiseSVN: In TortoiseSVN you directly create a patch instead of committing\r
90 your changes and create a patch of the commits afterwards. To generate a patch containing the uncommitted,\r
91 but staged, changes click on <guibutton>Save unified diff since HEAD</guibutton>.\r
92 </para>\r
93 </important>\r
94 </sect2>\r
95 <sect2 id="tsvn-dug-patch-sendpatches">\r
96 <title>Sending patches by mail</title>\r
97 <para>\r
98 In order to send patches to the upstream authors, select the patch files and then right click on them and select\r
99 <menuchoice>\r
100 <guimenu>TortoiseGit</guimenu>\r
101 <guimenuitem>Send Mail...</guimenuitem>\r
102 </menuchoice>\r
103 </para>\r
104 <para>\r
105 <figure id="tsvn-dug-patch-dia-sendpatches">\r
106 <title>The Send Patches Dialog</title>\r
107 <graphic fileref="../images/SendPatch.png"/>\r
108 </figure>\r
109 </para>\r
110 <para>\r
111 First you need to enter the receipient(s) (<guilabel>To</guilabel> and/or <guilabel>CC</guilabel>).\r
112 </para>\r
113 <para>\r
114 Depending on the mail type (<guilabel>Patch as attachment</guilabel> or <guilabel>Combine One Mail</guilabel>)\r
115 you have to enter a <guilabel>Subject</guilabel> for the mail.\r
116 </para>\r
117 <para>\r
118 <guilabel>Patch as attachment</guilabel> adds the patch(es) as attachment(s) to the mail(s) instead of inlining them.\r
119 </para>\r
120 <para>\r
121 <guilabel>Combine One Mail</guilabel> adds all patches to one mail. You have to enter a <guilabel>Subject</guilabel>\r
122 for the mail in this case.\r
123 </para>\r
124 <para>\r
125 <guilabel>Use MAPI</guilabel> uses the Windows MAPI interface for sending the mails. This requires a MUA to be configured on your system.\r
126 </para>\r
127 <important>\r
128 <para>\r
129 If you do not select <guilabel>Use MAPI</guilabel> mails are delivered via SMTP directly to the destination MTA.\r
130 This might be problematic if your ISP blocks outgoing SMTP connections (port 25) or you have a dialup internet connection.\r
131 In the ladder case the destination MTA might not accept your mails or marks them as SPAM.\r
132 </para>\r
133 </important>\r
134 </sect2>\r
135 <sect2 id="tsvn-dug-patch-applysinglepatch">\r
136 <title>Applying a single Patch File</title>\r
137 <para>\r
138 Patch files are applied to your working tree. This should be done\r
139 from the same folder level as was used to create the patch.\r
140 If you are not sure what this is, just look at the first line of\r
141 the patch file. For example, if the first file being worked on was\r
142 <filename>doc/source/english/chapter1.xml</filename>\r
143 and the first line in the patch file is\r
144 <filename>Index: english/chapter1.xml</filename>\r
145 then you need to apply the patch to the\r
146 <filename>doc/source/</filename> folder.\r
147 However, provided you are in the correct working tree, if you\r
148 pick the wrong folder level, TortoiseGit will notice and suggest the\r
149 correct level.\r
150 </para>\r
151 <para>\r
152 From the context menu for a patch file (<filename>.patch</filename>\r
153 or <filename>.diff</filename> extension), click on\r
154 <menuchoice>\r
155 <guimenu>TortoiseGit</guimenu>\r
156 <guimenuitem>Review/apply single patch...</guimenuitem>\r
157 </menuchoice>\r
158 You might be prompted to enter a working tree location:\r
159 <figure id="tsvn-dug-choose-repository">\r
160 <title>The Choose Repository Dialog</title>\r
161 <graphic fileref="../images/ChooseRepository.png"/>\r
162 </figure>\r
163 If the working tree is found, TortoiseMerge is launched to show and apply differences.\r
164 </para>\r
165 </sect2>\r
166 <sect2 id="tsvn-dug-patch-applaypatchserial">\r
167 <title>Applying a Patch Serial</title>\r
168 <para>\r
169 Patch files are applied to your working tree. For this copy the patch (or mbox)\r
170 files to the root of your working tree.\r
171 </para>\r
172 <para>\r
173 From the context menu for that folder (or all marked patch files), click on\r
174 <menuchoice>\r
175 <guimenu>TortoiseGit</guimenu>\r
176 <guimenuitem>Apply Patch Serial...</guimenuitem>\r
177 </menuchoice>\r
178 <figure id="tsvn-dug-apply-patch">\r
179 <title>The Apply Patch Dialog</title>\r
180 <graphic fileref="../images/ApplyPatch.png"/>\r
181 </figure>\r
182 </para>\r
183 \r
184 <para>\r
185 <guibutton>Add</guibutton> Insert patch\r
186 </para>\r
187 <para>\r
188 <guibutton>Up</guibutton> Move chosen patch up.\r
189 </para>\r
190 <para>\r
191 <guibutton>Down</guibutton> Move chosen patch down.\r
192 </para>\r
193 <para>\r
194 <guibutton>Remove</guibutton> Remove the chosen patch.\r
195 </para>\r
196 <para>\r
197 <guibutton>Apply</guibutton> Start applying the patches one by one.\r
198 </para>\r
199 <para>\r
200 You can find more information at <xref linkend="git-am(1)"/>.\r
201 </para>\r
202 </sect2>\r
203 <sect2 id="tsvn-dug-patch-pullrequest">\r
204 <title>Creating a pull request</title>\r
205 <para>\r
206 Apart from sending patches (or patch serials) to other developers,\r
207 there are two ways to ask other people to integrate your changes\r
208 into their repositories.\r
209 </para>\r
210 <para>\r
211 <emphasis>First:</emphasis> After pushing your changes to a (public)\r
212 repository, you just provide other people the URL of your repository\r
213 and the name of the branch or the revision id.\r
214 E.g.: <literal>git://example.com/repo.git BRANCHNAME</literal>\r
215 </para>\r
216 <para>\r
217 <emphasis>Second:</emphasis> After pushing your changes to a (public)\r
218 repository, you can create a standardized (quite formal) request for other\r
219 people to pull your changes and integrate them into their repository.\r
220 The format pull request consists of a list of all commits and provides\r
221 some statistics about changed files, so that other people can can a quick overview.\r
222 </para>\r
223 <para>\r
224 Select <guibutton>Request pull</guibutton> on the progress dialog after pushing your changes.\r
225 <figure id="tsvn-dug-request-pull">\r
226 <title>The Request Pull Dialog</title>\r
227 <graphic fileref="../images/RequestPull.png"/>\r
228 </figure>\r
229 </para>\r
230 <variablelist>\r
231 <varlistentry>\r
232 <term><guilabel>Start</guilabel></term>\r
233 <listitem>\r
234 <para>\r
235 This should be the revision on which your changes are based on.\r
236 </para>\r
237 </listitem>\r
238 </varlistentry>\r
239 <varlistentry>\r
240 <term><guilabel>URL</guilabel></term>\r
241 <listitem>\r
242 <para>\r
243 The public URL to your repository, which can be access\r
244 by the people who shall pull your changes.\r
245 </para>\r
246 </listitem>\r
247 </varlistentry>\r
248 <varlistentry>\r
249 <term><guilabel>End</guilabel></term>\r
250 <listitem>\r
251 <para>\r
252 This should be the branch name or revision id of the end of your commits.\r
253 </para>\r
254 </listitem>\r
255 </varlistentry>\r
256 </variablelist>\r
257 <para>\r
258 After clicking on <guibutton>OK</guibutton> the pull request is created. Just copy it\r
259 and pass it to other people who you want to pull your changes.\r
260 </para>\r
261 <para>\r
262 You can find more information at <xref linkend="git-request-pull(1)"/>.\r
263 </para>\r
264 </sect2>\r
265 </sect1>\r