]>
Commit | Line | Data |
---|---|---|
049e64aa | 1 | Submitting Patches |
2 | ================== | |
3 | ||
4 | == Guidelines | |
5 | ||
fc0825d5 LA |
6 | Here are some guidelines for contributing back to this |
7 | project. There is also a link:MyFirstContribution.html[step-by-step tutorial] | |
b75a2199 | 8 | available which covers many of these same guidelines. |
31408251 | 9 | |
d58848fb | 10 | [[patch-flow]] |
120adc7d | 11 | === A typical life cycle of a patch series |
d58848fb | 12 | |
120adc7d JH |
13 | To help us understand the reason behind various guidelines given later |
14 | in the document, first let's understand how the life cycle of a | |
15 | typical patch series for this project goes. | |
d58848fb | 16 | |
120adc7d JH |
17 | . You come up with an itch. You code it up. You do not need any |
18 | pre-authorization from the project to do so. | |
19 | + | |
20 | Your patches will be reviewed by other contributors on the mailing | |
21 | list, and the reviews will be done to assess the merit of various | |
22 | things, like the general idea behind your patch (including "is it | |
23 | solving a problem worth solving in the first place?"), the reason | |
24 | behind the design of the solution, and the actual implementation. | |
25 | The guidelines given here are there to help your patches by making | |
26 | them easier to understand by the reviewers. | |
27 | ||
28 | . You send the patches to the list and cc people who may need to know | |
29 | about the change. Your goal is *not* necessarily to convince others | |
30 | that what you are building is good. Your goal is to get help in | |
31 | coming up with a solution for the "itch" that is better than what | |
32 | you can build alone. | |
d58848fb | 33 | + |
120adc7d JH |
34 | The people who may need to know are the ones who worked on the code |
35 | you are touching. These people happen to be the ones who are | |
d58848fb | 36 | most likely to be knowledgeable enough to help you, but |
120adc7d JH |
37 | they have no obligation to help you (i.e. you ask them for help, |
38 | you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would | |
d58848fb JH |
39 | help you find out who they are. |
40 | ||
120adc7d JH |
41 | . You get comments and suggestions for improvements. You may even get |
42 | them in an "on top of your change" patch form. You are expected to | |
43 | respond to them with "Reply-All" on the mailing list, while taking | |
44 | them into account while preparing an updated set of patches. | |
45 | ||
46 | . Polish, refine, and re-send your patches to the list and to the people | |
47 | who spent their time to improve your patch. Go back to step (2). | |
48 | ||
49 | . While the above iterations improve your patches, the maintainer may | |
50 | pick the patches up from the list and queue them to the `seen` | |
51 | branch, in order to make it easier for people to play with it | |
52 | without having to pick up and apply the patches to their trees | |
53 | themselves. Being in `seen` has no other meaning. Specifically, it | |
54 | does not mean the patch was "accepted" in any way. | |
55 | ||
56 | . When the discussion reaches a consensus that the latest iteration of | |
57 | the patches are in good enough shape, the maintainer includes the | |
58 | topic in the "What's cooking" report that are sent out a few times a | |
59 | week to the mailing list, marked as "Will merge to 'next'." This | |
60 | decision is primarily made by the maintainer with help from those | |
61 | who participated in the review discussion. | |
62 | ||
63 | . After the patches are merged to the 'next' branch, the discussion | |
64 | can still continue to further improve them by adding more patches on | |
65 | top, but by the time a topic gets merged to 'next', it is expected | |
66 | that everybody agrees that the scope and the basic direction of the | |
67 | topic are appropriate, so such an incremental updates are limited to | |
68 | small corrections and polishing. After a topic cooks for some time | |
69 | (like 7 calendar days) in 'next' without needing further tweaks on | |
70 | top, it gets merged to the 'master' branch and wait to become part | |
71 | of the next major release. | |
72 | ||
73 | In the following sections, many techniques and conventions are listed | |
74 | to help your patches get reviewed effectively in such a life cycle. | |
d58848fb | 75 | |
d58848fb | 76 | |
b5dbfe28 LA |
77 | [[choose-starting-point]] |
78 | === Choose a starting point. | |
d0c26f0f | 79 | |
0a02ca23 LA |
80 | As a preliminary step, you must first choose a starting point for your |
81 | work. Typically this means choosing a branch, although technically | |
82 | speaking it is actually a particular commit (typically the HEAD, or tip, | |
83 | of the branch). | |
84 | ||
85 | There are several important branches to be aware of. Namely, there are | |
86 | four integration branches as discussed in linkgit:gitworkflows[7]: | |
87 | ||
88 | * maint | |
89 | * master | |
90 | * next | |
91 | * seen | |
92 | ||
93 | The branches lower on the list are typically descendants of the ones | |
94 | that come before it. For example, `maint` is an "older" branch than | |
95 | `master` because `master` usually has patches (commits) on top of | |
96 | `maint`. | |
97 | ||
98 | There are also "topic" branches, which contain work from other | |
99 | contributors. Topic branches are created by the Git maintainer (in | |
100 | their fork) to organize the current set of incoming contributions on | |
101 | the mailing list, and are itemized in the regular "What's cooking in | |
102 | git.git" announcements. To find the tip of a topic branch, run `git log | |
103 | --first-parent master..seen` and look for the merge commit. The second | |
104 | parent of this commit is the tip of the topic branch. | |
105 | ||
106 | There is one guiding principle for choosing the right starting point: in | |
107 | general, always base your work on the oldest integration branch that | |
108 | your change is relevant to (see "Merge upwards" in | |
109 | linkgit:gitworkflows[7]). What this principle means is that for the | |
110 | vast majority of cases, the starting point for new work should be the | |
111 | latest HEAD commit of `maint` or `master` based on the following cases: | |
112 | ||
113 | * If you are fixing bugs in the released version, use `maint` as the | |
114 | starting point (which may mean you have to fix things without using | |
115 | new API features on the cutting edge that recently appeared in | |
369998df | 116 | `master` but were not available in the released version). |
0a02ca23 LA |
117 | |
118 | * Otherwise (such as if you are adding new features) use `master`. | |
119 | ||
369998df JH |
120 | |
121 | NOTE: In exceptional cases, a bug that was introduced in an old | |
122 | version may have to be fixed for users of releases that are much older | |
123 | than the recent releases. `git describe --contains X` may describe | |
124 | `X` as `v2.30.0-rc2-gXXXXXX` for the commit `X` that introduced the | |
125 | bug, and the bug may be so high-impact that we may need to issue a new | |
126 | maintenance release for Git 2.30.x series, when "Git 2.41.0" is the | |
127 | current release. In such a case, you may want to use the tip of the | |
128 | maintenance branch for the 2.30.x series, which may be available in the | |
129 | `maint-2.30` branch in https://github.com/gitster/git[the maintainer's | |
130 | "broken out" repo]. | |
131 | ||
0a02ca23 LA |
132 | This also means that `next` or `seen` are inappropriate starting points |
133 | for your work, if you want your work to have a realistic chance of | |
f835de52 JH |
134 | graduating to `master`. They are simply not designed to be used as a |
135 | base for new work; they are only there to make sure that topics in | |
136 | flight work well together. This is why both `next` and `seen` are | |
137 | frequently re-integrated with incoming patches on the mailing list and | |
138 | force-pushed to replace previous versions of themselves. A topic that is | |
139 | literally built on top of `next` cannot be merged to `master` without | |
140 | dragging in all the other topics in `next`, some of which may not be | |
141 | ready. | |
0a02ca23 LA |
142 | |
143 | For example, if you are making tree-wide changes, while somebody else is | |
144 | also making their own tree-wide changes, your work may have severe | |
145 | overlap with the other person's work. This situation may tempt you to | |
146 | use `next` as your starting point (because it would have the other | |
147 | person's work included in it), but doing so would mean you'll not only | |
148 | depend on the other person's work, but all the other random things from | |
149 | other contributors that are already integrated into `next`. And as soon | |
150 | as `next` is updated with a new version, all of your work will need to | |
151 | be rebased anyway in order for them to be cleanly applied by the | |
152 | maintainer. | |
153 | ||
154 | Under truly exceptional circumstances where you absolutely must depend | |
155 | on a select few topic branches that are already in `next` but not in | |
156 | `master`, you may want to create your own custom base-branch by forking | |
9a9fd289 | 157 | `master` and merging the required topic branches into it. You could then |
0a02ca23 LA |
158 | work on top of this base-branch. But keep in mind that this base-branch |
159 | would only be known privately to you. So when you are ready to send | |
160 | your patches to the list, be sure to communicate how you created it in | |
161 | your cover letter. This critical piece of information would allow | |
162 | others to recreate your base-branch on their end in order for them to | |
163 | try out your work. | |
31408251 | 164 | |
3423e372 LA |
165 | Finally, note that some parts of the system have dedicated maintainers |
166 | with their own separate source code repositories (see the section | |
167 | "Subsystems" below). | |
168 | ||
049e64aa | 169 | [[separate-commits]] |
170 | === Make separate commits for logically separate changes. | |
31408251 JH |
171 | |
172 | Unless your patch is really trivial, you should not be sending | |
173 | out a patch that was generated between your working tree and | |
174 | your commit head. Instead, always make a commit with complete | |
175 | commit message and generate a series of patches from your | |
176 | repository. It is a good discipline. | |
177 | ||
d0f7dcbf JH |
178 | Give an explanation for the change(s) that is detailed enough so |
179 | that people can judge if it is good thing to do, without reading | |
180 | the actual patch text to determine how well the code does what | |
181 | the explanation promises to do. | |
31408251 | 182 | |
45d2b286 | 183 | If your description starts to get too long, that's a sign that you |
31408251 | 184 | probably need to split up your commit to finer grained pieces. |
47afed5d SV |
185 | That being said, patches which plainly describe the things that |
186 | help reviewers check the patch, and future maintainers understand | |
01e60a9a | 187 | the code, are the most beautiful patches. Descriptions that summarize |
47afed5d SV |
188 | the point in the subject well, and describe the motivation for the |
189 | change, the approach taken by the change, and if relevant how this | |
d0f7dcbf JH |
190 | differs substantially from the prior version, are all good things |
191 | to have. | |
31408251 | 192 | |
54cc5d29 | 193 | Make sure that you have tests for the bug you are fixing. See |
049e64aa | 194 | `t/README` for guidance. |
7d5bf87b | 195 | |
049e64aa | 196 | [[tests]] |
7d5bf87b | 197 | When adding a new feature, make sure that you have new tests to show |
0e5d028a | 198 | the feature triggers the new behavior when it should, and to show the |
fdfae830 JH |
199 | feature does not trigger when it shouldn't. After any code change, |
200 | make sure that the entire test suite passes. When fixing a bug, make | |
201 | sure you have new tests that break if somebody else breaks what you | |
202 | fixed by accident to avoid regression. Also, try merging your work to | |
203 | 'next' and 'seen' and make sure the tests still pass; topics by others | |
204 | that are still in flight may have unexpected interactions with what | |
205 | you are trying to do in your topic. | |
0e5d028a | 206 | |
f003a91f ÆAB |
207 | Pushing to a fork of https://github.com/git/git will use their CI |
208 | integration to test your changes on Linux, Mac and Windows. See the | |
209 | <<GHCI,GitHub CI>> section for details. | |
0e5d028a LS |
210 | |
211 | Do not forget to update the documentation to describe the updated | |
212 | behavior and make sure that the resulting documentation set formats | |
7a76f5c6 JK |
213 | well (try the Documentation/doc-diff script). |
214 | ||
215 | We currently have a liberal mixture of US and UK English norms for | |
0e5d028a LS |
216 | spelling and grammar, which is somewhat unfortunate. A huge patch that |
217 | touches the files all over the place only to correct the inconsistency | |
218 | is not welcome, though. Potential clashes with other changes that can | |
219 | result from such a patch are not worth it. We prefer to gradually | |
220 | reconcile the inconsistencies in favor of US English, with small and | |
221 | easily digestible patches, as a side effect of doing some other real | |
222 | work in the vicinity (e.g. rewriting a paragraph for clarity, while | |
223 | turning en_UK spelling to en_US). Obvious typographical fixes are much | |
224 | more welcomed ("teh -> "the"), preferably submitted as independent | |
225 | patches separate from other documentation changes. | |
42e0fae9 | 226 | |
049e64aa | 227 | [[whitespace-check]] |
42e0fae9 | 228 | Oh, another thing. We are picky about whitespaces. Make sure your |
45d2b286 | 229 | changes do not trigger errors with the sample pre-commit hook shipped |
049e64aa | 230 | in `templates/hooks--pre-commit`. To help ensure this does not happen, |
231 | run `git diff --check` on your changes before you commit. | |
31408251 | 232 | |
049e64aa | 233 | [[describe-changes]] |
234 | === Describe your changes well. | |
7d5bf87b | 235 | |
cdba0295 JH |
236 | The log message that explains your changes is just as important as the |
237 | changes themselves. Your code may be clearly written with in-code | |
238 | comment to sufficiently explain how it works with the surrounding | |
239 | code, but those who need to fix or enhance your code in the future | |
240 | will need to know _why_ your code does what it does, for a few | |
241 | reasons: | |
242 | ||
243 | . Your code may be doing something differently from what you wanted it | |
244 | to do. Writing down what you actually wanted to achieve will help | |
245 | them fix your code and make it do what it should have been doing | |
246 | (also, you often discover your own bugs yourself, while writing the | |
247 | log message to summarize the thought behind it). | |
248 | ||
249 | . Your code may be doing things that were only necessary for your | |
250 | immediate needs (e.g. "do X to directories" without implementing or | |
251 | even designing what is to be done on files). Writing down why you | |
252 | excluded what the code does not do will help guide future developers. | |
253 | Writing down "we do X to directories, because directories have | |
254 | characteristic Y" would help them infer "oh, files also have the same | |
255 | characteristic Y, so perhaps doing X to them would also make sense?". | |
256 | Saying "we don't do the same X to files, because ..." will help them | |
257 | decide if the reasoning is sound (in which case they do not waste | |
258 | time extending your code to cover files), or reason differently (in | |
259 | which case, they can explain why they extend your code to cover | |
260 | files, too). | |
261 | ||
120adc7d JH |
262 | The goal of your log message is to convey the _why_ behind your change |
263 | to help future developers. The reviewers will also make sure that | |
264 | your proposed log message will serve this purpose well. | |
cdba0295 | 265 | |
7d5bf87b | 266 | The first line of the commit message should be a short description (50 |
049e64aa | 267 | characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), |
268 | and should skip the full stop. It is also conventional in most cases to | |
7d5bf87b JH |
269 | prefix the first line with "area: " where the area is a filename or |
270 | identifier for the general area of the code being modified, e.g. | |
271 | ||
049e64aa | 272 | * doc: clarify distinction between sign-off and pgp-signing |
273 | * githooks.txt: improve the intro section | |
7d5bf87b | 274 | |
049e64aa | 275 | If in doubt which identifier to use, run `git log --no-merges` on the |
7d5bf87b JH |
276 | files you are modifying to see the current conventions. |
277 | ||
049e64aa | 278 | [[summary-section]] |
151b6c2d | 279 | The title sentence after the "area:" prefix omits the full stop at the |
3991bb73 JH |
280 | end, and its first word is not capitalized (the omission |
281 | of capitalization applies only to the word after the "area:" | |
282 | prefix of the title) unless there is a reason to | |
151b6c2d JH |
283 | capitalize it other than because it is the first word in the sentence. |
284 | E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt: | |
285 | improve...", not "githooks.txt: Improve...". But "refs: HEAD is also | |
286 | treated as a ref" is correct, as we spell `HEAD` in all caps even when | |
287 | it appears in the middle of a sentence. | |
2ee00567 | 288 | |
049e64aa | 289 | [[meaningful-message]] |
7d5bf87b JH |
290 | The body should provide a meaningful commit message, which: |
291 | ||
049e64aa | 292 | . explains the problem the change tries to solve, i.e. what is wrong |
293 | with the current code without the change. | |
7d5bf87b | 294 | |
049e64aa | 295 | . justifies the way the change solves the problem, i.e. why the |
296 | result with the change is better. | |
7d5bf87b | 297 | |
049e64aa | 298 | . alternate solutions considered but discarded, if any. |
7d5bf87b | 299 | |
fa1101af JH |
300 | [[present-tense]] |
301 | The problem statement that describes the status quo is written in the | |
302 | present tense. Write "The code does X when it is given input Y", | |
303 | instead of "The code used to do Y when given input X". You do not | |
304 | have to say "Currently"---the status quo in the problem statement is | |
305 | about the code _without_ your change, by project convention. | |
306 | ||
049e64aa | 307 | [[imperative-mood]] |
7d5bf87b JH |
308 | Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
309 | instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy | |
310 | to do frotz", as if you are giving orders to the codebase to change | |
01e60a9a | 311 | its behavior. Try to make sure your explanation can be understood |
7d5bf87b JH |
312 | without external resources. Instead of giving a URL to a mailing list |
313 | archive, summarize the relevant points of the discussion. | |
314 | ||
049e64aa | 315 | [[commit-reference]] |
fdfae830 JH |
316 | |
317 | There are a few reasons why you may want to refer to another commit in | |
318 | the "more stable" part of the history (i.e. on branches like `maint`, | |
319 | `master`, and `next`): | |
320 | ||
321 | . A commit that introduced the root cause of a bug you are fixing. | |
322 | ||
323 | . A commit that introduced a feature that you are enhancing. | |
324 | ||
325 | . A commit that conflicts with your work when you made a trial merge | |
326 | of your work into `next` and `seen` for testing. | |
327 | ||
328 | When you reference a commit on a more stable branch (like `master`, | |
329 | `maint` and `next`), use the format "abbreviated hash (subject, | |
330 | date)", like this: | |
4369523b | 331 | |
049e64aa | 332 | .... |
fb2ffa77 | 333 | Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) |
049e64aa | 334 | noticed that ... |
335 | .... | |
4369523b | 336 | |
d15b8539 | 337 | The "Copy commit reference" command of gitk can be used to obtain this |
fb2ffa77 DL |
338 | format (with the subject enclosed in a pair of double-quotes), or this |
339 | invocation of `git show`: | |
175d38ca | 340 | |
049e64aa | 341 | .... |
3798149a DL |
342 | git show -s --pretty=reference <commit> |
343 | .... | |
344 | ||
345 | or, on an older version of Git without support for --pretty=reference: | |
346 | ||
049e64aa | 347 | .... |
fb2ffa77 | 348 | git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> |
049e64aa | 349 | .... |
7d5bf87b | 350 | |
4523dc86 ÆAB |
351 | [[sign-off]] |
352 | === Certify your work by adding your `Signed-off-by` trailer | |
353 | ||
354 | To improve tracking of who did what, we ask you to certify that you | |
355 | wrote the patch or have the right to pass it on under the same license | |
356 | as ours, by "signing off" your patch. Without sign-off, we cannot | |
357 | accept your patches. | |
358 | ||
359 | If (and only if) you certify the below D-C-O: | |
360 | ||
361 | [[dco]] | |
362 | .Developer's Certificate of Origin 1.1 | |
363 | ____ | |
364 | By making a contribution to this project, I certify that: | |
365 | ||
366 | a. The contribution was created in whole or in part by me and I | |
367 | have the right to submit it under the open source license | |
368 | indicated in the file; or | |
369 | ||
370 | b. The contribution is based upon previous work that, to the best | |
371 | of my knowledge, is covered under an appropriate open source | |
372 | license and I have the right under that license to submit that | |
373 | work with modifications, whether created in whole or in part | |
374 | by me, under the same open source license (unless I am | |
375 | permitted to submit under a different license), as indicated | |
376 | in the file; or | |
377 | ||
378 | c. The contribution was provided directly to me by some other | |
379 | person who certified (a), (b) or (c) and I have not modified | |
380 | it. | |
381 | ||
382 | d. I understand and agree that this project and the contribution | |
383 | are public and that a record of the contribution (including all | |
384 | personal information I submit with it, including my sign-off) is | |
385 | maintained indefinitely and may be redistributed consistent with | |
386 | this project or the open source license(s) involved. | |
387 | ____ | |
388 | ||
389 | you add a "Signed-off-by" trailer to your commit, that looks like | |
390 | this: | |
391 | ||
392 | .... | |
393 | Signed-off-by: Random J Developer <random@developer.example.org> | |
394 | .... | |
395 | ||
396 | This line can be added by Git if you run the git-commit command with | |
397 | the -s option. | |
398 | ||
399 | Notice that you can place your own `Signed-off-by` trailer when | |
400 | forwarding somebody else's patch with the above rules for | |
401 | D-C-O. Indeed you are encouraged to do so. Do not forget to | |
402 | place an in-body "From: " line at the beginning to properly attribute | |
403 | the change to its true author (see (2) above). | |
404 | ||
405 | This procedure originally came from the Linux kernel project, so our | |
406 | rule is quite similar to theirs, but what exactly it means to sign-off | |
407 | your patch differs from project to project, so it may be different | |
408 | from that of the project you are accustomed to. | |
409 | ||
410 | [[real-name]] | |
411 | Also notice that a real name is used in the `Signed-off-by` trailer. Please | |
412 | don't hide your real name. | |
413 | ||
414 | [[commit-trailers]] | |
415 | If you like, you can put extra tags at the end: | |
416 | ||
417 | . `Reported-by:` is used to credit someone who found the bug that | |
418 | the patch attempts to fix. | |
419 | . `Acked-by:` says that the person who is more familiar with the area | |
420 | the patch attempts to modify liked the patch. | |
421 | . `Reviewed-by:`, unlike the other tags, can only be offered by the | |
422 | reviewers themselves when they are completely satisfied with the | |
423 | patch after a detailed analysis. | |
424 | . `Tested-by:` is used to indicate that the person applied the patch | |
425 | and found it to have the desired effect. | |
c771ef6f JS |
426 | . `Co-authored-by:` is used to indicate that people exchanged drafts |
427 | of a patch before submitting it. | |
428 | . `Helped-by:` is used to credit someone who suggested ideas for | |
429 | changes without providing the precise changes in patch form. | |
430 | . `Mentored-by:` is used to credit someone with helping develop a | |
431 | patch as part of a mentorship program (e.g., GSoC or Outreachy). | |
432 | . `Suggested-by:` is used to credit someone with suggesting the idea | |
433 | for a patch. | |
4523dc86 | 434 | |
ac9fff2b JS |
435 | While you can also create your own trailer if the situation warrants it, we |
436 | encourage you to instead use one of the common trailers in this project | |
437 | highlighted above. | |
4523dc86 | 438 | |
08e2e6f8 JS |
439 | Only capitalize the very first letter of tags, i.e. favor |
440 | "Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". | |
441 | ||
049e64aa | 442 | [[git-tools]] |
443 | === Generate your patch using Git tools out of your commits. | |
45d2b286 | 444 | |
2de9b711 | 445 | Git based diff tools generate unidiff which is the preferred format. |
45d2b286 | 446 | |
049e64aa | 447 | You do not have to be afraid to use `-M` option to `git diff` or |
448 | `git format-patch`, if your patch involves file renames. The | |
31408251 JH |
449 | receiving end can handle them just fine. |
450 | ||
049e64aa | 451 | [[review-patch]] |
7d5bf87b JH |
452 | Please make sure your patch does not add commented out debugging code, |
453 | or include any extra files which do not relate to what your patch | |
454 | is trying to achieve. Make sure to review | |
31408251 | 455 | your patch after generating it, to ensure accuracy. Before |
b5dbfe28 | 456 | sending out, please make sure it cleanly applies to the starting point you |
5c98149c LA |
457 | have chosen in the "Choose a starting point" section. |
458 | ||
459 | NOTE: From the perspective of those reviewing your patch, the `master` | |
460 | branch is the default expected starting point. So if you have chosen a | |
461 | different starting point, please communicate this choice in your cover | |
462 | letter. | |
fdfae830 | 463 | |
31408251 | 464 | |
049e64aa | 465 | [[send-patches]] |
466 | === Sending your patches. | |
31408251 | 467 | |
e2663c45 LA |
468 | ==== Choosing your reviewers |
469 | ||
2a00502b TG |
470 | :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] |
471 | ||
01ea2b28 | 472 | NOTE: Patches that may be |
2a00502b TG |
473 | security relevant should be submitted privately to the Git Security |
474 | mailing list{security-ml}, instead of the public mailing list. | |
475 | ||
e2663c45 LA |
476 | :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + |
477 | not part of the core `git` binary and must be called directly. Clone the Git + | |
478 | codebase and run `perl contrib/contacts/git-contacts`.] | |
479 | ||
480 | Send your patch with "To:" set to the mailing list, with "cc:" listing | |
481 | people who are involved in the area you are touching (the `git-contacts` | |
482 | script in `contrib/contacts/`{contrib-scripts} can help to | |
483 | identify them), to solicit comments and reviews. Also, when you made | |
484 | trial merges of your topic to `next` and `seen`, you may have noticed | |
485 | work by others conflicting with your changes. There is a good possibility | |
486 | that these people may know the area you are touching well. | |
487 | ||
61e124bb LA |
488 | If you are using `send-email`, you can feed it the output of `git-contacts` like |
489 | this: | |
490 | ||
491 | .... | |
492 | git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch | |
493 | .... | |
494 | ||
e2663c45 LA |
495 | :current-maintainer: footnote:[The current maintainer: gitster@pobox.com] |
496 | :git-ml: footnote:[The mailing list: git@vger.kernel.org] | |
497 | ||
498 | After the list reached a consensus that it is a good idea to apply the | |
499 | patch, re-send it with "To:" set to the maintainer{current-maintainer} | |
500 | and "cc:" the list{git-ml} for inclusion. This is especially relevant | |
501 | when the maintainer did not heavily participate in the discussion and | |
502 | instead left the review to trusted others. | |
503 | ||
504 | Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and | |
505 | `Tested-by:` lines as necessary to credit people who helped your | |
506 | patch, and "cc:" them when sending such a final version for inclusion. | |
507 | ||
bf966145 LA |
508 | ==== `format-patch` and `send-email` |
509 | ||
c8d6a54a | 510 | Learn to use `format-patch` and `send-email` if possible. These commands |
b25c4699 | 511 | are optimized for the workflow of sending patches, avoiding many ways |
97509a34 ŠN |
512 | your existing e-mail client (often optimized for "multipart/*" MIME |
513 | type e-mails) might render your patches unusable. | |
b25c4699 | 514 | |
84b91fc4 LA |
515 | NOTE: Here we outline the procedure using `format-patch` and |
516 | `send-email`, but you can instead use GitGitGadget to send in your | |
517 | patches (see link:MyFirstContribution.html[MyFirstContribution]). | |
518 | ||
2de9b711 | 519 | People on the Git mailing list need to be able to read and |
31408251 JH |
520 | comment on the changes you are submitting. It is important for |
521 | a developer to be able to "quote" your changes, using standard | |
522 | e-mail tools, so that they may comment on specific portions of | |
eaa6c987 RS |
523 | your code. For this reason, each patch should be submitted |
524 | "inline" in a separate message. | |
525 | ||
4cf6e7bf JT |
526 | All subsequent versions of a patch series and other related patches should be |
527 | grouped into their own e-mail thread to help readers find all parts of the | |
528 | series. To that end, send them as replies to either an additional "cover | |
529 | letter" message (see below), the first patch, or the respective preceding patch. | |
530 | Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on | |
531 | how to submit updated versions of a patch series. | |
eaa6c987 RS |
532 | |
533 | If your log message (including your name on the | |
3abd4a67 | 534 | `Signed-off-by` trailer) is not writable in ASCII, make sure that |
7d5bf87b JH |
535 | you send off a message in the correct encoding. |
536 | ||
537 | WARNING: Be wary of your MUAs word-wrap | |
45d2b286 JH |
538 | corrupting your patch. Do not cut-n-paste your patch; you can |
539 | lose tabs that way if you are not careful. | |
31408251 | 540 | |
45d2b286 | 541 | It is a common convention to prefix your subject line with |
31408251 | 542 | [PATCH]. This lets people easily distinguish patches from other |
f6be7edc AD |
543 | e-mail discussions. Use of markers in addition to PATCH within |
544 | the brackets to describe the nature of the patch is also | |
545 | encouraged. E.g. [RFC PATCH] (where RFC stands for "request for | |
546 | comments") is often used to indicate a patch needs further | |
547 | discussion before being accepted, [PATCH v2], [PATCH v3] etc. | |
548 | are often seen when you are sending an update to what you have | |
549 | previously sent. | |
550 | ||
1a5f2e44 | 551 | The `git format-patch` command follows the best current practice to |
31408251 JH |
552 | format the body of an e-mail message. At the beginning of the |
553 | patch should come your commit message, ending with the | |
3abd4a67 | 554 | `Signed-off-by` trailers, and a line that consists of three dashes, |
31408251 JH |
555 | followed by the diffstat information and the patch itself. If |
556 | you are forwarding a patch from somebody else, optionally, at | |
557 | the beginning of the e-mail message just before the commit | |
558 | message starts, you can put a "From: " line to name that person. | |
f6be7edc AD |
559 | To change the default "[PATCH]" in the subject to "[<text>]", use |
560 | `git format-patch --subject-prefix=<text>`. As a shortcut, you | |
561 | can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or | |
562 | `-v <n>` instead of `--subject-prefix="PATCH v<n>"`. | |
31408251 JH |
563 | |
564 | You often want to add additional explanation about the patch, | |
565 | other than the commit message itself. Place such "cover letter" | |
86010993 ES |
566 | material between the three-dash line and the diffstat. For |
567 | patches requiring multiple iterations of review and discussion, | |
568 | an explanation of changes between each iteration can be kept in | |
569 | Git-notes and inserted automatically following the three-dash | |
570 | line via `git format-patch --notes`. | |
31408251 | 571 | |
d255105c JH |
572 | [[the-topic-summary]] |
573 | *This is EXPERIMENTAL*. | |
574 | ||
575 | When sending a topic, you can propose a one-paragraph summary that | |
576 | should appear in the "What's cooking" report when it is picked up to | |
577 | explain the topic. If you choose to do so, please write a 2-5 line | |
578 | paragraph that will fit well in our release notes (see many bulleted | |
579 | entries in the Documentation/RelNotes/* files for examples), and make | |
580 | it the first paragraph of the cover letter. For a single-patch | |
581 | series, use the space between the three-dash line and the diffstat, as | |
582 | described earlier. | |
583 | ||
049e64aa | 584 | [[attachment]] |
31408251 | 585 | Do not attach the patch as a MIME attachment, compressed or not. |
e30b217b JH |
586 | Do not let your e-mail client send quoted-printable. Do not let |
587 | your e-mail client send format=flowed which would destroy | |
588 | whitespaces in your patches. Many | |
31408251 JH |
589 | popular e-mail applications will not always transmit a MIME |
590 | attachment as plain text, making it impossible to comment on | |
591 | your code. A MIME attachment also takes a bit more time to | |
592 | process. This does not decrease the likelihood of your | |
593 | MIME-attached change being accepted, but it makes it more likely | |
594 | that it will be postponed. | |
595 | ||
596 | Exception: If your mailer is mangling patches then someone may ask | |
9847f7e0 | 597 | you to re-send them using MIME, that is OK. |
31408251 | 598 | |
049e64aa | 599 | [[pgp-signature]] |
eafd5d94 CW |
600 | Do not PGP sign your patch. Most likely, your maintainer or other people on the |
601 | list would not have your PGP key and would not bother obtaining it anyway. | |
602 | Your patch is not judged by who you are; a good patch from an unknown origin | |
603 | has a far better chance of being accepted than a patch from a known, respected | |
604 | origin that is done poorly or does incorrect things. | |
9847f7e0 JH |
605 | |
606 | If you really really really really want to do a PGP signed | |
607 | patch, format it as "multipart/signed", not a text/plain message | |
049e64aa | 608 | that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is |
9847f7e0 JH |
609 | not a text/plain, it's something else. |
610 | ||
c397ddff KN |
611 | === Handling Conflicts and Iterating Patches |
612 | ||
613 | When revising changes made to your patches, it's important to | |
614 | acknowledge the possibility of conflicts with other ongoing topics. To | |
615 | navigate these potential conflicts effectively, follow the recommended | |
616 | steps outlined below: | |
617 | ||
618 | . Build on a suitable base branch, see the <<choose-starting-point, section above>>, | |
619 | and format-patch the series. If you are doing "rebase -i" in-place to | |
620 | update from the previous round, this will reuse the previous base so | |
621 | (2) and (3) may become trivial. | |
622 | ||
623 | . Find the base of where the last round was queued | |
624 | + | |
625 | $ mine='kn/ref-transaction-symref' | |
626 | $ git checkout "origin/seen^{/^Merge branch '$mine'}...master" | |
627 | ||
628 | . Apply your format-patch result. There are two cases | |
629 | .. Things apply cleanly and tests fine. Go to (4). | |
630 | .. Things apply cleanly but does not build or test fails, or things do | |
631 | not apply cleanly. | |
632 | + | |
633 | In the latter case, you have textual or semantic conflicts coming from | |
634 | the difference between the old base and the base you used to build in | |
635 | (1). Identify what caused the breakages (e.g., a topic or two may have | |
636 | merged since the base used by (2) until the base used by (1)). | |
637 | + | |
638 | Check out the latest 'origin/master' (which may be newer than the base | |
639 | used by (2)), "merge --no-ff" the topics you newly depend on in there, | |
640 | and use the result of the merge(s) as the base, rebuild the series and | |
641 | test again. Run format-patch from the last such merges to the tip of | |
642 | your topic. If you did | |
643 | + | |
644 | $ git checkout origin/master | |
645 | $ git merge --no-ff --into-name kn/ref-transaction-symref fo/obar | |
646 | $ git merge --no-ff --into-name kn/ref-transaction-symref ba/zqux | |
647 | ... rebuild the topic ... | |
648 | + | |
649 | Then you'd just format your topic above these "preparing the ground" | |
650 | merges, e.g. | |
651 | + | |
652 | $ git format-patch "HEAD^{/^Merge branch 'ba/zqux'}"..HEAD | |
653 | + | |
654 | Do not forget to write in the cover letter you did this, including the | |
655 | topics you have in your base on top of 'master'. Then go to (4). | |
656 | ||
657 | . Make a trial merge of your topic into 'next' and 'seen', e.g. | |
658 | + | |
659 | $ git checkout --detach 'origin/seen' | |
660 | $ git revert -m 1 <the merge of the previous iteration into seen> | |
661 | $ git merge kn/ref-transaction-symref | |
662 | + | |
663 | The "revert" is needed if the previous iteration of your topic is | |
664 | already in 'seen' (like in this case). You could choose to rebuild | |
665 | master..origin/seen from scratch while excluding your previous | |
666 | iteration, which may emulate what happens on the maintainers end more | |
667 | closely. | |
668 | + | |
669 | This trial merge may conflict. It is primarily to see what conflicts | |
670 | _other_ topics may have with your topic. In other words, you do not | |
671 | have to depend on it to make your topic work on 'master'. It may | |
672 | become the job of the other topic owners to resolve conflicts if your | |
673 | topic goes to 'next' before theirs. | |
674 | + | |
675 | Make a note on what conflict you saw in the cover letter. You do not | |
676 | necessarily have to resolve them, but it would be a good opportunity to | |
677 | learn what others are doing in related areas. | |
678 | + | |
679 | $ git checkout --detach 'origin/next' | |
680 | $ git merge kn/ref-transaction-symref | |
681 | + | |
682 | This is to see what conflicts your topic has with other topics that are | |
683 | already cooking. This should not conflict if (3)-2 prepared a base on | |
684 | top of updated master plus dependent topics taken from 'next'. Unless | |
685 | the context is severe (one way to tell is try the same trial merge with | |
686 | your old iteration, which may conflict in a similar way), expect that it | |
687 | will be handled on maintainers end (if it gets unmanageable, I'll ask to | |
688 | rebase when I receive your patches). | |
689 | ||
049e64aa | 690 | == Subsystems with dedicated maintainers |
e6da8ee8 JH |
691 | |
692 | Some parts of the system have dedicated maintainers with their own | |
693 | repositories. | |
694 | ||
e18ad8eb | 695 | - `git-gui/` comes from git-gui project, maintained by Johannes Sixt: |
e6da8ee8 | 696 | |
e18ad8eb | 697 | https://github.com/j6t/git-gui |
e6da8ee8 | 698 | |
68ed71b5 | 699 | - `gitk-git/` comes from Paul Mackerras's gitk project: |
e6da8ee8 | 700 | |
b014cee8 JH |
701 | git://git.ozlabs.org/~paulus/gitk |
702 | ||
97509a34 ŠN |
703 | Those who are interested in improving gitk can volunteer to help Paul |
704 | maintain it, cf. <YntxL/fTplFm8lr6@cleo>. | |
e6da8ee8 | 705 | |
68ed71b5 | 706 | - `po/` comes from the localization coordinator, Jiang Xin: |
e6da8ee8 JH |
707 | |
708 | https://github.com/git-l10n/git-po/ | |
709 | ||
710 | Patches to these parts should be based on their trees. | |
711 | ||
558a5b8c JH |
712 | - The "Git documentation translations" project, led by Jean-Noël |
713 | Avila, translates our documentation pages. Their work products are | |
714 | maintained separately from this project, not as part of our tree: | |
715 | ||
716 | https://github.com/jnavila/git-manpages-l10n/ | |
717 | ||
718 | ||
edbd9f37 | 719 | == GitHub CI[[GHCI]] |
0e5d028a | 720 | |
f003a91f ÆAB |
721 | With an account at GitHub, you can use GitHub CI to test your changes |
722 | on Linux, Mac and Windows. See | |
723 | https://github.com/git/git/actions/workflows/main.yml for examples of | |
724 | recent CI runs. | |
0e5d028a LS |
725 | |
726 | Follow these steps for the initial setup: | |
727 | ||
049e64aa | 728 | . Fork https://github.com/git/git to your GitHub account. |
729 | You can find detailed instructions how to fork here: | |
730 | https://help.github.com/articles/fork-a-repo/ | |
0e5d028a | 731 | |
f003a91f | 732 | After the initial setup, CI will run whenever you push new changes |
0e5d028a | 733 | to your fork of Git on GitHub. You can monitor the test state of all your |
edbd9f37 | 734 | branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml` |
0e5d028a | 735 | |
0771a3b5 JS |
736 | If a branch does not pass all test cases then it will be marked with a |
737 | red +x+, instead of a green check. In that case, you can click on the | |
738 | failing job and navigate to "ci/run-build-and-tests.sh" and/or | |
739 | "ci/print-test-failures.sh". You can also download "Artifacts" which | |
78189516 JS |
740 | are zip archives containing tarred (or zipped) archives with test data |
741 | relevant for debugging. | |
f003a91f ÆAB |
742 | |
743 | Then fix the problem and push your fix to your GitHub fork. This will | |
744 | trigger a new CI build to ensure all tests pass. | |
0e5d028a | 745 | |
049e64aa | 746 | [[mua]] |
747 | == MUA specific hints | |
9740d289 | 748 | |
d0ea2ca1 | 749 | Some of the patches I receive or pick up from the list share common |
9740d289 | 750 | patterns of breakage. Please make sure your MUA is set up |
57756161 JN |
751 | properly not to corrupt whitespaces. |
752 | ||
049e64aa | 753 | See the DISCUSSION section of linkgit:git-format-patch[1] for hints on |
57756161 | 754 | checking your patch by mailing it to yourself and applying with |
049e64aa | 755 | linkgit:git-am[1]. |
57756161 JN |
756 | |
757 | While you are at it, check the resulting commit log message from | |
758 | a trial run of applying the patch. If what is in the resulting | |
759 | commit is not exactly what you would want to see, it is very | |
760 | likely that your maintainer would end up hand editing the log | |
761 | message when he applies your patch. Things like "Hi, this is my | |
762 | first patch.\n", if you really want to put in the patch e-mail, | |
763 | should come after the three-dash line that signals the end of the | |
764 | commit message. | |
9847f7e0 | 765 | |
9740d289 | 766 | |
049e64aa | 767 | === Pine |
9740d289 JH |
768 | |
769 | (Johannes Schindelin) | |
770 | ||
049e64aa | 771 | .... |
9740d289 JH |
772 | I don't know how many people still use pine, but for those poor |
773 | souls it may be good to mention that the quell-flowed-text is | |
774 | needed for recent versions. | |
775 | ||
776 | ... the "no-strip-whitespace-before-send" option, too. AFAIK it | |
777 | was introduced in 4.60. | |
049e64aa | 778 | .... |
9740d289 JH |
779 | |
780 | (Linus Torvalds) | |
781 | ||
049e64aa | 782 | .... |
9740d289 JH |
783 | And 4.58 needs at least this. |
784 | ||
9740d289 JH |
785 | diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) |
786 | Author: Linus Torvalds <torvalds@g5.osdl.org> | |
787 | Date: Mon Aug 15 17:23:51 2005 -0700 | |
788 | ||
789 | Fix pine whitespace-corruption bug | |
790 | ||
791 | There's no excuse for unconditionally removing whitespace from | |
792 | the pico buffers on close. | |
793 | ||
794 | diff --git a/pico/pico.c b/pico/pico.c | |
795 | --- a/pico/pico.c | |
796 | +++ b/pico/pico.c | |
797 | @@ -219,7 +219,9 @@ PICO *pm; | |
a6080a0a JH |
798 | switch(pico_all_done){ /* prepare for/handle final events */ |
799 | case COMP_EXIT : /* already confirmed */ | |
800 | packheader(); | |
9740d289 | 801 | +#if 0 |
a6080a0a | 802 | stripwhitespace(); |
9740d289 | 803 | +#endif |
a6080a0a JH |
804 | c |= COMP_EXIT; |
805 | break; | |
049e64aa | 806 | .... |
9740d289 | 807 | |
1eb446fa JH |
808 | (Daniel Barkalow) |
809 | ||
049e64aa | 810 | .... |
1eb446fa JH |
811 | > A patch to SubmittingPatches, MUA specific help section for |
812 | > users of Pine 4.63 would be very much appreciated. | |
813 | ||
814 | Ah, it looks like a recent version changed the default behavior to do the | |
815 | right thing, and inverted the sense of the configuration option. (Either | |
816 | that or Gentoo did it.) So you need to set the | |
817 | "no-strip-whitespace-before-send" option, unless the option you have is | |
818 | "strip-whitespace-before-send", in which case you should avoid checking | |
819 | it. | |
049e64aa | 820 | .... |
1eb446fa | 821 | |
049e64aa | 822 | === Thunderbird, KMail, GMail |
9740d289 | 823 | |
049e64aa | 824 | See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1]. |
e30b217b | 825 | |
049e64aa | 826 | === Gnus |
e30b217b | 827 | |
049e64aa | 828 | "|" in the `*Summary*` buffer can be used to pipe the current |
e30b217b | 829 | message to an external program, and this is a handy way to drive |
049e64aa | 830 | `git am`. However, if the message is MIME encoded, what is |
e30b217b | 831 | piped into the program is the representation you see in your |
049e64aa | 832 | `*Article*` buffer after unwrapping MIME. This is often not what |
291873e5 | 833 | you would want for two reasons. It tends to screw up non-ASCII |
e30b217b | 834 | characters (most notably in people's names), and also |
049e64aa | 835 | whitespaces (fatal in patches). Running "C-u g" to display the |
836 | message in raw form before using "|" to run the pipe can work | |
e30b217b | 837 | this problem around. |