]>
Commit | Line | Data |
---|---|---|
adcc42e6 JH |
1 | Here are some guidelines for people who want to contribute their code |
2 | to this software. | |
31408251 | 3 | |
d0c26f0f RR |
4 | (0) Decide what to base your work on. |
5 | ||
6 | In general, always base your work on the oldest branch that your | |
7 | change is relevant to. | |
8 | ||
9 | - A bugfix should be based on 'maint' in general. If the bug is not | |
10 | present in 'maint', base it on 'master'. For a bug that's not yet | |
11 | in 'master', find the topic that introduces the regression, and | |
12 | base your work on the tip of the topic. | |
13 | ||
14 | - A new feature should be based on 'master' in general. If the new | |
15 | feature depends on a topic that is in 'pu', but not in 'master', | |
16 | base your work on the tip of that topic. | |
17 | ||
18 | - Corrections and enhancements to a topic not yet in 'master' should | |
19 | be based on the tip of that topic. If the topic has not been merged | |
20 | to 'next', it's alright to add a note to squash minor corrections | |
21 | into the series. | |
22 | ||
23 | - In the exceptional case that a new feature depends on several topics | |
24 | not in 'master', start working on 'next' or 'pu' privately and send | |
25 | out patches for discussion. Before the final merge, you may have to | |
26 | wait until some of the dependent topics graduate to 'master', and | |
27 | rebase your work. | |
28 | ||
e6da8ee8 JH |
29 | - Some parts of the system have dedicated maintainers with their own |
30 | repositories (see the section "Subsystems" below). Changes to | |
31 | these parts should be based on their trees. | |
32 | ||
d0c26f0f RR |
33 | To find the tip of a topic branch, run "git log --first-parent |
34 | master..pu" and look for the merge commit. The second parent of this | |
35 | commit is the tip of the topic branch. | |
31408251 JH |
36 | |
37 | (1) Make separate commits for logically separate changes. | |
38 | ||
39 | Unless your patch is really trivial, you should not be sending | |
40 | out a patch that was generated between your working tree and | |
41 | your commit head. Instead, always make a commit with complete | |
42 | commit message and generate a series of patches from your | |
43 | repository. It is a good discipline. | |
44 | ||
d0f7dcbf JH |
45 | Give an explanation for the change(s) that is detailed enough so |
46 | that people can judge if it is good thing to do, without reading | |
47 | the actual patch text to determine how well the code does what | |
48 | the explanation promises to do. | |
31408251 | 49 | |
45d2b286 | 50 | If your description starts to get too long, that's a sign that you |
31408251 | 51 | probably need to split up your commit to finer grained pieces. |
47afed5d SV |
52 | That being said, patches which plainly describe the things that |
53 | help reviewers check the patch, and future maintainers understand | |
54 | the code, are the most beautiful patches. Descriptions that summarise | |
55 | the point in the subject well, and describe the motivation for the | |
56 | change, the approach taken by the change, and if relevant how this | |
d0f7dcbf JH |
57 | differs substantially from the prior version, are all good things |
58 | to have. | |
31408251 | 59 | |
7d5bf87b JH |
60 | Make sure that you have tests for the bug you are fixing. |
61 | ||
62 | When adding a new feature, make sure that you have new tests to show | |
63 | the feature triggers the new behaviour when it should, and to show the | |
64 | feature does not trigger when it shouldn't. Also make sure that the | |
65 | test suite passes after your commit. Do not forget to update the | |
66 | documentation to describe the updated behaviour. | |
67 | ||
45d2b286 JH |
68 | Oh, another thing. I am picky about whitespaces. Make sure your |
69 | changes do not trigger errors with the sample pre-commit hook shipped | |
16507fcf BL |
70 | in templates/hooks--pre-commit. To help ensure this does not happen, |
71 | run git diff --check on your changes before you commit. | |
31408251 | 72 | |
31408251 | 73 | |
7d5bf87b JH |
74 | (2) Describe your changes well. |
75 | ||
76 | The first line of the commit message should be a short description (50 | |
77 | characters is the soft limit, see DISCUSSION in git-commit(1)), and | |
78 | should skip the full stop. It is also conventional in most cases to | |
79 | prefix the first line with "area: " where the area is a filename or | |
80 | identifier for the general area of the code being modified, e.g. | |
81 | ||
82 | . archive: ustar header checksum is computed unsigned | |
83 | . git-cherry-pick.txt: clarify the use of revision range notation | |
84 | ||
85 | If in doubt which identifier to use, run "git log --no-merges" on the | |
86 | files you are modifying to see the current conventions. | |
87 | ||
88 | The body should provide a meaningful commit message, which: | |
89 | ||
90 | . explains the problem the change tries to solve, iow, what is wrong | |
91 | with the current code without the change. | |
92 | ||
93 | . justifies the way the change solves the problem, iow, why the | |
94 | result with the change is better. | |
95 | ||
96 | . alternate solutions considered but discarded, if any. | |
97 | ||
98 | Describe your changes in imperative mood, e.g. "make xyzzy do frotz" | |
99 | instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy | |
100 | to do frotz", as if you are giving orders to the codebase to change | |
101 | its behaviour. Try to make sure your explanation can be understood | |
102 | without external resources. Instead of giving a URL to a mailing list | |
103 | archive, summarize the relevant points of the discussion. | |
104 | ||
105 | ||
2de9b711 | 106 | (3) Generate your patch using Git tools out of your commits. |
45d2b286 | 107 | |
2de9b711 | 108 | Git based diff tools generate unidiff which is the preferred format. |
45d2b286 | 109 | |
31408251 JH |
110 | You do not have to be afraid to use -M option to "git diff" or |
111 | "git format-patch", if your patch involves file renames. The | |
112 | receiving end can handle them just fine. | |
113 | ||
7d5bf87b JH |
114 | Please make sure your patch does not add commented out debugging code, |
115 | or include any extra files which do not relate to what your patch | |
116 | is trying to achieve. Make sure to review | |
31408251 JH |
117 | your patch after generating it, to ensure accuracy. Before |
118 | sending out, please make sure it cleanly applies to the "master" | |
45d2b286 JH |
119 | branch head. If you are preparing a work based on "next" branch, |
120 | that is fine, but please mark it as such. | |
31408251 JH |
121 | |
122 | ||
7d5bf87b | 123 | (4) Sending your patches. |
31408251 | 124 | |
2de9b711 | 125 | People on the Git mailing list need to be able to read and |
31408251 JH |
126 | comment on the changes you are submitting. It is important for |
127 | a developer to be able to "quote" your changes, using standard | |
128 | e-mail tools, so that they may comment on specific portions of | |
addf88e4 | 129 | your code. For this reason, all patches should be submitted |
7d5bf87b JH |
130 | "inline". If your log message (including your name on the |
131 | Signed-off-by line) is not writable in ASCII, make sure that | |
132 | you send off a message in the correct encoding. | |
133 | ||
134 | WARNING: Be wary of your MUAs word-wrap | |
45d2b286 JH |
135 | corrupting your patch. Do not cut-n-paste your patch; you can |
136 | lose tabs that way if you are not careful. | |
31408251 | 137 | |
45d2b286 | 138 | It is a common convention to prefix your subject line with |
31408251 | 139 | [PATCH]. This lets people easily distinguish patches from other |
4e891acf JH |
140 | e-mail discussions. Use of additional markers after PATCH and |
141 | the closing bracket to mark the nature of the patch is also | |
142 | encouraged. E.g. [PATCH/RFC] is often used when the patch is | |
143 | not ready to be applied but it is for discussion, [PATCH v2], | |
144 | [PATCH v3] etc. are often seen when you are sending an update to | |
145 | what you have previously sent. | |
31408251 JH |
146 | |
147 | "git format-patch" command follows the best current practice to | |
148 | format the body of an e-mail message. At the beginning of the | |
149 | patch should come your commit message, ending with the | |
150 | Signed-off-by: lines, and a line that consists of three dashes, | |
151 | followed by the diffstat information and the patch itself. If | |
152 | you are forwarding a patch from somebody else, optionally, at | |
153 | the beginning of the e-mail message just before the commit | |
154 | message starts, you can put a "From: " line to name that person. | |
155 | ||
156 | You often want to add additional explanation about the patch, | |
157 | other than the commit message itself. Place such "cover letter" | |
76323c67 PO |
158 | material between the three dash lines and the diffstat. Git-notes |
159 | can also be inserted using the `--notes` option. | |
31408251 JH |
160 | |
161 | Do not attach the patch as a MIME attachment, compressed or not. | |
e30b217b JH |
162 | Do not let your e-mail client send quoted-printable. Do not let |
163 | your e-mail client send format=flowed which would destroy | |
164 | whitespaces in your patches. Many | |
31408251 JH |
165 | popular e-mail applications will not always transmit a MIME |
166 | attachment as plain text, making it impossible to comment on | |
167 | your code. A MIME attachment also takes a bit more time to | |
168 | process. This does not decrease the likelihood of your | |
169 | MIME-attached change being accepted, but it makes it more likely | |
170 | that it will be postponed. | |
171 | ||
172 | Exception: If your mailer is mangling patches then someone may ask | |
9847f7e0 | 173 | you to re-send them using MIME, that is OK. |
31408251 | 174 | |
9847f7e0 JH |
175 | Do not PGP sign your patch, at least for now. Most likely, your |
176 | maintainer or other people on the list would not have your PGP | |
177 | key and would not bother obtaining it anyway. Your patch is not | |
178 | judged by who you are; a good patch from an unknown origin has a | |
179 | far better chance of being accepted than a patch from a known, | |
180 | respected origin that is done poorly or does incorrect things. | |
181 | ||
182 | If you really really really really want to do a PGP signed | |
183 | patch, format it as "multipart/signed", not a text/plain message | |
184 | that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is | |
185 | not a text/plain, it's something else. | |
186 | ||
7d5bf87b | 187 | Send your patch with "To:" set to the mailing list, with "cc:" listing |
d0c26f0f RR |
188 | people who are involved in the area you are touching (the output from |
189 | "git blame $path" and "git shortlog --no-merges $path" would help to | |
7d5bf87b | 190 | identify them), to solicit comments and reviews. |
04d24455 | 191 | |
7d5bf87b | 192 | After the list reached a consensus that it is a good idea to apply the |
92a865e7 JH |
193 | patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the |
194 | list [*2*] for inclusion. | |
31408251 | 195 | |
7d5bf87b JH |
196 | Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and |
197 | "Tested-by:" lines as necessary to credit people who helped your | |
198 | patch. | |
04d24455 | 199 | |
92a865e7 JH |
200 | [Addresses] |
201 | *1* The current maintainer: gitster@pobox.com | |
202 | *2* The mailing list: git@vger.kernel.org | |
203 | ||
31408251 | 204 | |
7d5bf87b | 205 | (5) Sign your work |
31408251 JH |
206 | |
207 | To improve tracking of who did what, we've borrowed the | |
208 | "sign-off" procedure from the Linux kernel project on patches | |
48a8c26c | 209 | that are being emailed around. Although core Git is a lot |
31408251 JH |
210 | smaller project it is a good discipline to follow it. |
211 | ||
212 | The sign-off is a simple line at the end of the explanation for | |
213 | the patch, which certifies that you wrote it or otherwise have | |
214 | the right to pass it on as a open-source patch. The rules are | |
215 | pretty simple: if you can certify the below: | |
216 | ||
217 | Developer's Certificate of Origin 1.1 | |
218 | ||
219 | By making a contribution to this project, I certify that: | |
220 | ||
221 | (a) The contribution was created in whole or in part by me and I | |
222 | have the right to submit it under the open source license | |
223 | indicated in the file; or | |
224 | ||
225 | (b) The contribution is based upon previous work that, to the best | |
226 | of my knowledge, is covered under an appropriate open source | |
227 | license and I have the right under that license to submit that | |
228 | work with modifications, whether created in whole or in part | |
229 | by me, under the same open source license (unless I am | |
230 | permitted to submit under a different license), as indicated | |
231 | in the file; or | |
232 | ||
233 | (c) The contribution was provided directly to me by some other | |
234 | person who certified (a), (b) or (c) and I have not modified | |
235 | it. | |
236 | ||
237 | (d) I understand and agree that this project and the contribution | |
238 | are public and that a record of the contribution (including all | |
239 | personal information I submit with it, including my sign-off) is | |
240 | maintained indefinitely and may be redistributed consistent with | |
241 | this project or the open source license(s) involved. | |
242 | ||
243 | then you just add a line saying | |
244 | ||
245 | Signed-off-by: Random J Developer <random@developer.example.org> | |
246 | ||
2de9b711 | 247 | This line can be automatically added by Git if you run the git-commit |
69945602 PC |
248 | command with the -s option. |
249 | ||
c11c3b56 JH |
250 | Notice that you can place your own Signed-off-by: line when |
251 | forwarding somebody else's patch with the above rules for | |
252 | D-C-O. Indeed you are encouraged to do so. Do not forget to | |
253 | place an in-body "From: " line at the beginning to properly attribute | |
254 | the change to its true author (see (2) above). | |
255 | ||
67275247 MV |
256 | Also notice that a real name is used in the Signed-off-by: line. Please |
257 | don't hide your real name. | |
258 | ||
95b7a41a RR |
259 | If you like, you can put extra tags at the end: |
260 | ||
0353a0c4 | 261 | 1. "Reported-by:" is used to credit someone who found the bug that |
95b7a41a RR |
262 | the patch attempts to fix. |
263 | 2. "Acked-by:" says that the person who is more familiar with the area | |
264 | the patch attempts to modify liked the patch. | |
265 | 3. "Reviewed-by:", unlike the other tags, can only be offered by the | |
266 | reviewer and means that she is completely satisfied that the patch | |
267 | is ready for application. It is usually offered only after a | |
268 | detailed review. | |
269 | 4. "Tested-by:" is used to indicate that the person applied the patch | |
270 | and found it to have the desired effect. | |
271 | ||
272 | You can also create your own tag or use one that's in common usage | |
273 | such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". | |
9740d289 | 274 | |
e6da8ee8 JH |
275 | ------------------------------------------------ |
276 | Subsystems with dedicated maintainers | |
277 | ||
278 | Some parts of the system have dedicated maintainers with their own | |
279 | repositories. | |
280 | ||
281 | - git-gui/ comes from git-gui project, maintained by Pat Thoyts: | |
282 | ||
283 | git://repo.or.cz/git-gui.git | |
284 | ||
285 | - gitk-git/ comes from Paul Mackerras's gitk project: | |
286 | ||
287 | git://ozlabs.org/~paulus/gitk | |
288 | ||
289 | - po/ comes from the localization coordinator, Jiang Xin: | |
290 | ||
291 | https://github.com/git-l10n/git-po/ | |
292 | ||
293 | Patches to these parts should be based on their trees. | |
294 | ||
a941fb4a JH |
295 | ------------------------------------------------ |
296 | An ideal patch flow | |
297 | ||
298 | Here is an ideal patch flow for this project the current maintainer | |
299 | suggests to the contributors: | |
300 | ||
301 | (0) You come up with an itch. You code it up. | |
302 | ||
303 | (1) Send it to the list and cc people who may need to know about | |
304 | the change. | |
305 | ||
306 | The people who may need to know are the ones whose code you | |
307 | are butchering. These people happen to be the ones who are | |
308 | most likely to be knowledgeable enough to help you, but | |
309 | they have no obligation to help you (i.e. you ask for help, | |
310 | don't demand). "git log -p -- $area_you_are_modifying" would | |
311 | help you find out who they are. | |
312 | ||
313 | (2) You get comments and suggestions for improvements. You may | |
314 | even get them in a "on top of your change" patch form. | |
315 | ||
316 | (3) Polish, refine, and re-send to the list and the people who | |
317 | spend their time to improve your patch. Go back to step (2). | |
318 | ||
319 | (4) The list forms consensus that the last round of your patch is | |
320 | good. Send it to the list and cc the maintainer. | |
321 | ||
322 | (5) A topic branch is created with the patch and is merged to 'next', | |
323 | and cooked further and eventually graduates to 'master'. | |
324 | ||
325 | In any time between the (2)-(3) cycle, the maintainer may pick it up | |
326 | from the list and queue it to 'pu', in order to make it easier for | |
327 | people play with it without having to pick up and apply the patch to | |
328 | their trees themselves. | |
329 | ||
63cb8215 MM |
330 | ------------------------------------------------ |
331 | Know the status of your patch after submission | |
332 | ||
333 | * You can use Git itself to find out when your patch is merged in | |
334 | master. 'git pull --rebase' will automatically skip already-applied | |
335 | patches, and will let you know. This works only if you rebase on top | |
336 | of the branch in which your patch has been merged (i.e. it will not | |
337 | tell you if your patch is merged in pu if you rebase on top of | |
338 | master). | |
339 | ||
2de9b711 | 340 | * Read the Git mailing list, the maintainer regularly posts messages |
63cb8215 MM |
341 | entitled "What's cooking in git.git" and "What's in git.git" giving |
342 | the status of various proposed changes. | |
343 | ||
9740d289 JH |
344 | ------------------------------------------------ |
345 | MUA specific hints | |
346 | ||
347 | Some of patches I receive or pick up from the list share common | |
348 | patterns of breakage. Please make sure your MUA is set up | |
57756161 JN |
349 | properly not to corrupt whitespaces. |
350 | ||
351 | See the DISCUSSION section of git-format-patch(1) for hints on | |
352 | checking your patch by mailing it to yourself and applying with | |
353 | git-am(1). | |
354 | ||
355 | While you are at it, check the resulting commit log message from | |
356 | a trial run of applying the patch. If what is in the resulting | |
357 | commit is not exactly what you would want to see, it is very | |
358 | likely that your maintainer would end up hand editing the log | |
359 | message when he applies your patch. Things like "Hi, this is my | |
360 | first patch.\n", if you really want to put in the patch e-mail, | |
361 | should come after the three-dash line that signals the end of the | |
362 | commit message. | |
9847f7e0 | 363 | |
9740d289 JH |
364 | |
365 | Pine | |
366 | ---- | |
367 | ||
368 | (Johannes Schindelin) | |
369 | ||
370 | I don't know how many people still use pine, but for those poor | |
371 | souls it may be good to mention that the quell-flowed-text is | |
372 | needed for recent versions. | |
373 | ||
374 | ... the "no-strip-whitespace-before-send" option, too. AFAIK it | |
375 | was introduced in 4.60. | |
376 | ||
377 | (Linus Torvalds) | |
378 | ||
379 | And 4.58 needs at least this. | |
380 | ||
381 | --- | |
382 | diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) | |
383 | Author: Linus Torvalds <torvalds@g5.osdl.org> | |
384 | Date: Mon Aug 15 17:23:51 2005 -0700 | |
385 | ||
386 | Fix pine whitespace-corruption bug | |
387 | ||
388 | There's no excuse for unconditionally removing whitespace from | |
389 | the pico buffers on close. | |
390 | ||
391 | diff --git a/pico/pico.c b/pico/pico.c | |
392 | --- a/pico/pico.c | |
393 | +++ b/pico/pico.c | |
394 | @@ -219,7 +219,9 @@ PICO *pm; | |
a6080a0a JH |
395 | switch(pico_all_done){ /* prepare for/handle final events */ |
396 | case COMP_EXIT : /* already confirmed */ | |
397 | packheader(); | |
9740d289 | 398 | +#if 0 |
a6080a0a | 399 | stripwhitespace(); |
9740d289 | 400 | +#endif |
a6080a0a JH |
401 | c |= COMP_EXIT; |
402 | break; | |
403 | ||
9740d289 | 404 | |
1eb446fa JH |
405 | (Daniel Barkalow) |
406 | ||
407 | > A patch to SubmittingPatches, MUA specific help section for | |
408 | > users of Pine 4.63 would be very much appreciated. | |
409 | ||
410 | Ah, it looks like a recent version changed the default behavior to do the | |
411 | right thing, and inverted the sense of the configuration option. (Either | |
412 | that or Gentoo did it.) So you need to set the | |
413 | "no-strip-whitespace-before-send" option, unless the option you have is | |
414 | "strip-whitespace-before-send", in which case you should avoid checking | |
415 | it. | |
416 | ||
9740d289 | 417 | |
36c10e6d JN |
418 | Thunderbird, KMail, GMail |
419 | ------------------------- | |
9740d289 | 420 | |
dc53151f | 421 | See the MUA-SPECIFIC HINTS section of git-format-patch(1). |
e30b217b | 422 | |
e30b217b JH |
423 | Gnus |
424 | ---- | |
425 | ||
426 | '|' in the *Summary* buffer can be used to pipe the current | |
427 | message to an external program, and this is a handy way to drive | |
428 | "git am". However, if the message is MIME encoded, what is | |
429 | piped into the program is the representation you see in your | |
430 | *Article* buffer after unwrapping MIME. This is often not what | |
431 | you would want for two reasons. It tends to screw up non ASCII | |
432 | characters (most notably in people's names), and also | |
433 | whitespaces (fatal in patches). Running 'C-u g' to display the | |
434 | message in raw form before using '|' to run the pipe can work | |
435 | this problem around. |