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