6 Here are some guidelines for people who want to contribute their code to this
7 software. There is also a link:MyFirstContribution.html[step-by-step tutorial]
8 available which covers many of these same guidelines.
11 === Decide what to base your work on.
13 In general, always base your work on the oldest branch that your
14 change is relevant to.
16 * A bugfix should be based on `maint` in general. If the bug is not
17 present in `maint`, base it on `master`. For a bug that's not yet
18 in `master`, find the topic that introduces the regression, and
19 base your work on the tip of the topic.
21 * A new feature should be based on `master` in general. If the new
22 feature depends on a topic that is in `seen`, but not in `master`,
23 base your work on the tip of that topic.
25 * Corrections and enhancements to a topic not yet in `master` should
26 be based on the tip of that topic. If the topic has not been merged
27 to `next`, it's alright to add a note to squash minor corrections
30 * In the exceptional case that a new feature depends on several topics
31 not in `master`, start working on `next` or `seen` privately and send
32 out patches for discussion. Before the final merge, you may have to
33 wait until some of the dependent topics graduate to `master`, and
36 * Some parts of the system have dedicated maintainers with their own
37 repositories (see the section "Subsystems" below). Changes to
38 these parts should be based on their trees.
40 To find the tip of a topic branch, run `git log --first-parent
41 master..seen` and look for the merge commit. The second parent of this
42 commit is the tip of the topic branch.
45 === Make separate commits for logically separate changes.
47 Unless your patch is really trivial, you should not be sending
48 out a patch that was generated between your working tree and
49 your commit head. Instead, always make a commit with complete
50 commit message and generate a series of patches from your
51 repository. It is a good discipline.
53 Give an explanation for the change(s) that is detailed enough so
54 that people can judge if it is good thing to do, without reading
55 the actual patch text to determine how well the code does what
56 the explanation promises to do.
58 If your description starts to get too long, that's a sign that you
59 probably need to split up your commit to finer grained pieces.
60 That being said, patches which plainly describe the things that
61 help reviewers check the patch, and future maintainers understand
62 the code, are the most beautiful patches. Descriptions that summarize
63 the point in the subject well, and describe the motivation for the
64 change, the approach taken by the change, and if relevant how this
65 differs substantially from the prior version, are all good things
68 Make sure that you have tests for the bug you are fixing. See
69 `t/README` for guidance.
72 When adding a new feature, make sure that you have new tests to show
73 the feature triggers the new behavior when it should, and to show the
74 feature does not trigger when it shouldn't. After any code change, make
75 sure that the entire test suite passes.
77 If you have an account at GitHub (and you can get one for free to work
78 on open source projects), you can use their Travis CI integration to
79 test your changes on Linux, Mac (and hopefully soon Windows). See
80 GitHub-Travis CI hints section for details.
82 Do not forget to update the documentation to describe the updated
83 behavior and make sure that the resulting documentation set formats
84 well (try the Documentation/doc-diff script).
86 We currently have a liberal mixture of US and UK English norms for
87 spelling and grammar, which is somewhat unfortunate. A huge patch that
88 touches the files all over the place only to correct the inconsistency
89 is not welcome, though. Potential clashes with other changes that can
90 result from such a patch are not worth it. We prefer to gradually
91 reconcile the inconsistencies in favor of US English, with small and
92 easily digestible patches, as a side effect of doing some other real
93 work in the vicinity (e.g. rewriting a paragraph for clarity, while
94 turning en_UK spelling to en_US). Obvious typographical fixes are much
95 more welcomed ("teh -> "the"), preferably submitted as independent
96 patches separate from other documentation changes.
99 Oh, another thing. We are picky about whitespaces. Make sure your
100 changes do not trigger errors with the sample pre-commit hook shipped
101 in `templates/hooks--pre-commit`. To help ensure this does not happen,
102 run `git diff --check` on your changes before you commit.
105 === Describe your changes well.
107 The first line of the commit message should be a short description (50
108 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),
109 and should skip the full stop. It is also conventional in most cases to
110 prefix the first line with "area: " where the area is a filename or
111 identifier for the general area of the code being modified, e.g.
113 * doc: clarify distinction between sign-off and pgp-signing
114 * githooks.txt: improve the intro section
116 If in doubt which identifier to use, run `git log --no-merges` on the
117 files you are modifying to see the current conventions.
120 The title sentence after the "area:" prefix omits the full stop at the
121 end, and its first word is not capitalized unless there is a reason to
122 capitalize it other than because it is the first word in the sentence.
123 E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt:
124 improve...", not "githooks.txt: Improve...". But "refs: HEAD is also
125 treated as a ref" is correct, as we spell `HEAD` in all caps even when
126 it appears in the middle of a sentence.
128 [[meaningful-message]]
129 The body should provide a meaningful commit message, which:
131 . explains the problem the change tries to solve, i.e. what is wrong
132 with the current code without the change.
134 . justifies the way the change solves the problem, i.e. why the
135 result with the change is better.
137 . alternate solutions considered but discarded, if any.
140 Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
141 instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
142 to do frotz", as if you are giving orders to the codebase to change
143 its behavior. Try to make sure your explanation can be understood
144 without external resources. Instead of giving a URL to a mailing list
145 archive, summarize the relevant points of the discussion.
148 If you want to reference a previous commit in the history of a stable
149 branch, use the format "abbreviated hash (subject, date)", like this:
152 Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
156 The "Copy commit summary" command of gitk can be used to obtain this
157 format (with the subject enclosed in a pair of double-quotes), or this
158 invocation of `git show`:
161 git show -s --pretty=reference <commit>
164 or, on an older version of Git without support for --pretty=reference:
167 git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
171 === Generate your patch using Git tools out of your commits.
173 Git based diff tools generate unidiff which is the preferred format.
175 You do not have to be afraid to use `-M` option to `git diff` or
176 `git format-patch`, if your patch involves file renames. The
177 receiving end can handle them just fine.
180 Please make sure your patch does not add commented out debugging code,
181 or include any extra files which do not relate to what your patch
182 is trying to achieve. Make sure to review
183 your patch after generating it, to ensure accuracy. Before
184 sending out, please make sure it cleanly applies to the `master`
185 branch head. If you are preparing a work based on "next" branch,
186 that is fine, but please mark it as such.
189 === Sending your patches.
191 :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
193 Before sending any patches, please note that patches that may be
194 security relevant should be submitted privately to the Git Security
195 mailing list{security-ml}, instead of the public mailing list.
197 Learn to use format-patch and send-email if possible. These commands
198 are optimized for the workflow of sending patches, avoiding many ways
199 your existing e-mail client that is optimized for "multipart/*" mime
200 type e-mails to corrupt and render your patches unusable.
202 People on the Git mailing list need to be able to read and
203 comment on the changes you are submitting. It is important for
204 a developer to be able to "quote" your changes, using standard
205 e-mail tools, so that they may comment on specific portions of
206 your code. For this reason, each patch should be submitted
207 "inline" in a separate message.
209 Multiple related patches should be grouped into their own e-mail
210 thread to help readers find all parts of the series. To that end,
211 send them as replies to either an additional "cover letter" message
212 (see below), the first patch, or the respective preceding patch.
214 If your log message (including your name on the
215 `Signed-off-by` trailer) is not writable in ASCII, make sure that
216 you send off a message in the correct encoding.
218 WARNING: Be wary of your MUAs word-wrap
219 corrupting your patch. Do not cut-n-paste your patch; you can
220 lose tabs that way if you are not careful.
222 It is a common convention to prefix your subject line with
223 [PATCH]. This lets people easily distinguish patches from other
224 e-mail discussions. Use of markers in addition to PATCH within
225 the brackets to describe the nature of the patch is also
226 encouraged. E.g. [RFC PATCH] (where RFC stands for "request for
227 comments") is often used to indicate a patch needs further
228 discussion before being accepted, [PATCH v2], [PATCH v3] etc.
229 are often seen when you are sending an update to what you have
232 The `git format-patch` command follows the best current practice to
233 format the body of an e-mail message. At the beginning of the
234 patch should come your commit message, ending with the
235 `Signed-off-by` trailers, and a line that consists of three dashes,
236 followed by the diffstat information and the patch itself. If
237 you are forwarding a patch from somebody else, optionally, at
238 the beginning of the e-mail message just before the commit
239 message starts, you can put a "From: " line to name that person.
240 To change the default "[PATCH]" in the subject to "[<text>]", use
241 `git format-patch --subject-prefix=<text>`. As a shortcut, you
242 can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or
243 `-v <n>` instead of `--subject-prefix="PATCH v<n>"`.
245 You often want to add additional explanation about the patch,
246 other than the commit message itself. Place such "cover letter"
247 material between the three-dash line and the diffstat. For
248 patches requiring multiple iterations of review and discussion,
249 an explanation of changes between each iteration can be kept in
250 Git-notes and inserted automatically following the three-dash
251 line via `git format-patch --notes`.
254 Do not attach the patch as a MIME attachment, compressed or not.
255 Do not let your e-mail client send quoted-printable. Do not let
256 your e-mail client send format=flowed which would destroy
257 whitespaces in your patches. Many
258 popular e-mail applications will not always transmit a MIME
259 attachment as plain text, making it impossible to comment on
260 your code. A MIME attachment also takes a bit more time to
261 process. This does not decrease the likelihood of your
262 MIME-attached change being accepted, but it makes it more likely
263 that it will be postponed.
265 Exception: If your mailer is mangling patches then someone may ask
266 you to re-send them using MIME, that is OK.
269 Do not PGP sign your patch. Most likely, your maintainer or other people on the
270 list would not have your PGP key and would not bother obtaining it anyway.
271 Your patch is not judged by who you are; a good patch from an unknown origin
272 has a far better chance of being accepted than a patch from a known, respected
273 origin that is done poorly or does incorrect things.
275 If you really really really really want to do a PGP signed
276 patch, format it as "multipart/signed", not a text/plain message
277 that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is
278 not a text/plain, it's something else.
280 :security-ml-ref: footnoteref:[security-ml]
282 As mentioned at the beginning of the section, patches that may be
283 security relevant should not be submitted to the public mailing list
284 mentioned below, but should instead be sent privately to the Git
285 Security mailing list{security-ml-ref}.
287 Send your patch with "To:" set to the mailing list, with "cc:" listing
288 people who are involved in the area you are touching (the `git
289 contacts` command in `contrib/contacts/` can help to
290 identify them), to solicit comments and reviews.
292 :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
293 :git-ml: footnote:[The mailing list: git@vger.kernel.org]
295 After the list reached a consensus that it is a good idea to apply the
296 patch, re-send it with "To:" set to the maintainer{current-maintainer}
297 and "cc:" the list{git-ml} for inclusion. This is especially relevant
298 when the maintainer did not heavily participate in the discussion and
299 instead left the review to trusted others.
301 Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
302 `Tested-by:` lines as necessary to credit people who helped your
303 patch, and "cc:" them when sending such a final version for inclusion.
306 === Certify your work by adding your `Signed-off-by` trailer
308 To improve tracking of who did what, we ask you to certify that you
309 wrote the patch or have the right to pass it on under the same license
310 as ours, by "signing off" your patch. Without sign-off, we cannot
313 If (and only if) you certify the below D-C-O:
316 .Developer's Certificate of Origin 1.1
318 By making a contribution to this project, I certify that:
320 a. The contribution was created in whole or in part by me and I
321 have the right to submit it under the open source license
322 indicated in the file; or
324 b. The contribution is based upon previous work that, to the best
325 of my knowledge, is covered under an appropriate open source
326 license and I have the right under that license to submit that
327 work with modifications, whether created in whole or in part
328 by me, under the same open source license (unless I am
329 permitted to submit under a different license), as indicated
332 c. The contribution was provided directly to me by some other
333 person who certified (a), (b) or (c) and I have not modified
336 d. I understand and agree that this project and the contribution
337 are public and that a record of the contribution (including all
338 personal information I submit with it, including my sign-off) is
339 maintained indefinitely and may be redistributed consistent with
340 this project or the open source license(s) involved.
343 you add a "Signed-off-by" trailer to your commit, that looks like
347 Signed-off-by: Random J Developer <random@developer.example.org>
350 This line can be added by Git if you run the git-commit command with
353 Notice that you can place your own `Signed-off-by` trailer when
354 forwarding somebody else's patch with the above rules for
355 D-C-O. Indeed you are encouraged to do so. Do not forget to
356 place an in-body "From: " line at the beginning to properly attribute
357 the change to its true author (see (2) above).
359 This procedure originally came from the Linux kernel project, so our
360 rule is quite similar to theirs, but what exactly it means to sign-off
361 your patch differs from project to project, so it may be different
362 from that of the project you are accustomed to.
365 Also notice that a real name is used in the `Signed-off-by` trailer. Please
366 don't hide your real name.
369 If you like, you can put extra tags at the end:
371 . `Reported-by:` is used to credit someone who found the bug that
372 the patch attempts to fix.
373 . `Acked-by:` says that the person who is more familiar with the area
374 the patch attempts to modify liked the patch.
375 . `Reviewed-by:`, unlike the other tags, can only be offered by the
376 reviewers themselves when they are completely satisfied with the
377 patch after a detailed analysis.
378 . `Tested-by:` is used to indicate that the person applied the patch
379 and found it to have the desired effect.
381 You can also create your own tag or use one that's in common usage
382 such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
384 == Subsystems with dedicated maintainers
386 Some parts of the system have dedicated maintainers with their own
389 - `git-gui/` comes from git-gui project, maintained by Pratyush Yadav:
391 https://github.com/prati0100/git-gui.git
393 - `gitk-git/` comes from Paul Mackerras's gitk project:
395 git://ozlabs.org/~paulus/gitk
397 - `po/` comes from the localization coordinator, Jiang Xin:
399 https://github.com/git-l10n/git-po/
401 Patches to these parts should be based on their trees.
404 == An ideal patch flow
406 Here is an ideal patch flow for this project the current maintainer
407 suggests to the contributors:
409 . You come up with an itch. You code it up.
411 . Send it to the list and cc people who may need to know about
414 The people who may need to know are the ones whose code you
415 are butchering. These people happen to be the ones who are
416 most likely to be knowledgeable enough to help you, but
417 they have no obligation to help you (i.e. you ask for help,
418 don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
419 help you find out who they are.
421 . You get comments and suggestions for improvements. You may
422 even get them in an "on top of your change" patch form.
424 . Polish, refine, and re-send to the list and the people who
425 spend their time to improve your patch. Go back to step (2).
427 . The list forms consensus that the last round of your patch is
428 good. Send it to the maintainer and cc the list.
430 . A topic branch is created with the patch and is merged to `next`,
431 and cooked further and eventually graduates to `master`.
433 In any time between the (2)-(3) cycle, the maintainer may pick it up
434 from the list and queue it to `seen`, in order to make it easier for
435 people play with it without having to pick up and apply the patch to
436 their trees themselves.
439 == Know the status of your patch after submission
441 * You can use Git itself to find out when your patch is merged in
442 master. `git pull --rebase` will automatically skip already-applied
443 patches, and will let you know. This works only if you rebase on top
444 of the branch in which your patch has been merged (i.e. it will not
445 tell you if your patch is merged in `seen` if you rebase on top of
448 * Read the Git mailing list, the maintainer regularly posts messages
449 entitled "What's cooking in git.git" and "What's in git.git" giving
450 the status of various proposed changes.
453 == GitHub-Travis CI hints
455 With an account at GitHub (you can get one for free to work on open
456 source projects), you can use Travis CI to test your changes on Linux,
457 Mac (and hopefully soon Windows). You can find a successful example
458 test build here: https://travis-ci.org/git/git/builds/120473209
460 Follow these steps for the initial setup:
462 . Fork https://github.com/git/git to your GitHub account.
463 You can find detailed instructions how to fork here:
464 https://help.github.com/articles/fork-a-repo/
466 . Open the Travis CI website: https://travis-ci.org
468 . Press the "Sign in with GitHub" button.
470 . Grant Travis CI permissions to access your GitHub account.
471 You can find more information about the required permissions here:
472 https://docs.travis-ci.com/user/github-oauth-scopes
474 . Open your Travis CI profile page: https://travis-ci.org/profile
476 . Enable Travis CI builds for your Git fork.
478 After the initial setup, Travis CI will run whenever you push new changes
479 to your fork of Git on GitHub. You can monitor the test state of all your
480 branches here: https://travis-ci.org/__<Your GitHub handle>__/git/branches
482 If a branch did not pass all test cases then it is marked with a red
483 cross. In that case you can click on the failing Travis CI job and
484 scroll all the way down in the log. Find the line "<-- Click here to see
485 detailed test output!" and click on the triangle next to the log line
486 number to expand the detailed test output. Here is such a failing
487 example: https://travis-ci.org/git/git/jobs/122676187
489 Fix the problem and push your fix to your Git fork. This will trigger
490 a new Travis CI build to ensure all tests pass.
493 == MUA specific hints
495 Some of patches I receive or pick up from the list share common
496 patterns of breakage. Please make sure your MUA is set up
497 properly not to corrupt whitespaces.
499 See the DISCUSSION section of linkgit:git-format-patch[1] for hints on
500 checking your patch by mailing it to yourself and applying with
503 While you are at it, check the resulting commit log message from
504 a trial run of applying the patch. If what is in the resulting
505 commit is not exactly what you would want to see, it is very
506 likely that your maintainer would end up hand editing the log
507 message when he applies your patch. Things like "Hi, this is my
508 first patch.\n", if you really want to put in the patch e-mail,
509 should come after the three-dash line that signals the end of the
515 (Johannes Schindelin)
518 I don't know how many people still use pine, but for those poor
519 souls it may be good to mention that the quell-flowed-text is
520 needed for recent versions.
522 ... the "no-strip-whitespace-before-send" option, too. AFAIK it
523 was introduced in 4.60.
529 And 4.58 needs at least this.
531 diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
532 Author: Linus Torvalds <torvalds@g5.osdl.org>
533 Date: Mon Aug 15 17:23:51 2005 -0700
535 Fix pine whitespace-corruption bug
537 There's no excuse for unconditionally removing whitespace from
538 the pico buffers on close.
540 diff --git a/pico/pico.c b/pico/pico.c
543 @@ -219,7 +219,9 @@ PICO *pm;
544 switch(pico_all_done){ /* prepare for/handle final events */
545 case COMP_EXIT : /* already confirmed */
557 > A patch to SubmittingPatches, MUA specific help section for
558 > users of Pine 4.63 would be very much appreciated.
560 Ah, it looks like a recent version changed the default behavior to do the
561 right thing, and inverted the sense of the configuration option. (Either
562 that or Gentoo did it.) So you need to set the
563 "no-strip-whitespace-before-send" option, unless the option you have is
564 "strip-whitespace-before-send", in which case you should avoid checking
568 === Thunderbird, KMail, GMail
570 See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1].
574 "|" in the `*Summary*` buffer can be used to pipe the current
575 message to an external program, and this is a handy way to drive
576 `git am`. However, if the message is MIME encoded, what is
577 piped into the program is the representation you see in your
578 `*Article*` buffer after unwrapping MIME. This is often not what
579 you would want for two reasons. It tends to screw up non ASCII
580 characters (most notably in people's names), and also
581 whitespaces (fatal in patches). Running "C-u g" to display the
582 message in raw form before using "|" to run the pipe can work