git

1
Submitting Patches
2
==================
3

4
== Guidelines
5

6
Here are some guidelines for contributing back to this
7
project. There is also a link:MyFirstContribution.html[step-by-step tutorial]
8
available which covers many of these same guidelines.
9

10
[[patch-flow]]
11
=== A typical life cycle of a patch series
12

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.
16

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.
33
+
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
36
most likely to be knowledgeable enough to help you, but
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
39
help you find out who they are.
40

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.
75

76

77
[[choose-starting-point]]
78
=== Choose a starting point.
79

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
116
  `master` but were not available in the released version).
117

118
* Otherwise (such as if you are adding new features) use `master`.
119

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

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
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.
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
157
`master` and merging the required topic branches into it. You could then
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.
164

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

169
[[separate-commits]]
170
=== Make separate commits for logically separate changes.
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

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.
182

183
If your description starts to get too long, that's a sign that you
184
probably need to split up your commit to finer grained pieces.
185
That being said, patches which plainly describe the things that
186
help reviewers check the patch, and future maintainers understand
187
the code, are the most beautiful patches.  Descriptions that summarize
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
190
differs substantially from the prior version, are all good things
191
to have.
192

193
Make sure that you have tests for the bug you are fixing.  See
194
`t/README` for guidance.
195

196
[[tests]]
197
When adding a new feature, make sure that you have new tests to show
198
the feature triggers the new behavior when it should, and to show the
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.
206

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.
210

211
Do not forget to update the documentation to describe the updated
212
behavior and make sure that the resulting documentation set formats
213
well (try the Documentation/doc-diff script).
214

215
We currently have a liberal mixture of US and UK English norms for
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.
226

227
[[whitespace-check]]
228
Oh, another thing.  We are picky about whitespaces.  Make sure your
229
changes do not trigger errors with the sample pre-commit hook shipped
230
in `templates/hooks--pre-commit`.  To help ensure this does not happen,
231
run `git diff --check` on your changes before you commit.
232

233
[[describe-changes]]
234
=== Describe your changes well.
235

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

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.
265

