blob: 5bd795e5dbf90daff92fcf33a10f7c318e9d0689 [file] [log] [blame]
brian m. carlson049e64a2017-11-12 22:07:18 +00001Submitting Patches
2==================
3
4== Guidelines
5
Emily Shafferb75a2192020-06-08 14:11:32 -07006Here are some guidelines for people who want to contribute their code to this
7software. There is also a link:MyFirstContribution.html[step-by-step tutorial]
8available which covers many of these same guidelines.
Junio C Hamano31408252005-08-12 23:48:09 -07009
brian m. carlson049e64a2017-11-12 22:07:18 +000010[[base-branch]]
11=== Decide what to base your work on.
Ramkumar Ramachandrad0c26f02010-04-19 01:24:20 +053012
13In general, always base your work on the oldest branch that your
14change is relevant to.
15
brian m. carlson049e64a2017-11-12 22:07:18 +000016* 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.
Ramkumar Ramachandrad0c26f02010-04-19 01:24:20 +053020
brian m. carlson049e64a2017-11-12 22:07:18 +000021* A new feature should be based on `master` in general. If the new
Junio C Hamanofdfae832021-12-30 12:18:35 -080022 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..`.
Ramkumar Ramachandrad0c26f02010-04-19 01:24:20 +053026
brian m. carlson049e64a2017-11-12 22:07:18 +000027* 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.
Ramkumar Ramachandrad0c26f02010-04-19 01:24:20 +053031
brian m. carlson049e64a2017-11-12 22:07:18 +000032* In the exceptional case that a new feature depends on several topics
Junio C Hamanofdfae832021-12-30 12:18:35 -080033 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).
Ramkumar Ramachandrad0c26f02010-04-19 01:24:20 +053037
brian m. carlson049e64a2017-11-12 22:07:18 +000038* 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.
Junio C Hamanoe6da8ee2013-01-01 14:37:56 -080041
brian m. carlson049e64a2017-11-12 22:07:18 +000042To find the tip of a topic branch, run `git log --first-parent
Johannes Schindelin828197d2020-06-25 12:18:57 +000043master..seen` and look for the merge commit. The second parent of this
Ramkumar Ramachandrad0c26f02010-04-19 01:24:20 +053044commit is the tip of the topic branch.
Junio C Hamano31408252005-08-12 23:48:09 -070045
brian m. carlson049e64a2017-11-12 22:07:18 +000046[[separate-commits]]
47=== Make separate commits for logically separate changes.
Junio C Hamano31408252005-08-12 23:48:09 -070048
49Unless your patch is really trivial, you should not be sending
50out a patch that was generated between your working tree and
51your commit head. Instead, always make a commit with complete
52commit message and generate a series of patches from your
53repository. It is a good discipline.
54
Junio C Hamanod0f7dcb2011-03-08 16:58:19 -080055Give an explanation for the change(s) that is detailed enough so
56that people can judge if it is good thing to do, without reading
57the actual patch text to determine how well the code does what
58the explanation promises to do.
Junio C Hamano31408252005-08-12 23:48:09 -070059
Junio C Hamano45d2b282006-02-17 16:15:26 -080060If your description starts to get too long, that's a sign that you
Junio C Hamano31408252005-08-12 23:48:09 -070061probably need to split up your commit to finer grained pieces.
Sam Vilain47afed52009-04-28 02:38:47 +120062That being said, patches which plainly describe the things that
63help reviewers check the patch, and future maintainers understand
René Genz01e60a92017-04-30 17:42:21 +020064the code, are the most beautiful patches. Descriptions that summarize
Sam Vilain47afed52009-04-28 02:38:47 +120065the point in the subject well, and describe the motivation for the
66change, the approach taken by the change, and if relevant how this
Junio C Hamanod0f7dcb2011-03-08 16:58:19 -080067differs substantially from the prior version, are all good things
68to have.
Junio C Hamano31408252005-08-12 23:48:09 -070069
Junio C Hamano54cc5d22014-11-24 09:43:29 -080070Make sure that you have tests for the bug you are fixing. See
brian m. carlson049e64a2017-11-12 22:07:18 +000071`t/README` for guidance.
Junio C Hamano7d5bf872013-01-01 15:19:00 -080072
brian m. carlson049e64a2017-11-12 22:07:18 +000073[[tests]]
Junio C Hamano7d5bf872013-01-01 15:19:00 -080074When adding a new feature, make sure that you have new tests to show
Lars Schneider0e5d0282016-05-02 10:12:12 +020075the feature triggers the new behavior when it should, and to show the
Junio C Hamanofdfae832021-12-30 12:18:35 -080076feature does not trigger when it shouldn't. After any code change,
77make sure that the entire test suite passes. When fixing a bug, make
78sure you have new tests that break if somebody else breaks what you
79fixed 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
81that are still in flight may have unexpected interactions with what
82you are trying to do in your topic.
Junio C Hamano7d5bf872013-01-01 15:19:00 -080083
Ævar Arnfjörð Bjarmasonf003a912021-07-22 14:11:24 +020084Pushing to a fork of https://github.com/git/git will use their CI
85integration to test your changes on Linux, Mac and Windows. See the
86<<GHCI,GitHub CI>> section for details.
Lars Schneider0e5d0282016-05-02 10:12:12 +020087
88Do not forget to update the documentation to describe the updated
89behavior and make sure that the resulting documentation set formats
Jeff King7a76f5c2018-08-21 15:23:22 -040090well (try the Documentation/doc-diff script).
91
92We currently have a liberal mixture of US and UK English norms for
Lars Schneider0e5d0282016-05-02 10:12:12 +020093spelling and grammar, which is somewhat unfortunate. A huge patch that
94touches the files all over the place only to correct the inconsistency
95is not welcome, though. Potential clashes with other changes that can
96result from such a patch are not worth it. We prefer to gradually
97reconcile the inconsistencies in favor of US English, with small and
98easily digestible patches, as a side effect of doing some other real
99work in the vicinity (e.g. rewriting a paragraph for clarity, while
100turning en_UK spelling to en_US). Obvious typographical fixes are much
101more welcomed ("teh -> "the"), preferably submitted as independent
102patches separate from other documentation changes.
Marc Branchaud42e0fae2013-08-01 14:49:54 -0400103
brian m. carlson049e64a2017-11-12 22:07:18 +0000104[[whitespace-check]]
Marc Branchaud42e0fae2013-08-01 14:49:54 -0400105Oh, another thing. We are picky about whitespaces. Make sure your
Junio C Hamano45d2b282006-02-17 16:15:26 -0800106changes do not trigger errors with the sample pre-commit hook shipped
brian m. carlson049e64a2017-11-12 22:07:18 +0000107in `templates/hooks--pre-commit`. To help ensure this does not happen,
108run `git diff --check` on your changes before you commit.
Junio C Hamano31408252005-08-12 23:48:09 -0700109
brian m. carlson049e64a2017-11-12 22:07:18 +0000110[[describe-changes]]
111=== Describe your changes well.
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800112
Junio C Hamanocdba0292022-01-27 11:02:59 -0800113The log message that explains your changes is just as important as the
114changes themselves. Your code may be clearly written with in-code
115comment to sufficiently explain how it works with the surrounding
116code, but those who need to fix or enhance your code in the future
117will need to know _why_ your code does what it does, for a few
118reasons:
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
139The goal of your log message is to convey the _why_ behind your
140change to help future developers.
141
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800142The first line of the commit message should be a short description (50
brian m. carlson049e64a2017-11-12 22:07:18 +0000143characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),
144and should skip the full stop. It is also conventional in most cases to
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800145prefix the first line with "area: " where the area is a filename or
146identifier for the general area of the code being modified, e.g.
147
brian m. carlson049e64a2017-11-12 22:07:18 +0000148* doc: clarify distinction between sign-off and pgp-signing
149* githooks.txt: improve the intro section
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800150
brian m. carlson049e64a2017-11-12 22:07:18 +0000151If in doubt which identifier to use, run `git log --no-merges` on the
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800152files you are modifying to see the current conventions.
153
brian m. carlson049e64a2017-11-12 22:07:18 +0000154[[summary-section]]
Junio C Hamano151b6c22021-04-14 16:51:17 -0700155The title sentence after the "area:" prefix omits the full stop at the
156end, and its first word is not capitalized unless there is a reason to
157capitalize it other than because it is the first word in the sentence.
158E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt:
159improve...", not "githooks.txt: Improve...". But "refs: HEAD is also
160treated as a ref" is correct, as we spell `HEAD` in all caps even when
161it appears in the middle of a sentence.
Ævar Arnfjörð Bjarmason2ee00562017-03-21 14:21:53 +0000162
brian m. carlson049e64a2017-11-12 22:07:18 +0000163[[meaningful-message]]
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800164The body should provide a meaningful commit message, which:
165
brian m. carlson049e64a2017-11-12 22:07:18 +0000166. explains the problem the change tries to solve, i.e. what is wrong
167 with the current code without the change.
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800168
brian m. carlson049e64a2017-11-12 22:07:18 +0000169. justifies the way the change solves the problem, i.e. why the
170 result with the change is better.
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800171
brian m. carlson049e64a2017-11-12 22:07:18 +0000172. alternate solutions considered but discarded, if any.
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800173
Junio C Hamanofa1101a2022-01-27 11:02:57 -0800174[[present-tense]]
175The problem statement that describes the status quo is written in the
176present tense. Write "The code does X when it is given input Y",
177instead of "The code used to do Y when given input X". You do not
178have to say "Currently"---the status quo in the problem statement is
179about the code _without_ your change, by project convention.
180
brian m. carlson049e64a2017-11-12 22:07:18 +0000181[[imperative-mood]]
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800182Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
183instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
184to do frotz", as if you are giving orders to the codebase to change
René Genz01e60a92017-04-30 17:42:21 +0200185its behavior. Try to make sure your explanation can be understood
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800186without external resources. Instead of giving a URL to a mailing list
187archive, summarize the relevant points of the discussion.
188
brian m. carlson049e64a2017-11-12 22:07:18 +0000189[[commit-reference]]
Junio C Hamanofdfae832021-12-30 12:18:35 -0800190
191There are a few reasons why you may want to refer to another commit in
192the "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
202When you reference a commit on a more stable branch (like `master`,
203`maint` and `next`), use the format "abbreviated hash (subject,
204date)", like this:
Beat Bolli43695232016-08-26 18:59:01 +0200205
brian m. carlson049e64a2017-11-12 22:07:18 +0000206....
Denton Liufb2ffa72019-11-19 16:51:08 -0800207 Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
brian m. carlson049e64a2017-11-12 22:07:18 +0000208 noticed that ...
209....
Beat Bolli43695232016-08-26 18:59:01 +0200210
211The "Copy commit summary" command of gitk can be used to obtain this
Denton Liufb2ffa72019-11-19 16:51:08 -0800212format (with the subject enclosed in a pair of double-quotes), or this
213invocation of `git show`:
Heiko Voigt175d38c2016-07-28 14:55:14 +0200214
brian m. carlson049e64a2017-11-12 22:07:18 +0000215....
Denton Liu37981492019-11-19 16:51:28 -0800216 git show -s --pretty=reference <commit>
217....
218
219or, on an older version of Git without support for --pretty=reference:
220
221....
Denton Liufb2ffa72019-11-19 16:51:08 -0800222 git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
brian m. carlson049e64a2017-11-12 22:07:18 +0000223....
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800224
Ævar Arnfjörð Bjarmason4523dc82021-07-22 14:11:23 +0200225[[sign-off]]
226=== Certify your work by adding your `Signed-off-by` trailer
227
228To improve tracking of who did what, we ask you to certify that you
229wrote the patch or have the right to pass it on under the same license
230as ours, by "signing off" your patch. Without sign-off, we cannot
231accept your patches.
232
233If (and only if) you certify the below D-C-O:
234
235[[dco]]
236.Developer's Certificate of Origin 1.1
237____
238By making a contribution to this project, I certify that:
239
240a. 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
244b. 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
252c. 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
256d. 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
263you add a "Signed-off-by" trailer to your commit, that looks like
264this:
265
266....
267 Signed-off-by: Random J Developer <random@developer.example.org>
268....
269
270This line can be added by Git if you run the git-commit command with
271the -s option.
272
273Notice that you can place your own `Signed-off-by` trailer when
274forwarding somebody else's patch with the above rules for
275D-C-O. Indeed you are encouraged to do so. Do not forget to
276place an in-body "From: " line at the beginning to properly attribute
277the change to its true author (see (2) above).
278
279This procedure originally came from the Linux kernel project, so our
280rule is quite similar to theirs, but what exactly it means to sign-off
281your patch differs from project to project, so it may be different
282from that of the project you are accustomed to.
283
284[[real-name]]
285Also notice that a real name is used in the `Signed-off-by` trailer. Please
286don't hide your real name.
287
288[[commit-trailers]]
289If 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
301You can also create your own tag or use one that's in common usage
302such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
303
brian m. carlson049e64a2017-11-12 22:07:18 +0000304[[git-tools]]
305=== Generate your patch using Git tools out of your commits.
Junio C Hamano45d2b282006-02-17 16:15:26 -0800306
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100307Git based diff tools generate unidiff which is the preferred format.
Junio C Hamano45d2b282006-02-17 16:15:26 -0800308
brian m. carlson049e64a2017-11-12 22:07:18 +0000309You 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
Junio C Hamano31408252005-08-12 23:48:09 -0700311receiving end can handle them just fine.
312
brian m. carlson049e64a2017-11-12 22:07:18 +0000313[[review-patch]]
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800314Please make sure your patch does not add commented out debugging code,
315or include any extra files which do not relate to what your patch
316is trying to achieve. Make sure to review
Junio C Hamano31408252005-08-12 23:48:09 -0700317your patch after generating it, to ensure accuracy. Before
Junio C Hamanofdfae832021-12-30 12:18:35 -0800318sending out, please make sure it cleanly applies to the base you
319have chosen in the "Decide what to base your work on" section,
320and unless it targets the `master` branch (which is the default),
321mark your patches as such.
322
Junio C Hamano31408252005-08-12 23:48:09 -0700323
brian m. carlson049e64a2017-11-12 22:07:18 +0000324[[send-patches]]
325=== Sending your patches.
Junio C Hamano31408252005-08-12 23:48:09 -0700326
Thomas Gummerer2a005022018-05-30 21:52:55 +0100327:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
328
329Before sending any patches, please note that patches that may be
330security relevant should be submitted privately to the Git Security
331mailing list{security-ml}, instead of the public mailing list.
332
Junio C Hamanob25c4692015-03-13 00:02:15 -0700333Learn to use format-patch and send-email if possible. These commands
334are optimized for the workflow of sending patches, avoiding many ways
335your existing e-mail client that is optimized for "multipart/*" mime
336type e-mails to corrupt and render your patches unusable.
337
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100338People on the Git mailing list need to be able to read and
Junio C Hamano31408252005-08-12 23:48:09 -0700339comment on the changes you are submitting. It is important for
340a developer to be able to "quote" your changes, using standard
341e-mail tools, so that they may comment on specific portions of
René Scharfeeaa6c982013-11-27 01:28:39 +0100342your code. For this reason, each patch should be submitted
343"inline" in a separate message.
344
345Multiple related patches should be grouped into their own e-mail
346thread to help readers find all parts of the series. To that end,
347send them as replies to either an additional "cover letter" message
348(see below), the first patch, or the respective preceding patch.
349
350If your log message (including your name on the
Bradley M. Kuhn3abd4a62020-10-19 18:03:55 -0700351`Signed-off-by` trailer) is not writable in ASCII, make sure that
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800352you send off a message in the correct encoding.
353
354WARNING: Be wary of your MUAs word-wrap
Junio C Hamano45d2b282006-02-17 16:15:26 -0800355corrupting your patch. Do not cut-n-paste your patch; you can
356lose tabs that way if you are not careful.
Junio C Hamano31408252005-08-12 23:48:09 -0700357
Junio C Hamano45d2b282006-02-17 16:15:26 -0800358It is a common convention to prefix your subject line with
Junio C Hamano31408252005-08-12 23:48:09 -0700359[PATCH]. This lets people easily distinguish patches from other
Adam Dinwoodief6be7ed2017-11-10 15:02:50 +0000360e-mail discussions. Use of markers in addition to PATCH within
361the brackets to describe the nature of the patch is also
362encouraged. E.g. [RFC PATCH] (where RFC stands for "request for
363comments") is often used to indicate a patch needs further
364discussion before being accepted, [PATCH v2], [PATCH v3] etc.
365are often seen when you are sending an update to what you have
366previously sent.
Junio C Hamano31408252005-08-12 23:48:09 -0700367
Junio C Hamano1a5f2e42017-11-21 14:07:51 +0900368The `git format-patch` command follows the best current practice to
Junio C Hamano31408252005-08-12 23:48:09 -0700369format the body of an e-mail message. At the beginning of the
370patch should come your commit message, ending with the
Bradley M. Kuhn3abd4a62020-10-19 18:03:55 -0700371`Signed-off-by` trailers, and a line that consists of three dashes,
Junio C Hamano31408252005-08-12 23:48:09 -0700372followed by the diffstat information and the patch itself. If
373you are forwarding a patch from somebody else, optionally, at
374the beginning of the e-mail message just before the commit
375message starts, you can put a "From: " line to name that person.
Adam Dinwoodief6be7ed2017-11-10 15:02:50 +0000376To change the default "[PATCH]" in the subject to "[<text>]", use
377`git format-patch --subject-prefix=<text>`. As a shortcut, you
378can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or
379`-v <n>` instead of `--subject-prefix="PATCH v<n>"`.
Junio C Hamano31408252005-08-12 23:48:09 -0700380
381You often want to add additional explanation about the patch,
382other than the commit message itself. Place such "cover letter"
Eric Sunshine86010992014-12-30 18:30:30 -0500383material between the three-dash line and the diffstat. For
384patches requiring multiple iterations of review and discussion,
385an explanation of changes between each iteration can be kept in
386Git-notes and inserted automatically following the three-dash
387line via `git format-patch --notes`.
Junio C Hamano31408252005-08-12 23:48:09 -0700388
brian m. carlson049e64a2017-11-12 22:07:18 +0000389[[attachment]]
Junio C Hamano31408252005-08-12 23:48:09 -0700390Do not attach the patch as a MIME attachment, compressed or not.
Junio C Hamanoe30b2172007-01-17 01:07:27 -0800391Do not let your e-mail client send quoted-printable. Do not let
392your e-mail client send format=flowed which would destroy
393whitespaces in your patches. Many
Junio C Hamano31408252005-08-12 23:48:09 -0700394popular e-mail applications will not always transmit a MIME
395attachment as plain text, making it impossible to comment on
396your code. A MIME attachment also takes a bit more time to
397process. This does not decrease the likelihood of your
398MIME-attached change being accepted, but it makes it more likely
399that it will be postponed.
400
401Exception: If your mailer is mangling patches then someone may ask
Junio C Hamano9847f7e2005-08-28 17:54:18 -0700402you to re-send them using MIME, that is OK.
Junio C Hamano31408252005-08-12 23:48:09 -0700403
brian m. carlson049e64a2017-11-12 22:07:18 +0000404[[pgp-signature]]
Cornelius Weigeafd5d92017-01-27 21:01:36 +0100405Do not PGP sign your patch. Most likely, your maintainer or other people on the
406list would not have your PGP key and would not bother obtaining it anyway.
407Your patch is not judged by who you are; a good patch from an unknown origin
408has a far better chance of being accepted than a patch from a known, respected
409origin that is done poorly or does incorrect things.
Junio C Hamano9847f7e2005-08-28 17:54:18 -0700410
411If you really really really really want to do a PGP signed
412patch, format it as "multipart/signed", not a text/plain message
brian m. carlson049e64a2017-11-12 22:07:18 +0000413that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is
Junio C Hamano9847f7e2005-08-28 17:54:18 -0700414not a text/plain, it's something else.
415
Thomas Gummerer2a005022018-05-30 21:52:55 +0100416:security-ml-ref: footnoteref:[security-ml]
417
418As mentioned at the beginning of the section, patches that may be
419security relevant should not be submitted to the public mailing list
420mentioned below, but should instead be sent privately to the Git
421Security mailing list{security-ml-ref}.
422
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800423Send your patch with "To:" set to the mailing list, with "cc:" listing
Thomas Gummerer92a5dbb2018-04-11 21:20:00 +0100424people who are involved in the area you are touching (the `git
425contacts` command in `contrib/contacts/` can help to
Junio C Hamanofdfae832021-12-30 12:18:35 -0800426identify them), to solicit comments and reviews. Also, when you made
427trial merges of your topic to `next` and `seen`, you may have noticed
428work by others conflicting with your changes. There is a good possibility
429that these people may know the area you are touching well.
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800430
Thomas Gummerera27cd1a2018-05-30 21:52:54 +0100431:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
432:git-ml: footnote:[The mailing list: git@vger.kernel.org]
Junio C Hamano7d5bf872013-01-01 15:19:00 -0800433
brian m. carlson049e64a2017-11-12 22:07:18 +0000434After the list reached a consensus that it is a good idea to apply the
Junio C Hamanod95b1922020-10-09 11:56:52 -0700435patch, re-send it with "To:" set to the maintainer{current-maintainer}
436and "cc:" the list{git-ml} for inclusion. This is especially relevant
437when the maintainer did not heavily participate in the discussion and
438instead left the review to trusted others.
brian m. carlson049e64a2017-11-12 22:07:18 +0000439
440Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
441`Tested-by:` lines as necessary to credit people who helped your
Junio C Hamanod95b1922020-10-09 11:56:52 -0700442patch, and "cc:" them when sending such a final version for inclusion.
Junio C Hamano04d24452006-10-24 01:29:27 -0700443
brian m. carlson049e64a2017-11-12 22:07:18 +0000444== Subsystems with dedicated maintainers
Junio C Hamanoe6da8ee2013-01-01 14:37:56 -0800445
446Some parts of the system have dedicated maintainers with their own
447repositories.
448
Junio C Hamano253bfe42019-09-18 13:57:13 -0700449- `git-gui/` comes from git-gui project, maintained by Pratyush Yadav:
Junio C Hamanoe6da8ee2013-01-01 14:37:56 -0800450
Junio C Hamano253bfe42019-09-18 13:57:13 -0700451 https://github.com/prati0100/git-gui.git
Junio C Hamanoe6da8ee2013-01-01 14:37:56 -0800452
Corentin BOMPARD68ed71b2019-03-06 14:04:46 +0100453- `gitk-git/` comes from Paul Mackerras's gitk project:
Junio C Hamanoe6da8ee2013-01-01 14:37:56 -0800454
Junio C Hamanob014cee2022-05-11 08:10:12 -0700455 git://git.ozlabs.org/~paulus/gitk
456
457 Those who are interested in improve gitk can volunteer to help Paul
458 in maintaining it cf. <YntxL/fTplFm8lr6@cleo>.
Junio C Hamanoe6da8ee2013-01-01 14:37:56 -0800459
Corentin BOMPARD68ed71b2019-03-06 14:04:46 +0100460- `po/` comes from the localization coordinator, Jiang Xin:
Junio C Hamanoe6da8ee2013-01-01 14:37:56 -0800461
462 https://github.com/git-l10n/git-po/
463
464Patches to these parts should be based on their trees.
465
brian m. carlson049e64a2017-11-12 22:07:18 +0000466[[patch-flow]]
467== An ideal patch flow
Junio C Hamanoa941fb42008-02-10 14:09:52 -0800468
469Here is an ideal patch flow for this project the current maintainer
470suggests to the contributors:
471
brian m. carlson049e64a2017-11-12 22:07:18 +0000472. You come up with an itch. You code it up.
Junio C Hamanoa941fb42008-02-10 14:09:52 -0800473
brian m. carlson049e64a2017-11-12 22:07:18 +0000474. Send it to the list and cc people who may need to know about
475 the change.
476+
477The people who may need to know are the ones whose code you
478are butchering. These people happen to be the ones who are
479most likely to be knowledgeable enough to help you, but
480they have no obligation to help you (i.e. you ask for help,
481don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
482help you find out who they are.
Junio C Hamanoa941fb42008-02-10 14:09:52 -0800483
brian m. carlson049e64a2017-11-12 22:07:18 +0000484. You get comments and suggestions for improvements. You may
Ville Skyttä928f0ab2018-06-22 09:50:37 +0300485 even get them in an "on top of your change" patch form.
Junio C Hamanoa941fb42008-02-10 14:09:52 -0800486
brian m. carlson049e64a2017-11-12 22:07:18 +0000487. Polish, refine, and re-send to the list and the people who
488 spend their time to improve your patch. Go back to step (2).
Junio C Hamanoa941fb42008-02-10 14:09:52 -0800489
brian m. carlson049e64a2017-11-12 22:07:18 +0000490. The list forms consensus that the last round of your patch is
491 good. Send it to the maintainer and cc the list.
Junio C Hamanoa941fb42008-02-10 14:09:52 -0800492
brian m. carlson049e64a2017-11-12 22:07:18 +0000493. A topic branch is created with the patch and is merged to `next`,
494 and cooked further and eventually graduates to `master`.
Junio C Hamanoa941fb42008-02-10 14:09:52 -0800495
496In any time between the (2)-(3) cycle, the maintainer may pick it up
Johannes Schindelin828197d2020-06-25 12:18:57 +0000497from the list and queue it to `seen`, in order to make it easier for
Junio C Hamanoa941fb42008-02-10 14:09:52 -0800498people play with it without having to pick up and apply the patch to
499their trees themselves.
500
brian m. carlson049e64a2017-11-12 22:07:18 +0000501[[patch-status]]
502== Know the status of your patch after submission
Matthieu Moy63cb8212009-12-30 15:51:22 +0100503
504* You can use Git itself to find out when your patch is merged in
brian m. carlson049e64a2017-11-12 22:07:18 +0000505 master. `git pull --rebase` will automatically skip already-applied
Matthieu Moy63cb8212009-12-30 15:51:22 +0100506 patches, and will let you know. This works only if you rebase on top
507 of the branch in which your patch has been merged (i.e. it will not
Johannes Schindelin828197d2020-06-25 12:18:57 +0000508 tell you if your patch is merged in `seen` if you rebase on top of
Matthieu Moy63cb8212009-12-30 15:51:22 +0100509 master).
510
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100511* Read the Git mailing list, the maintainer regularly posts messages
Matthieu Moy63cb8212009-12-30 15:51:22 +0100512 entitled "What's cooking in git.git" and "What's in git.git" giving
513 the status of various proposed changes.
514
Philippe Blainedbd9f32021-11-13 20:38:05 +0000515== GitHub CI[[GHCI]]
Lars Schneider0e5d0282016-05-02 10:12:12 +0200516
Ævar Arnfjörð Bjarmasonf003a912021-07-22 14:11:24 +0200517With an account at GitHub, you can use GitHub CI to test your changes
518on Linux, Mac and Windows. See
519https://github.com/git/git/actions/workflows/main.yml for examples of
520recent CI runs.
Lars Schneider0e5d0282016-05-02 10:12:12 +0200521
522Follow these steps for the initial setup:
523
brian m. carlson049e64a2017-11-12 22:07:18 +0000524. Fork https://github.com/git/git to your GitHub account.
525 You can find detailed instructions how to fork here:
526 https://help.github.com/articles/fork-a-repo/
Lars Schneider0e5d0282016-05-02 10:12:12 +0200527
Ævar Arnfjörð Bjarmasonf003a912021-07-22 14:11:24 +0200528After the initial setup, CI will run whenever you push new changes
Lars Schneider0e5d0282016-05-02 10:12:12 +0200529to your fork of Git on GitHub. You can monitor the test state of all your
Philippe Blainedbd9f32021-11-13 20:38:05 +0000530branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
Lars Schneider0e5d0282016-05-02 10:12:12 +0200531
532If a branch did not pass all test cases then it is marked with a red
Ævar Arnfjörð Bjarmasonf003a912021-07-22 14:11:24 +0200533cross. In that case you can click on the failing job and navigate to
534"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
535can also download "Artifacts" which are tarred (or zipped) archives
536with test data relevant for debugging.
Lars Schneider0e5d0282016-05-02 10:12:12 +0200537
Ævar Arnfjörð Bjarmasonf003a912021-07-22 14:11:24 +0200538Then fix the problem and push your fix to your GitHub fork. This will
539trigger a new CI build to ensure all tests pass.
Lars Schneider0e5d0282016-05-02 10:12:12 +0200540
brian m. carlson049e64a2017-11-12 22:07:18 +0000541[[mua]]
542== MUA specific hints
Junio C Hamano9740d282005-08-26 23:53:07 -0700543
544Some of patches I receive or pick up from the list share common
545patterns of breakage. Please make sure your MUA is set up
Jonathan Nieder57756162011-04-14 21:24:01 -0500546properly not to corrupt whitespaces.
Junio C Hamano9740d282005-08-26 23:53:07 -0700547
brian m. carlson049e64a2017-11-12 22:07:18 +0000548See the DISCUSSION section of linkgit:git-format-patch[1] for hints on
Jonathan Nieder57756162011-04-14 21:24:01 -0500549checking your patch by mailing it to yourself and applying with
brian m. carlson049e64a2017-11-12 22:07:18 +0000550linkgit:git-am[1].
Junio C Hamano9740d282005-08-26 23:53:07 -0700551
Jonathan Nieder57756162011-04-14 21:24:01 -0500552While you are at it, check the resulting commit log message from
553a trial run of applying the patch. If what is in the resulting
554commit is not exactly what you would want to see, it is very
555likely that your maintainer would end up hand editing the log
556message when he applies your patch. Things like "Hi, this is my
557first patch.\n", if you really want to put in the patch e-mail,
558should come after the three-dash line that signals the end of the
559commit message.
Junio C Hamano9847f7e2005-08-28 17:54:18 -0700560
Junio C Hamano9740d282005-08-26 23:53:07 -0700561
brian m. carlson049e64a2017-11-12 22:07:18 +0000562=== Pine
Junio C Hamano9740d282005-08-26 23:53:07 -0700563
564(Johannes Schindelin)
565
brian m. carlson049e64a2017-11-12 22:07:18 +0000566....
Junio C Hamano9740d282005-08-26 23:53:07 -0700567I don't know how many people still use pine, but for those poor
568souls it may be good to mention that the quell-flowed-text is
569needed for recent versions.
570
571... the "no-strip-whitespace-before-send" option, too. AFAIK it
572was introduced in 4.60.
brian m. carlson049e64a2017-11-12 22:07:18 +0000573....
Junio C Hamano9740d282005-08-26 23:53:07 -0700574
575(Linus Torvalds)
576
brian m. carlson049e64a2017-11-12 22:07:18 +0000577....
Junio C Hamano9740d282005-08-26 23:53:07 -0700578And 4.58 needs at least this.
579
Junio C Hamano9740d282005-08-26 23:53:07 -0700580diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
581Author: Linus Torvalds <torvalds@g5.osdl.org>
582Date: Mon Aug 15 17:23:51 2005 -0700
583
584 Fix pine whitespace-corruption bug
585
586 There's no excuse for unconditionally removing whitespace from
587 the pico buffers on close.
588
589diff --git a/pico/pico.c b/pico/pico.c
590--- a/pico/pico.c
591+++ b/pico/pico.c
592@@ -219,7 +219,9 @@ PICO *pm;
Junio C Hamanoa6080a02007-06-07 00:04:01 -0700593 switch(pico_all_done){ /* prepare for/handle final events */
594 case COMP_EXIT : /* already confirmed */
595 packheader();
Junio C Hamano9740d282005-08-26 23:53:07 -0700596+#if 0
Junio C Hamanoa6080a02007-06-07 00:04:01 -0700597 stripwhitespace();
Junio C Hamano9740d282005-08-26 23:53:07 -0700598+#endif
Junio C Hamanoa6080a02007-06-07 00:04:01 -0700599 c |= COMP_EXIT;
600 break;
brian m. carlson049e64a2017-11-12 22:07:18 +0000601....
Junio C Hamano9740d282005-08-26 23:53:07 -0700602
Junio C Hamano1eb446f2005-08-31 11:48:41 -0700603(Daniel Barkalow)
604
brian m. carlson049e64a2017-11-12 22:07:18 +0000605....
Junio C Hamano1eb446f2005-08-31 11:48:41 -0700606> A patch to SubmittingPatches, MUA specific help section for
607> users of Pine 4.63 would be very much appreciated.
608
609Ah, it looks like a recent version changed the default behavior to do the
610right thing, and inverted the sense of the configuration option. (Either
611that or Gentoo did it.) So you need to set the
612"no-strip-whitespace-before-send" option, unless the option you have is
613"strip-whitespace-before-send", in which case you should avoid checking
614it.
brian m. carlson049e64a2017-11-12 22:07:18 +0000615....
Junio C Hamano1eb446f2005-08-31 11:48:41 -0700616
brian m. carlson049e64a2017-11-12 22:07:18 +0000617=== Thunderbird, KMail, GMail
Junio C Hamano9740d282005-08-26 23:53:07 -0700618
brian m. carlson049e64a2017-11-12 22:07:18 +0000619See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1].
Junio C Hamano9740d282005-08-26 23:53:07 -0700620
brian m. carlson049e64a2017-11-12 22:07:18 +0000621=== Gnus
Junio C Hamanoe30b2172007-01-17 01:07:27 -0800622
brian m. carlson049e64a2017-11-12 22:07:18 +0000623"|" in the `*Summary*` buffer can be used to pipe the current
Junio C Hamanoe30b2172007-01-17 01:07:27 -0800624message to an external program, and this is a handy way to drive
brian m. carlson049e64a2017-11-12 22:07:18 +0000625`git am`. However, if the message is MIME encoded, what is
Junio C Hamanoe30b2172007-01-17 01:07:27 -0800626piped into the program is the representation you see in your
brian m. carlson049e64a2017-11-12 22:07:18 +0000627`*Article*` buffer after unwrapping MIME. This is often not what
Junio C Hamanoe30b2172007-01-17 01:07:27 -0800628you would want for two reasons. It tends to screw up non ASCII
629characters (most notably in people's names), and also
brian m. carlson049e64a2017-11-12 22:07:18 +0000630whitespaces (fatal in patches). Running "C-u g" to display the
631message in raw form before using "|" to run the pipe can work
Junio C Hamanoe30b2172007-01-17 01:07:27 -0800632this problem around.