[PATCH] Add SubmittingPatches

[PATCH] Add SubmittingPatches

[Junio C Hamano]

Not that I have stricter patch submission standards than ordinary
projects, I wanted to have it to make sure people understand
what they are doing when they add their own Signed-off-by line.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 Documentation/SubmittingPatches |  130 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 130 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/SubmittingPatches

3de1a21da62e2ad89bfb25f742384b9af496e4e0
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
new file mode 100644
--- /dev/null
+++ b/Documentation/SubmittingPatches
@@ -0,0 +1,130 @@
+I started reading over the SubmittingPatches document for Linux
+kernel, primarily because I wanted to have a document similar to
+it for the core GIT to make sure people understand what they are
+doing when they write "Signed-off-by" line.
+
+But the patch submission requirements are a lot more relaxed
+here, because the core GIT is thousand times smaller ;-).  So
+here is only the 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 long, that's a sign that you
+probably need to split up your commit to finer grained pieces.
+
+
+(2) Generate your patch using git/cogito out of your commits.
+
+git diff tools generate unidiff which is the preferred 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 needs 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 submitting
+e-mail "inline".  WARNING: Be wary of your MUAs word-wrap
+corrupting your patch.  Do not cut-n-paste your patch.
+
+It is 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.  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.
+
+Note that your maintainer does not subscribe to the git mailing
+list (he reads it via mail-to-news gateway).  If your patch is
+for discussion first, send it "To:" the mailing list, and
+optoinally "cc:" him.  If it is trivially correct or after list
+discussion reached consensus, send it "To:" the maintainer and
+optionally "cc:" the list.
+
+
+(6) 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 core GIT 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>
+
+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.

Re: [PATCH] Add SubmittingPatches

[Johannes Schindelin]

Hi,

On Sat, 13 Aug 2005, Junio C Hamano wrote:

> +Note that your maintainer does not subscribe to the git mailing
> +list (he reads it via mail-to-news gateway).

Wow. I didn't even read a newsgroup in decades...

BTW, 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.

Ciao,
Dscho

Re: [PATCH] Add SubmittingPatches

[Linus Torvalds]

On Tue, 16 Aug 2005, Johannes Schindelin wrote:
> 
> BTW, 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.

And 4.58 needs at least this

		Linus

---
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;
 

Re: [PATCH] Add SubmittingPatches

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> BTW, 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.

Contributions from pine users are very much appreciated.  Among
the patches I either receive or pick up from the list, 15-20%
have WS corruption one way or another, which is starting to
annoy me.  What annoys me more are MIME quoted printable,
though, but that is partly my fault.

I haven't counted what percentage of those WS corrupted ones are
from Pine, so please do not take the above 15-20% number to have
anything to do with Pine.

Re: [PATCH] Add SubmittingPatches

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

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

Wow.

This is a _terrible_ one.  Isn't pico code also supposed to be a
standalone editor of some sort?  I wonder how anybody could
tolerate this kind of "dictatorship ;-)".

At least the changelog entry seems to say that 4.60 removed this
"feature".

Re: [PATCH] Add SubmittingPatches

[Johannes Schindelin]

Hi,

On Mon, 15 Aug 2005, Linus Torvalds wrote:

> On Tue, 16 Aug 2005, Johannes Schindelin wrote:
> > 
> > BTW, 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.
> 
> And 4.58 needs at least this
>
>[...]

Sorry, I forgot the "no-strip-whitespace-before-send" option, too. AFAIK 
it was introduced in 4.60 (the "fix" Junio was referring to).

Maybe we should enhance git-applymbox to detect whitespace corruption in 
particular, and output the User-Agent header (or if that does not 
exist, the Message-ID header; thanks, pine) on error.

Ciao,
Dscho

Re: [PATCH] Add SubmittingPatches

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Maybe we should enhance git-applymbox to detect whitespace corruption in 
> particular, and output the User-Agent header (or if that does not 
> exist, the Message-ID header; thanks, pine) on error.

We _could_ but I doubt it would help anybody.  The damage is
already done.

Re: [PATCH] Add SubmittingPatches

[Johannes Schindelin]

Hi,

On Mon, 15 Aug 2005, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > Maybe we should enhance git-applymbox to detect whitespace corruption in 
> > particular, and output the User-Agent header (or if that does not 
> > exist, the Message-ID header; thanks, pine) on error.
> 

Alternatively, SubmittingPatches could include a big fat CAVEAT, and a 
note that the submitter might want to send a single SP to herself, save 
the received mail and check that all is well, prior to sending the first 
patch. I mean, well, erm, it is sort of, uh, annoying, to send out a 
corrupt patch *speaksofyourstruly*.

Ciao,
Dscho

Re: [PATCH] Add SubmittingPatches

[Ryan Anderson]

On Tue, Aug 16, 2005 at 03:41:04AM +0200, Johannes Schindelin wrote:
> On Mon, 15 Aug 2005, Junio C Hamano wrote:
> 
> > Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> > 
> > > Maybe we should enhance git-applymbox to detect whitespace corruption in 
> > > particular, and output the User-Agent header (or if that does not 
> > > exist, the Message-ID header; thanks, pine) on error.
> > 
> 
> Alternatively, SubmittingPatches could include a big fat CAVEAT, and a 
> note that the submitter might want to send a single SP to herself, save 
> the received mail and check that all is well, prior to sending the first 
> patch. I mean, well, erm, it is sort of, uh, annoying, to send out a 
> corrupt patch *speaksofyourstruly*.

If you have some trouble sending them out, you can use
	git format-patch --mbox
and
	git send-email

which seems to consistently do the right thing.


-- 

Ryan Anderson
  sometimes Pug Majere

Submitting patches w/ Thunderbird [was: Re: [PATCH] Add SubmittingPatches]

[A Large Angry SCM]

Johannes Schindelin wrote:
> Hi,
> 
> On Mon, 15 Aug 2005, Junio C Hamano wrote:
> 
>>Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>>
>>>Maybe we should enhance git-applymbox to detect whitespace corruption in 
>>>particular, and output the User-Agent header (or if that does not 
>>>exist, the Message-ID header; thanks, pine) on error.
> 
> Alternatively, SubmittingPatches could include a big fat CAVEAT, and a 
> note that the submitter might want to send a single SP to herself, save 
> the received mail and check that all is well, prior to sending the first 
> patch. I mean, well, erm, it is sort of, uh, annoying, to send out a 
> corrupt patch *speaksofyourstruly*.

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.5.4
		http://extensionroom.mozdev.org/more-info/exteditor

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		=> 999

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