]>
Commit | Line | Data |
---|---|---|
049e64aa | 1 | Submitting Patches |
2 | ================== | |
3 | ||
4 | == Guidelines | |
5 | ||
b75a2199 ES |
6 | Here are some guidelines for people who want to contribute their code to this |
7 | software. There is also a link:MyFirstContribution.html[step-by-step tutorial] | |
8 | available which covers many of these same guidelines. | |
31408251 | 9 | |
049e64aa | 10 | [[base-branch]] |
11 | === Decide what to base your work on. | |
d0c26f0f RR |
12 | |
13 | In general, always base your work on the oldest branch that your | |
14 | change is relevant to. | |
15 | ||
049e64aa | 16 | * A bugfix should be based on `maint` in general. If the bug is not |
17 | present in `maint`, base it on `master`. For a bug that's not yet | |
18 | in `master`, find the topic that introduces the regression, and | |
19 | base your work on the tip of the topic. | |
d0c26f0f | 20 | |
049e64aa | 21 | * A new feature should be based on `master` in general. If the new |
fdfae830 JH |
22 | feature depends on other topics that are in `next`, but not in |
23 | `master`, fork a branch from the tip of `master`, merge these topics | |
24 | to the branch, and work on that branch. You can remind yourself of | |
25 | how you prepared the base with `git log --first-parent master..`. | |
d0c26f0f | 26 | |
049e64aa | 27 | * Corrections and enhancements to a topic not yet in `master` should |
28 | be based on the tip of that topic. If the topic has not been merged | |
29 | to `next`, it's alright to add a note to squash minor corrections | |
30 | into the series. | |
d0c26f0f | 31 | |
049e64aa | 32 | * In the exceptional case that a new feature depends on several topics |
fdfae830 JH |
33 | not in `master`, start working on `next` or `seen` privately and |
34 | send out patches only for discussion. Once your new feature starts | |
35 | to stabilize, you would have to rebase it (see the "depends on other | |
36 | topics" above). | |
d0c26f0f | 37 | |
049e64aa | 38 | * Some parts of the system have dedicated maintainers with their own |
39 | repositories (see the section "Subsystems" below). Changes to | |
40 | these parts should be based on their trees. | |
e6da8ee8 | 41 | |
049e64aa | 42 | To find the tip of a topic branch, run `git log --first-parent |
828197de | 43 | master..seen` and look for the merge commit. The second parent of this |
d0c26f0f | 44 | commit is the tip of the topic branch. |
31408251 | 45 | |
049e64aa | 46 | [[separate-commits]] |
47 | === Make separate commits for logically separate changes. | |
31408251 JH |
48 | |
49 | Unless your patch is really trivial, you should not be sending | |
50 | out a patch that was generated between your working tree and | |
51 | your commit head. Instead, always make a commit with complete | |
52 | commit message and generate a series of patches from your | |
53 | repository. It is a good discipline. | |
54 | ||
d0f7dcbf JH |
55 | Give an explanation for the change(s) that is detailed enough so |
56 | that people can judge if it is good thing to do, without reading | |
57 | the actual patch text to determine how well the code does what | |
58 | the explanation promises to do. | |
31408251 | 59 | |
45d2b286 | 60 | If your description starts to get too long, that's a sign that you |
31408251 | 61 | probably need to split up your commit to finer grained pieces. |
47afed5d SV |
62 | That being said, patches which plainly describe the things that |
63 | help reviewers check the patch, and future maintainers understand | |
01e60a9a | 64 | the code, are the most beautiful patches. Descriptions that summarize |
47afed5d SV |
65 | the point in the subject well, and describe the motivation for the |
66 | change, the approach taken by the change, and if relevant how this | |
d0f7dcbf JH |
67 | differs substantially from the prior version, are all good things |
68 | to have. | |
31408251 | 69 | |
54cc5d29 | 70 | Make sure that you have tests for the bug you are fixing. See |
049e64aa | 71 | `t/README` for guidance. |
7d5bf87b | 72 | |
049e64aa | 73 | [[tests]] |
7d5bf87b | 74 | When adding a new feature, make sure that you have new tests to show |
0e5d028a | 75 | the feature triggers the new behavior when it should, and to show the |
fdfae830 JH |
76 | feature does not trigger when it shouldn't. After any code change, |
77 | make sure that the entire test suite passes. When fixing a bug, make | |
78 | sure you have new tests that break if somebody else breaks what you | |
79 | fixed by accident to avoid regression. Also, try merging your work to | |
80 | 'next' and 'seen' and make sure the tests still pass; topics by others | |
81 | that are still in flight may have unexpected interactions with what | |
82 | you are trying to do in your topic. | |
0e5d028a | 83 | |
f003a91f ÆAB |
84 | Pushing to a fork of https://github.com/git/git will use their CI |
85 | integration to test your changes on Linux, Mac and Windows. See the | |
86 | <<GHCI,GitHub CI>> section for details. | |
0e5d028a LS |
87 | |
88 | Do not forget to update the documentation to describe the updated | |
89 | behavior and make sure that the resulting documentation set formats | |
7a76f5c6 JK |
90 | well (try the Documentation/doc-diff script). |
91 | ||
92 | We currently have a liberal mixture of US and UK English norms for | |
0e5d028a LS |
93 | spelling and grammar, which is somewhat unfortunate. A huge patch that |
94 | touches the files all over the place only to correct the inconsistency | |
95 | is not welcome, though. Potential clashes with other changes that can | |
96 | result from such a patch are not worth it. We prefer to gradually | |
97 | reconcile the inconsistencies in favor of US English, with small and | |
98 | easily digestible patches, as a side effect of doing some other real | |
99 | work in the vicinity (e.g. rewriting a paragraph for clarity, while | |
100 | turning en_UK spelling to en_US). Obvious typographical fixes are much | |
101 | more welcomed ("teh -> "the"), preferably submitted as independent | |
102 | patches separate from other documentation changes. | |
42e0fae9 | 103 | |
049e64aa | 104 | [[whitespace-check]] |
42e0fae9 | 105 | Oh, another thing. We are picky about whitespaces. Make sure your |
45d2b286 | 106 | changes do not trigger errors with the sample pre-commit hook shipped |
049e64aa | 107 | in `templates/hooks--pre-commit`. To help ensure this does not happen, |
108 | run `git diff --check` on your changes before you commit. | |
31408251 | 109 | |
049e64aa | 110 | [[describe-changes]] |
111 | === Describe your changes well. | |
7d5bf87b | 112 | |
cdba0295 JH |
113 | The log message that explains your changes is just as important as the |
114 | changes themselves. Your code may be clearly written with in-code | |
115 | comment to sufficiently explain how it works with the surrounding | |
116 | code, but those who need to fix or enhance your code in the future | |
117 | will need to know _why_ your code does what it does, for a few | |
118 | reasons: | |
119 | ||
120 | . Your code may be doing something differently from what you wanted it | |
121 | to do. Writing down what you actually wanted to achieve will help | |
122 | them fix your code and make it do what it should have been doing | |
123 | (also, you often discover your own bugs yourself, while writing the | |
124 | log message to summarize the thought behind it). | |
125 | ||
126 | . Your code may be doing things that were only necessary for your | |
127 | immediate needs (e.g. "do X to directories" without implementing or | |
128 | even designing what is to be done on files). Writing down why you | |
129 | excluded what the code does not do will help guide future developers. | |
130 | Writing down "we do X to directories, because directories have | |
131 | characteristic Y" would help them infer "oh, files also have the same | |
132 | characteristic Y, so perhaps doing X to them would also make sense?". | |
133 | Saying "we don't do the same X to files, because ..." will help them | |
134 | decide if the reasoning is sound (in which case they do not waste | |
135 | time extending your code to cover files), or reason differently (in | |
136 | which case, they can explain why they extend your code to cover | |
137 | files, too). | |
138 | ||
139 | The goal of your log message is to convey the _why_ behind your | |
140 | change to help future developers. | |
141 | ||
7d5bf87b | 142 | The first line of the commit message should be a short description (50 |
049e64aa | 143 | characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), |
144 | and should skip the full stop. It is also conventional in most cases to | |
7d5bf87b JH |
145 | prefix the first line with "area: " where the area is a filename or |
146 | identifier for the general area of the code being modified, e.g. | |
147 | ||
049e64aa | 148 | * doc: clarify distinction between sign-off and pgp-signing |
149 | * githooks.txt: improve the intro section | |
7d5bf87b | 150 | |
049e64aa | 151 | If in doubt which identifier to use, run `git log --no-merges` on the |
7d5bf87b JH |
152 | files you are modifying to see the current conventions. |
153 | ||
049e64aa | 154 | [[summary-section]] |
151b6c2d JH |
155 | The title sentence after the "area:" prefix omits the full stop at the |
156 | end, and its first word is not capitalized unless there is a reason to | |
157 | capitalize it other than because it is the first word in the sentence. | |
158 | E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt: | |
159 | improve...", not "githooks.txt: Improve...". But "refs: HEAD is also | |
160 | treated as a ref" is correct, as we spell `HEAD` in all caps even when | |
161 | it appears in the middle of a sentence. | |
2ee00567 | 162 | |
049e64aa | 163 | [[meaningful-message]] |
7d5bf87b JH |
164 | The body should provide a meaningful commit message, which: |
165 | ||
049e64aa | 166 | . explains the problem the change tries to solve, i.e. what is wrong |
167 | with the current code without the change. | |
7d5bf87b | 168 | |
049e64aa | 169 | . justifies the way the change solves the problem, i.e. why the |
170 | result with the change is better. | |
7d5bf87b | 171 | |
049e64aa | 172 | . alternate solutions considered but discarded, if any. |
7d5bf87b | 173 | |
fa1101af JH |
174 | [[present-tense]] |
175 | The problem statement that describes the status quo is written in the | |
176 | present tense. Write "The code does X when it is given input Y", | |
177 | instead of "The code used to do Y when given input X". You do not | |
178 | have to say "Currently"---the status quo in the problem statement is | |
179 | about the code _without_ your change, by project convention. | |
180 | ||
049e64aa | 181 | [[imperative-mood]] |
7d5bf87b JH |
182 | Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
183 | instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy | |
184 | to do frotz", as if you are giving orders to the codebase to change | |
01e60a9a | 185 | its behavior. Try to make sure your explanation can be understood |
7d5bf87b JH |
186 | without external resources. Instead of giving a URL to a mailing list |
187 | archive, summarize the relevant points of the discussion. | |
188 | ||
049e64aa | 189 | [[commit-reference]] |
fdfae830 JH |
190 | |
191 | There are a few reasons why you may want to refer to another commit in | |
192 | the "more stable" part of the history (i.e. on branches like `maint`, | |
193 | `master`, and `next`): | |
194 | ||
195 | . A commit that introduced the root cause of a bug you are fixing. | |
196 | ||
197 | . A commit that introduced a feature that you are enhancing. | |
198 | ||
199 | . A commit that conflicts with your work when you made a trial merge | |
200 | of your work into `next` and `seen` for testing. | |
201 | ||
202 | When you reference a commit on a more stable branch (like `master`, | |
203 | `maint` and `next`), use the format "abbreviated hash (subject, | |
204 | date)", like this: | |
4369523b | 205 | |
049e64aa | 206 | .... |
fb2ffa77 | 207 | Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) |
049e64aa | 208 | noticed that ... |
209 | .... | |
4369523b BB |
210 | |
211 | The "Copy commit summary" command of gitk can be used to obtain this | |
fb2ffa77 DL |
212 | format (with the subject enclosed in a pair of double-quotes), or this |
213 | invocation of `git show`: | |
175d38ca | 214 | |
049e64aa | 215 | .... |
3798149a DL |
216 | git show -s --pretty=reference <commit> |
217 | .... | |
218 | ||
219 | or, on an older version of Git without support for --pretty=reference: | |
220 | ||
049e64aa | 221 | .... |
fb2ffa77 | 222 | git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> |
049e64aa | 223 | .... |
7d5bf87b | 224 | |
4523dc86 ÆAB |
225 | [[sign-off]] |
226 | === Certify your work by adding your `Signed-off-by` trailer | |
227 | ||
228 | To improve tracking of who did what, we ask you to certify that you | |
229 | wrote the patch or have the right to pass it on under the same license | |
230 | as ours, by "signing off" your patch. Without sign-off, we cannot | |
231 | accept your patches. | |
232 | ||
233 | If (and only if) you certify the below D-C-O: | |
234 | ||
235 | [[dco]] | |
236 | .Developer's Certificate of Origin 1.1 | |
237 | ____ | |
238 | By making a contribution to this project, I certify that: | |
239 | ||
240 | a. The contribution was created in whole or in part by me and I | |
241 | have the right to submit it under the open source license | |
242 | indicated in the file; or | |
243 | ||
244 | b. The contribution is based upon previous work that, to the best | |
245 | of my knowledge, is covered under an appropriate open source | |
246 | license and I have the right under that license to submit that | |
247 | work with modifications, whether created in whole or in part | |
248 | by me, under the same open source license (unless I am | |
249 | permitted to submit under a different license), as indicated | |
250 | in the file; or | |
251 | ||
252 | c. The contribution was provided directly to me by some other | |
253 | person who certified (a), (b) or (c) and I have not modified | |
254 | it. | |
255 | ||
256 | d. I understand and agree that this project and the contribution | |
257 | are public and that a record of the contribution (including all | |
258 | personal information I submit with it, including my sign-off) is | |
259 | maintained indefinitely and may be redistributed consistent with | |
260 | this project or the open source license(s) involved. | |
261 | ____ | |
262 | ||
263 | you add a "Signed-off-by" trailer to your commit, that looks like | |
264 | this: | |
265 | ||
266 | .... | |
267 | Signed-off-by: Random J Developer <random@developer.example.org> | |
268 | .... | |
269 | ||
270 | This line can be added by Git if you run the git-commit command with | |
271 | the -s option. | |
272 | ||
273 | Notice that you can place your own `Signed-off-by` trailer when | |
274 | forwarding somebody else's patch with the above rules for | |
275 | D-C-O. Indeed you are encouraged to do so. Do not forget to | |
276 | place an in-body "From: " line at the beginning to properly attribute | |
277 | the change to its true author (see (2) above). | |
278 | ||
279 | This procedure originally came from the Linux kernel project, so our | |
280 | rule is quite similar to theirs, but what exactly it means to sign-off | |
281 | your patch differs from project to project, so it may be different | |
282 | from that of the project you are accustomed to. | |
283 | ||
284 | [[real-name]] | |
285 | Also notice that a real name is used in the `Signed-off-by` trailer. Please | |
286 | don't hide your real name. | |
287 | ||
288 | [[commit-trailers]] | |
289 | If you like, you can put extra tags at the end: | |
290 | ||
291 | . `Reported-by:` is used to credit someone who found the bug that | |
292 | the patch attempts to fix. | |
293 | . `Acked-by:` says that the person who is more familiar with the area | |
294 | the patch attempts to modify liked the patch. | |
295 | . `Reviewed-by:`, unlike the other tags, can only be offered by the | |
296 | reviewers themselves when they are completely satisfied with the | |
297 | patch after a detailed analysis. | |
298 | . `Tested-by:` is used to indicate that the person applied the patch | |
299 | and found it to have the desired effect. | |
300 | ||
301 | You can also create your own tag or use one that's in common usage | |
302 | such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". | |
303 | ||
049e64aa | 304 | [[git-tools]] |
305 | === Generate your patch using Git tools out of your commits. | |
45d2b286 | 306 | |
2de9b711 | 307 | Git based diff tools generate unidiff which is the preferred format. |
45d2b286 | 308 | |
049e64aa | 309 | You do not have to be afraid to use `-M` option to `git diff` or |
310 | `git format-patch`, if your patch involves file renames. The | |
31408251 JH |
311 | receiving end can handle them just fine. |
312 | ||
049e64aa | 313 | [[review-patch]] |
7d5bf87b JH |
314 | Please make sure your patch does not add commented out debugging code, |
315 | or include any extra files which do not relate to what your patch | |
316 | is trying to achieve. Make sure to review | |
31408251 | 317 | your patch after generating it, to ensure accuracy. Before |
fdfae830 JH |
318 | sending out, please make sure it cleanly applies to the base you |
319 | have chosen in the "Decide what to base your work on" section, | |
320 | and unless it targets the `master` branch (which is the default), | |
321 | mark your patches as such. | |
322 | ||
31408251 | 323 | |
049e64aa | 324 | [[send-patches]] |
325 | === Sending your patches. | |
31408251 | 326 | |
2a00502b TG |
327 | :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] |
328 | ||
329 | Before sending any patches, please note that patches that may be | |
330 | security relevant should be submitted privately to the Git Security | |
331 | mailing list{security-ml}, instead of the public mailing list. | |
332 | ||
b25c4699 JH |
333 | Learn to use format-patch and send-email if possible. These commands |
334 | are optimized for the workflow of sending patches, avoiding many ways | |
335 | your existing e-mail client that is optimized for "multipart/*" mime | |
336 | type e-mails to corrupt and render your patches unusable. | |
337 | ||
2de9b711 | 338 | People on the Git mailing list need to be able to read and |
31408251 JH |
339 | comment on the changes you are submitting. It is important for |
340 | a developer to be able to "quote" your changes, using standard | |
341 | e-mail tools, so that they may comment on specific portions of | |
eaa6c987 RS |
342 | your code. For this reason, each patch should be submitted |
343 | "inline" in a separate message. | |
344 | ||
345 | Multiple related patches should be grouped into their own e-mail | |
346 | thread to help readers find all parts of the series. To that end, | |
347 | send them as replies to either an additional "cover letter" message | |
348 | (see below), the first patch, or the respective preceding patch. | |
349 | ||
350 | If your log message (including your name on the | |
3abd4a67 | 351 | `Signed-off-by` trailer) is not writable in ASCII, make sure that |
7d5bf87b JH |
352 | you send off a message in the correct encoding. |
353 | ||
354 | WARNING: Be wary of your MUAs word-wrap | |
45d2b286 JH |
355 | corrupting your patch. Do not cut-n-paste your patch; you can |
356 | lose tabs that way if you are not careful. | |
31408251 | 357 | |
45d2b286 | 358 | It is a common convention to prefix your subject line with |
31408251 | 359 | [PATCH]. This lets people easily distinguish patches from other |
f6be7edc AD |
360 | e-mail discussions. Use of markers in addition to PATCH within |
361 | the brackets to describe the nature of the patch is also | |
362 | encouraged. E.g. [RFC PATCH] (where RFC stands for "request for | |
363 | comments") is often used to indicate a patch needs further | |
364 | discussion before being accepted, [PATCH v2], [PATCH v3] etc. | |
365 | are often seen when you are sending an update to what you have | |
366 | previously sent. | |
367 | ||
1a5f2e44 | 368 | The `git format-patch` command follows the best current practice to |
31408251 JH |
369 | format the body of an e-mail message. At the beginning of the |
370 | patch should come your commit message, ending with the | |
3abd4a67 | 371 | `Signed-off-by` trailers, and a line that consists of three dashes, |
31408251 JH |
372 | followed by the diffstat information and the patch itself. If |
373 | you are forwarding a patch from somebody else, optionally, at | |
374 | the beginning of the e-mail message just before the commit | |
375 | message starts, you can put a "From: " line to name that person. | |
f6be7edc AD |
376 | To change the default "[PATCH]" in the subject to "[<text>]", use |
377 | `git format-patch --subject-prefix=<text>`. As a shortcut, you | |
378 | can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or | |
379 | `-v <n>` instead of `--subject-prefix="PATCH v<n>"`. | |
31408251 JH |
380 | |
381 | You often want to add additional explanation about the patch, | |
382 | other than the commit message itself. Place such "cover letter" | |
86010993 ES |
383 | material between the three-dash line and the diffstat. For |
384 | patches requiring multiple iterations of review and discussion, | |
385 | an explanation of changes between each iteration can be kept in | |
386 | Git-notes and inserted automatically following the three-dash | |
387 | line via `git format-patch --notes`. | |
31408251 | 388 | |
049e64aa | 389 | [[attachment]] |
31408251 | 390 | Do not attach the patch as a MIME attachment, compressed or not. |
e30b217b JH |
391 | Do not let your e-mail client send quoted-printable. Do not let |
392 | your e-mail client send format=flowed which would destroy | |
393 | whitespaces in your patches. Many | |
31408251 JH |
394 | popular e-mail applications will not always transmit a MIME |
395 | attachment as plain text, making it impossible to comment on | |
396 | your code. A MIME attachment also takes a bit more time to | |
397 | process. This does not decrease the likelihood of your | |
398 | MIME-attached change being accepted, but it makes it more likely | |
399 | that it will be postponed. | |
400 | ||
401 | Exception: If your mailer is mangling patches then someone may ask | |
9847f7e0 | 402 | you to re-send them using MIME, that is OK. |
31408251 | 403 | |
049e64aa | 404 | [[pgp-signature]] |
eafd5d94 CW |
405 | Do not PGP sign your patch. Most likely, your maintainer or other people on the |
406 | list would not have your PGP key and would not bother obtaining it anyway. | |
407 | Your patch is not judged by who you are; a good patch from an unknown origin | |
408 | has a far better chance of being accepted than a patch from a known, respected | |
409 | origin that is done poorly or does incorrect things. | |
9847f7e0 JH |
410 | |
411 | If you really really really really want to do a PGP signed | |
412 | patch, format it as "multipart/signed", not a text/plain message | |
049e64aa | 413 | that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is |
9847f7e0 JH |
414 | not a text/plain, it's something else. |
415 | ||
2a00502b TG |
416 | :security-ml-ref: footnoteref:[security-ml] |
417 | ||
418 | As mentioned at the beginning of the section, patches that may be | |
419 | security relevant should not be submitted to the public mailing list | |
420 | mentioned below, but should instead be sent privately to the Git | |
421 | Security mailing list{security-ml-ref}. | |
422 | ||
7d5bf87b | 423 | Send your patch with "To:" set to the mailing list, with "cc:" listing |
92a5dbbc TG |
424 | people who are involved in the area you are touching (the `git |
425 | contacts` command in `contrib/contacts/` can help to | |
fdfae830 JH |
426 | identify them), to solicit comments and reviews. Also, when you made |
427 | trial merges of your topic to `next` and `seen`, you may have noticed | |
428 | work by others conflicting with your changes. There is a good possibility | |
429 | that these people may know the area you are touching well. | |
04d24455 | 430 | |
a27cd1ab TG |
431 | :current-maintainer: footnote:[The current maintainer: gitster@pobox.com] |
432 | :git-ml: footnote:[The mailing list: git@vger.kernel.org] | |
049e64aa | 433 | |
7d5bf87b | 434 | After the list reached a consensus that it is a good idea to apply the |
d95b192e JH |
435 | patch, re-send it with "To:" set to the maintainer{current-maintainer} |
436 | and "cc:" the list{git-ml} for inclusion. This is especially relevant | |
437 | when the maintainer did not heavily participate in the discussion and | |
438 | instead left the review to trusted others. | |
31408251 | 439 | |
049e64aa | 440 | Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and |
441 | `Tested-by:` lines as necessary to credit people who helped your | |
d95b192e | 442 | patch, and "cc:" them when sending such a final version for inclusion. |
04d24455 | 443 | |
049e64aa | 444 | == Subsystems with dedicated maintainers |
e6da8ee8 JH |
445 | |
446 | Some parts of the system have dedicated maintainers with their own | |
447 | repositories. | |
448 | ||
253bfe49 | 449 | - `git-gui/` comes from git-gui project, maintained by Pratyush Yadav: |
e6da8ee8 | 450 | |
253bfe49 | 451 | https://github.com/prati0100/git-gui.git |
e6da8ee8 | 452 | |
68ed71b5 | 453 | - `gitk-git/` comes from Paul Mackerras's gitk project: |
e6da8ee8 | 454 | |
049e64aa | 455 | git://ozlabs.org/~paulus/gitk |
e6da8ee8 | 456 | |
68ed71b5 | 457 | - `po/` comes from the localization coordinator, Jiang Xin: |
e6da8ee8 JH |
458 | |
459 | https://github.com/git-l10n/git-po/ | |
460 | ||
461 | Patches to these parts should be based on their trees. | |
462 | ||
049e64aa | 463 | [[patch-flow]] |
464 | == An ideal patch flow | |
a941fb4a JH |
465 | |
466 | Here is an ideal patch flow for this project the current maintainer | |
467 | suggests to the contributors: | |
468 | ||
049e64aa | 469 | . You come up with an itch. You code it up. |
a941fb4a | 470 | |
049e64aa | 471 | . Send it to the list and cc people who may need to know about |
472 | the change. | |
473 | + | |
474 | The people who may need to know are the ones whose code you | |
475 | are butchering. These people happen to be the ones who are | |
476 | most likely to be knowledgeable enough to help you, but | |
477 | they have no obligation to help you (i.e. you ask for help, | |
478 | don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would | |
479 | help you find out who they are. | |
a941fb4a | 480 | |
049e64aa | 481 | . You get comments and suggestions for improvements. You may |
928f0ab4 | 482 | even get them in an "on top of your change" patch form. |
a941fb4a | 483 | |
049e64aa | 484 | . Polish, refine, and re-send to the list and the people who |
485 | spend their time to improve your patch. Go back to step (2). | |
a941fb4a | 486 | |
049e64aa | 487 | . The list forms consensus that the last round of your patch is |
488 | good. Send it to the maintainer and cc the list. | |
a941fb4a | 489 | |
049e64aa | 490 | . A topic branch is created with the patch and is merged to `next`, |
491 | and cooked further and eventually graduates to `master`. | |
a941fb4a JH |
492 | |
493 | In any time between the (2)-(3) cycle, the maintainer may pick it up | |
828197de | 494 | from the list and queue it to `seen`, in order to make it easier for |
a941fb4a JH |
495 | people play with it without having to pick up and apply the patch to |
496 | their trees themselves. | |
497 | ||
049e64aa | 498 | [[patch-status]] |
499 | == Know the status of your patch after submission | |
63cb8215 MM |
500 | |
501 | * You can use Git itself to find out when your patch is merged in | |
049e64aa | 502 | master. `git pull --rebase` will automatically skip already-applied |
63cb8215 MM |
503 | patches, and will let you know. This works only if you rebase on top |
504 | of the branch in which your patch has been merged (i.e. it will not | |
828197de | 505 | tell you if your patch is merged in `seen` if you rebase on top of |
63cb8215 MM |
506 | master). |
507 | ||
2de9b711 | 508 | * Read the Git mailing list, the maintainer regularly posts messages |
63cb8215 MM |
509 | entitled "What's cooking in git.git" and "What's in git.git" giving |
510 | the status of various proposed changes. | |
511 | ||
edbd9f37 | 512 | == GitHub CI[[GHCI]] |
0e5d028a | 513 | |
f003a91f ÆAB |
514 | With an account at GitHub, you can use GitHub CI to test your changes |
515 | on Linux, Mac and Windows. See | |
516 | https://github.com/git/git/actions/workflows/main.yml for examples of | |
517 | recent CI runs. | |
0e5d028a LS |
518 | |
519 | Follow these steps for the initial setup: | |
520 | ||
049e64aa | 521 | . Fork https://github.com/git/git to your GitHub account. |
522 | You can find detailed instructions how to fork here: | |
523 | https://help.github.com/articles/fork-a-repo/ | |
0e5d028a | 524 | |
f003a91f | 525 | After the initial setup, CI will run whenever you push new changes |
0e5d028a | 526 | to your fork of Git on GitHub. You can monitor the test state of all your |
edbd9f37 | 527 | branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml` |
0e5d028a LS |
528 | |
529 | If a branch did not pass all test cases then it is marked with a red | |
f003a91f ÆAB |
530 | cross. In that case you can click on the failing job and navigate to |
531 | "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You | |
532 | can also download "Artifacts" which are tarred (or zipped) archives | |
533 | with test data relevant for debugging. | |
534 | ||
535 | Then fix the problem and push your fix to your GitHub fork. This will | |
536 | trigger a new CI build to ensure all tests pass. | |
0e5d028a | 537 | |
049e64aa | 538 | [[mua]] |
539 | == MUA specific hints | |
9740d289 JH |
540 | |
541 | Some of patches I receive or pick up from the list share common | |
542 | patterns of breakage. Please make sure your MUA is set up | |
57756161 JN |
543 | properly not to corrupt whitespaces. |
544 | ||
049e64aa | 545 | See the DISCUSSION section of linkgit:git-format-patch[1] for hints on |
57756161 | 546 | checking your patch by mailing it to yourself and applying with |
049e64aa | 547 | linkgit:git-am[1]. |
57756161 JN |
548 | |
549 | While you are at it, check the resulting commit log message from | |
550 | a trial run of applying the patch. If what is in the resulting | |
551 | commit is not exactly what you would want to see, it is very | |
552 | likely that your maintainer would end up hand editing the log | |
553 | message when he applies your patch. Things like "Hi, this is my | |
554 | first patch.\n", if you really want to put in the patch e-mail, | |
555 | should come after the three-dash line that signals the end of the | |
556 | commit message. | |
9847f7e0 | 557 | |
9740d289 | 558 | |
049e64aa | 559 | === Pine |
9740d289 JH |
560 | |
561 | (Johannes Schindelin) | |
562 | ||
049e64aa | 563 | .... |
9740d289 JH |
564 | I don't know how many people still use pine, but for those poor |
565 | souls it may be good to mention that the quell-flowed-text is | |
566 | needed for recent versions. | |
567 | ||
568 | ... the "no-strip-whitespace-before-send" option, too. AFAIK it | |
569 | was introduced in 4.60. | |
049e64aa | 570 | .... |
9740d289 JH |
571 | |
572 | (Linus Torvalds) | |
573 | ||
049e64aa | 574 | .... |
9740d289 JH |
575 | And 4.58 needs at least this. |
576 | ||
9740d289 JH |
577 | diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) |
578 | Author: Linus Torvalds <torvalds@g5.osdl.org> | |
579 | Date: Mon Aug 15 17:23:51 2005 -0700 | |
580 | ||
581 | Fix pine whitespace-corruption bug | |
582 | ||
583 | There's no excuse for unconditionally removing whitespace from | |
584 | the pico buffers on close. | |
585 | ||
586 | diff --git a/pico/pico.c b/pico/pico.c | |
587 | --- a/pico/pico.c | |
588 | +++ b/pico/pico.c | |
589 | @@ -219,7 +219,9 @@ PICO *pm; | |
a6080a0a JH |
590 | switch(pico_all_done){ /* prepare for/handle final events */ |
591 | case COMP_EXIT : /* already confirmed */ | |
592 | packheader(); | |
9740d289 | 593 | +#if 0 |
a6080a0a | 594 | stripwhitespace(); |
9740d289 | 595 | +#endif |
a6080a0a JH |
596 | c |= COMP_EXIT; |
597 | break; | |
049e64aa | 598 | .... |
9740d289 | 599 | |
1eb446fa JH |
600 | (Daniel Barkalow) |
601 | ||
049e64aa | 602 | .... |
1eb446fa JH |
603 | > A patch to SubmittingPatches, MUA specific help section for |
604 | > users of Pine 4.63 would be very much appreciated. | |
605 | ||
606 | Ah, it looks like a recent version changed the default behavior to do the | |
607 | right thing, and inverted the sense of the configuration option. (Either | |
608 | that or Gentoo did it.) So you need to set the | |
609 | "no-strip-whitespace-before-send" option, unless the option you have is | |
610 | "strip-whitespace-before-send", in which case you should avoid checking | |
611 | it. | |
049e64aa | 612 | .... |
1eb446fa | 613 | |
049e64aa | 614 | === Thunderbird, KMail, GMail |
9740d289 | 615 | |
049e64aa | 616 | See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1]. |
e30b217b | 617 | |
049e64aa | 618 | === Gnus |
e30b217b | 619 | |
049e64aa | 620 | "|" in the `*Summary*` buffer can be used to pipe the current |
e30b217b | 621 | message to an external program, and this is a handy way to drive |
049e64aa | 622 | `git am`. However, if the message is MIME encoded, what is |
e30b217b | 623 | piped into the program is the representation you see in your |
049e64aa | 624 | `*Article*` buffer after unwrapping MIME. This is often not what |
e30b217b JH |
625 | you would want for two reasons. It tends to screw up non ASCII |
626 | characters (most notably in people's names), and also | |
049e64aa | 627 | whitespaces (fatal in patches). Running "C-u g" to display the |
628 | message in raw form before using "|" to run the pipe can work | |
e30b217b | 629 | this problem around. |