diff options
Diffstat (limited to 'SUBMITTING_PATCHES')
| -rw-r--r-- | SUBMITTING_PATCHES | 366 |
1 files changed, 366 insertions, 0 deletions
diff --git a/SUBMITTING_PATCHES b/SUBMITTING_PATCHES new file mode 100644 index 0000000000..82d2c253d1 --- /dev/null +++ b/SUBMITTING_PATCHES @@ -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" <spearce@spearce.org> + Robin Rosenberg <robin.rosenberg@dewire.com> + + git list : git@vger.kernel.org + + git list info : http://vger.kernel.org/vger-lists.html#git + +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 +discussions. + +"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 <random@developer.example.org> + +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://repo.or.cz/egit.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. + + +Pine +---- + +(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 <torvalds@g5.osdl.org> +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(); ++#endif + 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 +it. + + +Thunderbird +----------- + +(A Large Angry SCM) + +Here are some hints on how to successfully submit patches inline using +Thunderbird. + +This recipe appears to work with the current [*1*] Thunderbird from Suse. + +The following Thunderbird extensions are needed: + AboutConfig 0.5 + http://aboutconfig.mozdev.org/ + External Editor 0.7.2 + http://globs.org/articles.php?lng=en&pg=8 + +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. + + +[Footnotes] +*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 + mail.identity.id?.compose_html => false + + + +Gnus +---- + +'|' 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. + |