diff options
| -rw-r--r-- | SUBMITTING_PATCHES | 300 |
1 files changed, 24 insertions, 276 deletions
diff --git a/SUBMITTING_PATCHES b/SUBMITTING_PATCHES index 9a1a085990..55122aea83 100644 --- a/SUBMITTING_PATCHES +++ b/SUBMITTING_PATCHES @@ -20,8 +20,8 @@ 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: +However there are quite a few differences, so please review and +familiarize yourself with the following relevant bits: (1) Make separate commits for logically separate changes. @@ -58,70 +58,12 @@ 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. +(3) Check the license. -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. +JGit is licensed under the Eclipse Development License (EDL), +which is a renamed version of the new style/3-clause BSD license. -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 +Under 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 @@ -133,225 +75,31 @@ 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. +(4) Review the Eclipse Due Diligence Process. -* Try to apply to the tip of the "master" branch from the - egit.git public repository: + http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf - $ 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. +(5) Sending your patches. -* 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. +"git format-patch" command follows the best current practice to +format a commit as a reviewable text message. -*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 +At the beginning of the patch should come your commit message, +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, or please +place it in the bug description itself. +Open a new bug on the Eclipse bug tracker on the EGit project: -Gnus ----- + https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EGit -'|' 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. +Attach the mailbox file(s) created by "git format-patch" to the bug. |