266
The first line of the commit message should be a short description (50
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
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

272
* doc: clarify distinction between sign-off and pgp-signing
273
* githooks.txt: improve the intro section
274

275
If in doubt which identifier to use, run `git log --no-merges` on the
276
files you are modifying to see the current conventions.
277

278
[[summary-section]]
279
The title sentence after the "area:" prefix omits the full stop at the
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
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.
288

289
[[meaningful-message]]
290
The body should provide a meaningful commit message, which:
291

292
. explains the problem the change tries to solve, i.e. what is wrong
293
  with the current code without the change.
294

295
. justifies the way the change solves the problem, i.e. why the
296
  result with the change is better.
297

298
. alternate solutions considered but discarded, if any.
299

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

307
[[imperative-mood]]
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
311
its behavior.  Try to make sure your explanation can be understood
312
without external resources. Instead of giving a URL to a mailing list
313
archive, summarize the relevant points of the discussion.
314

315
[[commit-reference]]
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:
331

332
....
333
	Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
334
	noticed that ...
335
....
336

337
The "Copy commit reference" command of gitk can be used to obtain this
338
format (with the subject enclosed in a pair of double-quotes), or this
339
invocation of `git show`:
340

341
....
342
	git show -s --pretty=reference <commit>
343
....
344

345
or, on an older version of Git without support for --pretty=reference:
346

347
....
348
	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
349
....
350

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.
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.
434

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.
438

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

442
[[git-tools]]
443
=== Generate your patch using Git tools out of your commits.
444

445
Git based diff tools generate unidiff which is the preferred format.
446

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
449
receiving end can handle them just fine.
450

451
[[review-patch]]
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
455
your patch after generating it, to ensure accuracy.  Before
456
sending out, please make sure it cleanly applies to the starting point you
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.
463

464

465
[[send-patches]]
466
=== Sending your patches.
467

468
==== Choosing your reviewers
469

470
:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
471

472
NOTE: Patches that may be
473
security relevant should be submitted privately to the Git Security
474
mailing list{security-ml}, instead of the public mailing list.
475

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

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

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

508
==== `format-patch` and `send-email`
509

510
Learn to use `format-patch` and `send-email` if possible.  These commands
511
are optimized for the workflow of sending patches, avoiding many ways
512
your existing e-mail client (often optimized for "multipart/*" MIME
513
type e-mails) might render your patches unusable.
514

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

519
People on the Git mailing list need to be able to read and
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
523
your code.  For this reason, each patch should be submitted
524
"inline" in a separate message.
525

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.
532

533
If your log message (including your name on the
534
`Signed-off-by` trailer) is not writable in ASCII, make sure that
535
you send off a message in the correct encoding.
536

537
WARNING: Be wary of your MUAs word-wrap
538
corrupting your patch.  Do not cut-n-paste your patch; you can
539
lose tabs that way if you are not careful.
540

541
It is a common convention to prefix your subject line with
542
[PATCH].  This lets people easily distinguish patches from other
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

551
The `git format-patch` command follows the best current practice to
552
format the body of an e-mail message.  At the beginning of the
553
patch should come your commit message, ending with the
554
`Signed-off-by` trailers, and a line that consists of three dashes,
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.
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>"`.
563

564
You often want to add additional explanation about the patch,
565
other than the commit message itself.  Place such "cover letter"
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`.
571

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

584
[[attachment]]
585
Do not attach the patch as a MIME attachment, compressed or not.
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
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
597
you to re-send them using MIME, that is OK.
598

599
[[pgp-signature]]
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.
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
608
that starts with `-----BEGIN PGP SIGNED MESSAGE-----`.  That is
609
not a text/plain, it's something else.
610

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

690
== Subsystems with dedicated maintainers
691

692
Some parts of the system have dedicated maintainers with their own
693
repositories.
694

695
- `git-gui/` comes from git-gui project, maintained by Johannes Sixt:
696

697
        https://github.com/j6t/git-gui
698

699
- `gitk-git/` comes from Paul Mackerras's gitk project:
700

701
	git://git.ozlabs.org/~paulus/gitk
702

703
   Those who are interested in improving gitk can volunteer to help Paul
704
   maintain it, cf. <YntxL/fTplFm8lr6@cleo>.
705

706
- `po/` comes from the localization coordinator, Jiang Xin:
707

708
	https://github.com/git-l10n/git-po/
709

710
Patches to these parts should be based on their trees.
711

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

719
== GitHub CI[[GHCI]]
720

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.
725

726
Follow these steps for the initial setup:
727

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/
731

732
After the initial setup, CI will run whenever you push new changes
733
to your fork of Git on GitHub.  You can monitor the test state of all your
734
branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
735

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
740
are zip archives containing tarred (or zipped) archives with test data
741
relevant for debugging.
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.
745

746
[[mua]]
747
== MUA specific hints
748

749
Some of the patches I receive or pick up from the list share common
750
patterns of breakage.  Please make sure your MUA is set up
751
properly not to corrupt whitespaces.
752

753
See the DISCUSSION section of linkgit:git-format-patch[1] for hints on
754
checking your patch by mailing it to yourself and applying with
755
linkgit:git-am[1].
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.
765

766

767
=== Pine
768

769
(Johannes Schindelin)
770

771
....
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.
778
....
779

780
(Linus Torvalds)
781

782
....
783
And 4.58 needs at least this.
784

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;
798
	    switch(pico_all_done){	/* prepare for/handle final events */
799
	      case COMP_EXIT :		/* already confirmed */
800
		packheader();
801
+#if 0
802
		stripwhitespace();
803
+#endif
804
		c |= COMP_EXIT;
805
		break;
806
....
807

808
(Daniel Barkalow)
809

810
....
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.
820
....
821

822
=== Thunderbird, KMail, GMail
823

824
See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1].
825

826
=== Gnus
827

828
"|" in the `*Summary*` buffer can be used to pipe the current
829
message to an external program, and this is a handy way to drive
830
`git am`.  However, if the message is MIME encoded, what is
831
piped into the program is the representation you see in your
832
`*Article*` buffer after unwrapping MIME.  This is often not what
833
you would want for two reasons.  It tends to screw up non-ASCII
834
characters (most notably in people's names), and also
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
837
this problem around.
838