|
|
@@ -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. |
|
|
|
|