Skip to main content
diff options
authorGit Development Community2009-09-29 23:47:03 +0000
committerShawn O. Pearce2009-09-29 23:47:03 +0000
commit1a6964c8274c50f0253db75f010d78ef0e739343 (patch)
treeca833cc7cf6fc8c7b9850dee258f3a356c790ffc /SUBMITTING_PATCHES
Initial JGit contribution to
Per CQ 3448 this is the initial contribution of the JGit project to It is derived from the historical JGit repository at commit 3a2dd9921c8a08740a9e02c421469e5b1a9e47cb. Signed-off-by: Shawn O. Pearce <>
Diffstat (limited to 'SUBMITTING_PATCHES')
1 files changed, 366 insertions, 0 deletions
new file mode 100644
index 0000000000..82d2c253d1
--- /dev/null
@@ -0,0 +1,366 @@
+Short Version:
+ - Make small logical changes.
+ - Provide a meaningful commit message.
+ - Include your Signed-Off-By line to note you agree with the
+ Developer's Certificate of Origin (see below).
+ - Make sure all code is under the proper license:
+ 3-clause BSD
+ - Use a subject prefix of "[PATCH JGIT ...]" when sending any
+ patches directly by email.
+ - Send by email to the maintainers, cc'ing the git mailing list
+ which is currently used for both Git and JGit:
+ maintainers : "Shawn O. Pearce" <>
+ Robin Rosenberg <>
+ git list :
+ git list info :
+Long Version:
+I wanted a file describing how to submit patches for JGit,
+so I started with the one found in the core Git distribution
+(Documentation/SubmittingPatches), which itself was based on the
+patch submission guidelines for the Linux kernel.
+However there are some differences, so please review and familiarize
+yourself with the following relevant bits:
+(1) Make separate commits for logically separate changes.
+Unless your patch is really trivial, you should not be sending
+out a patch that was generated between your working tree and your
+commit head. Instead, always make a commit with complete commit
+message and generate a series of patches from your repository.
+It is a good discipline.
+Describe the technical detail of the change(s).
+If your description starts to get too long, that's a sign that you
+probably need to split up your commit to finer grained pieces.
+I am very picky about formatting. Make sure your final version
+of every file was formatted using the Eclipse code formatter
+using the project specific settings (Properties->Java Code
+Style->Formatter->"Java Conventions [built-in]").
+(2) Generate your patch using git tools out of your commits.
+git based diff tools (git, and StGIT included) generate unidiff,
+which is the only acceptable format.
+You do not have to be afraid to use -M option to "git diff" or "git
+format-patch", if your patch involves file renames. The receiving
+end can handle them just fine.
+Please make sure your patch does not include any extra files which
+do not belong in a patch submission. Make sure to review your
+patch after generating it, to ensure accuracy. Before sending out,
+please make sure it cleanly applies to the "master" branch head.
+(3) Sending your patches.
+People on the git mailing list need to be able to read and comment
+on the changes you are submitting. It is important for a developer
+to be able to "quote" your changes, using standard e-mail tools, so
+that they may comment on specific portions of your code. For this
+reason, all patches should be submitted "inline". WARNING: Be wary
+of your MUAs word-wrap corrupting your patch. Do not cut-n-paste
+your patch; you can lose tabs that way if you are not careful.
+It is a common convention to prefix your subject line with [PATCH].
+This lets people easily distinguish patches from other e-mail
+"git format-patch" command follows the best current practice to
+format the body of an e-mail message. At the beginning of the patch
+should come your commit message, ending with the Signed-off-by:
+lines, and a line that consists of three dashes, followed by the
+diffstat information and the patch itself. If you are forwarding a
+patch from somebody else, optionally, at the beginning of the e-mail
+message just before the commit message starts, you can put a "From:
+" line to name that person.
+You often want to add additional explanation about the patch,
+other than the commit message itself. Place such "cover letter"
+material between the three dash lines and the diffstat.
+Do not attach the patch as a MIME attachment, compressed or not.
+Do not let your e-mail client send quoted-printable. Do not let your
+e-mail client send format=flowed which would destroy whitespaces
+in your patches. Many popular e-mail applications will not always
+transmit a MIME attachment as plain text, making it impossible to
+comment on your code. A MIME attachment also takes a bit more
+time to process. This does not decrease the likelihood of your
+MIME-attached change being accepted, but it makes it more likely
+that it will be postponed.
+Exception: If your mailer is mangling patches then someone may ask
+you to re-send them using MIME, that is OK.
+Do not PGP sign your patch, at least for now. Most likely, your
+maintainer or other people on the list would not have your PGP
+key and would not bother obtaining it anyway. Your patch is not
+judged by who you are; a good patch from an unknown origin has a
+far better chance of being accepted than a patch from a known,
+respected origin that is done poorly or does incorrect things.
+If you really really really really want to do a PGP signed
+patch, format it as "multipart/signed", not a text/plain message
+that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is
+not a text/plain, it's something else.
+Note that your maintainer does not necessarily read everything
+on the git mailing list. If your patch is for discussion first,
+send it "To:" the mailing list, and optionally "cc:" him. If it
+is trivially correct or after the list reached a consensus, send it
+"To:" the maintainer and optionally "cc:" the list.
+(4) Check the license
+JGit is licensed under the 3-clause (new-style) BSD.
+Because of this licensing model *every* file within the project
+*must* list which license covers it in the header of the file.
+Any new contributions to an existing file *must* be submitted under
+the current license of that file. Any new files *must* clearly
+indicate which license they are provided under in the file header.
+Please verify that you are legally allowed and willing to submit your
+changes under the license covering each file *prior* to submitting
+your patch. It is virtually impossible to remove a patch once it
+has been applied and pushed out.
+(5) Sign your work
+To improve tracking of who did what, we've borrowed the "sign-off"
+procedure from the Linux kernel project on patches that are being
+emailed around. Although JGit is a lot smaller project it is
+a good discipline to follow it.
+The sign-off is a simple line at the end of the explanation for the
+patch, which certifies that you wrote it or otherwise have the right
+to pass it on as a open-source patch. The rules are pretty simple:
+if you can certify the below:
+ Developer's Certificate of Origin 1.1
+ By making a contribution to this project, I certify that:
+ (a) The contribution was created in whole or in part by me
+ and I have the right to submit it under the open source
+ license indicated in the file; or
+ (b) The contribution is based upon previous work that, to the
+ best of my knowledge, is covered under an appropriate
+ open source license and I have the right under that
+ license to submit that work with modifications, whether
+ created in whole or in part by me, under the same open
+ source license (unless I am permitted to submit under
+ a different license), as indicated in the file; or
+ (c) The contribution was provided directly to me by some
+ other person who certified (a), (b) or (c) and I have
+ not modified it.
+ (d) I understand and agree that this project and the
+ contribution are public and that a record of the
+ contribution (including all personal information I
+ submit with it, including my sign-off) is maintained
+ indefinitely and may be redistributed consistent with
+ this project or the open source license(s) involved.
+then you just add a line saying
+ Signed-off-by: Random J Developer <>
+This line can be automatically added by git if you run the git-commit
+command with the -s option.
+Some people also put extra tags at the end. They'll just be ignored
+for now, but you can do this to mark internal company procedures
+or just point out some special detail about the sign-off.
+MUA specific hints
+Some of patches I receive or pick up from the list share common
+patterns of breakage. Please make sure your MUA is set up
+properly not to corrupt whitespaces. Here are two common ones
+I have seen:
+* Empty context lines that do not have _any_ whitespace.
+* Non empty context lines that have one extra whitespace at the
+ beginning.
+One test you could do yourself if your MUA is set up correctly is:
+* Send the patch to yourself, exactly the way you would, except
+ To: and Cc: lines, which would not contain the list and
+ maintainer address.
+* Save that patch to a file in UNIX mailbox format. Call it say
+ a.patch.
+* Try to apply to the tip of the "master" branch from the
+ egit.git public repository:
+ $ git fetch git:// master:test-apply
+ $ git checkout test-apply
+ $ git reset --hard
+ $ git am a.patch
+If it does not apply correctly, there can be various reasons.
+* Your patch itself does not apply cleanly. That is _bad_ but
+ does not have much to do with your MUA. Please rebase the
+ patch appropriately.
+* Your MUA corrupted your patch; applymbox would complain that
+ the patch does not apply. Look at .dotest/ subdirectory and
+ see what 'patch' file contains and check for the common
+ corruption patterns mentioned above.
+* While you are at it, check what are in 'info' and
+ 'final-commit' files as well. If what is in 'final-commit' is
+ not exactly what you would want to see in the commit log
+ message, it is very likely that your maintainer would end up
+ hand editing the log message when he applies your patch.
+ Things like "Hi, this is my first patch.\n", if you really
+ want to put in the patch e-mail, should come after the
+ three-dash line that signals the end of the commit message.
+(Johannes Schindelin)
+I don't know how many people still use pine, but for those poor
+souls it may be good to mention that the quell-flowed-text is
+needed for recent versions.
+... the "no-strip-whitespace-before-send" option, too. AFAIK it
+was introduced in 4.60.
+(Linus Torvalds)
+And 4.58 needs at least this.
+diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
+Author: Linus Torvalds <>
+Date: Mon Aug 15 17:23:51 2005 -0700
+ Fix pine whitespace-corruption bug
+ There's no excuse for unconditionally removing whitespace from
+ the pico buffers on close.
+diff --git a/pico/pico.c b/pico/pico.c
+--- a/pico/pico.c
++++ b/pico/pico.c
+@@ -219,7 +219,9 @@ PICO *pm;
+ switch(pico_all_done){ /* prepare for/handle final events */
+ case COMP_EXIT : /* already confirmed */
+ packheader();
++#if 0
+ stripwhitespace();
+ c |= COMP_EXIT;
+ break;
+(Daniel Barkalow)
+> A patch to SubmittingPatches, MUA specific help section for
+> users of Pine 4.63 would be very much appreciated.
+Ah, it looks like a recent version changed the default behavior to do the
+right thing, and inverted the sense of the configuration option. (Either
+that or Gentoo did it.) So you need to set the
+"no-strip-whitespace-before-send" option, unless the option you have is
+"strip-whitespace-before-send", in which case you should avoid checking
+(A Large Angry SCM)
+Here are some hints on how to successfully submit patches inline using
+This recipe appears to work with the current [*1*] Thunderbird from Suse.
+The following Thunderbird extensions are needed:
+ AboutConfig 0.5
+ External Editor 0.7.2
+1) Prepare the patch as a text file using your method of choice.
+2) Before opening a compose window, use Edit->Account Settings to
+uncheck the "Compose messages in HTML format" setting in the
+"Composition & Addressing" panel of the account to be used to send the
+patch. [*2*]
+3) In the main Thunderbird window, _before_ you open the compose window
+for the patch, use Tools->about:config to set the following to the
+indicated values:
+ mailnews.send_plaintext_flowed => false
+ mailnews.wraplength => 0
+4) Open a compose window and click the external editor icon.
+5) In the external editor window, read in the patch file and exit the
+editor normally.
+6) Back in the compose window: Add whatever other text you wish to the
+message, complete the addressing and subject fields, and press send.
+7) Optionally, undo the about:config/account settings changes made in
+steps 2 & 3.
+*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
+9.3 professional updates.
+*2* It may be possible to do this with about:config and the following
+settings but I haven't tried, yet.
+ mail.html_compose => false
+ mail.identity.default.compose_html => false
+ => false
+'|' in the *Summary* buffer can be used to pipe the current
+message to an external program, and this is a handy way to drive
+"git am". However, if the message is MIME encoded, what is
+piped into the program is the representation you see in your
+*Article* buffer after unwrapping MIME. This is often not what
+you would want for two reasons. It tends to screw up non ASCII
+characters (most notably in people's names), and also
+whitespaces (fatal in patches). Running 'C-u g' to display the
+message in raw form before using '|' to run the pipe can work
+this problem around.

Back to the top