From: Randy Dunlap <randy.dunlap@oracle.com>
Requested by Jeff Garzik.
Add info about various email clients and their applicability

in being used to send Linux kernel patches.
Some notes takes from http://mbligh.org/linuxdocs/Email/Clients

Portions used with permission.
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>

---

 Documentation/email-clients.txt |  158 ++++++++++++++++++++++++++++++++++++++++

 1 file changed, 158 insertions(+)
--- /dev/null

+++ linux-2.6.23-rc5-git1/Documentation/email-clients.txt

@@ -0,0 +1,158 @@

+Email clients info for Linux

+======================================================================

+

+General Preferences

+----------------------------------------------------------------------

+Patches for the Linux kernel are submitted via email, preferably as

+inline text in the body of the email.  Some maintainers accept

+attachments, but then the attachments should have content-type

+"text/plain".  However, attachments are generally frowned upon because

+it makes quoting portions of the patch more difficult in the patch

+review process.

+

+Email clients that are used for Linux kernel patches should send the

+patch text untouched.  For example, they should not modify or delete tabs

+or spaces, even at the beginning or end of lines.

+

+<question about character set encoding/code pages:>

+They also should not modify the character set encoding of the text.

+

+Email clients should generate and maintain References: or In-Reply-To:

+headers so that mail threading is not broken.

+

+Copy-and-paste (or cut-and-paste) usually does not work for patches

+because tabs are converted to spaces.  I have seen comments that

+xclipboard, xclip, and/or xcutsel do work, but I cannot confirm this.

+

+Don't use PGP/GPG signatures in mail that contains patches.

+This breaks many scripts that read and apply the patches.

+(This should be fixable. ??)

+

+

+Some email client (MUA) hints

+--------------------------------------------------...
[ message continues ]

Evolution_ ?

...

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+TkRat (GUI)

+

+Works.  Use "Insert file..." or external editor.
--

Stefan Richter

-=====-=-=== =--= -=-==

http://arcgraph.de/sr/
-

Can someone describe the problems with just attaching the patch in

Thunderbird?  It's what Martin says he does on the linked document...
Chris
-

Email clients don't like to quote attachments, even text/plain ones,

which then makes attached patches much more difficult to review and

comment on (i.e. you greatly reduce the number of reviewers).
	Jeff
-

Interestingly, Thunderbird does this right and simply

adds text/plain attachments to the quoted text.
--

Politics is the struggle between those who want to make their country

the best in the world, and those who believe it already is.  Each group

calls the other unpatriotic.

-

Devolution allows the same, but most other mailers dont. Esp the text

based onces which are the majority under the people you want reviews

from.
-

I still prefer patches directly inline, but mutt both is a text based

MUA and defaults to adding text/plain attachments to the quoted text.
cu

Adrian
-- 
       "Is there not promise of rain?" Ling Tan asked suddenly out

        of the darkness. There had been need of rain for many days.

       "Only a promise," Lao Er said.

                                       Pearl S. Buck - Dragon Seed
-

Thunderbird, at least, will automatically inline a single text/plain

attachment when replying. (At least with my current settings, it does.)
Chris

-

No, the thing is: you send it attached with Thunderbird,

and my PINE strips it on reply _because_ it is an attachment.
	Jan

--

-

There's no setting to tell it to quote plaintext attachments on reply?

If someone with thunderbird replies to it the patch is automatically quoted.
Guess I need to get the external_editor extension.
Chris

-

I dont know about Thunderbird, but Seamonkey apparently only includes

text/plain attachments in the reply quote if they feature

''Content-Disposition: inline''.  It does not include attachments with

''Content-Disposition: attachment; filename="abc123.patch"'' even if

they are text/plain.

--

Stefan Richter

-=====-=-=== =--= -==-=

http://arcgraph.de/sr/

-

The faint whining noise from the recipients at the other end.
Mostly if it's text/plain, the noise is very faint, only the

most militant care, and it's fairly easy to ignore ;-)
M.
-

It should work with default settings.
mutt doesn't come with an editor, so whatever editor you use should be

used in a way that there are no automatic linebreaks. Most editors have

an "insert file" option that inserts the contents of a file unaltered.
cu

Adrian
-- 
       "Is there not promise of rain?" Ling Tan asked suddenly out

        of the darkness. There had been need of rain for many days.

       "Only a promise," Lao Er said.

                                       Pearl S. Buck - Dragon Seed
-

I can't agree with this.
It took me lots of time to configure mutt to work well for me in the first

time. Just default settings are far _not_ enough, especially for us

non-english-speakers. One common setting is the encoding, of course, lkml

prefers UTF-8, so I must set my mutt with `set send_charset="us-ascii:utf-8"`.
Manuals of mutt told me to add "subscribe linux-kernel@vger.kernel.org" if I

subscribed lkml, but in fact, we'd better _not_ add this, or it will drop

myself from cc list.
Yes, you can `set editor="vi"` or other editors you prefer.
Regards.
--

"Bill, look, we understand that you're interested in selling us this

operating system, but compare it to ours.  We can't possibly take such

a retrograde step."
-

This makes sense, but it's not really a mutt specific issue and

problems because mutt prefers iso-8859-1 over UTF-8 by default are
Whether or not people want to get personal copies of answers to mailing

list posts is a religious issue being second only to the vi<->emacs wars...
But as far as I understand it, this documentation is intended to help

people to get sending patches right (no line wrap etc.), not as a 
cu

Adrian
-- 
       "Is there not promise of rain?" Ling Tan asked suddenly out

        of the darkness. There had been need of rain for many days.

       "Only a promise," Lao Er said.

                                       Pearl S. Buck - Dragon Seed
-

Definitely.

and to reduce the amount of repetition that we have to do.
I'll add a bit about it not being complete s/w package config info.
thanks,

~Randy

-

One point from this email that might be appropriate for the

"General Preferences" section of your document would be to suggest

configuring the MUA to send text encoded as UTF-8, something like:
The kernel source code is encoded in UTF-8, and if you configure your

email client to send emails UTF-8 encoded you avoid some possible 
cu

Adrian
-- 
       "Is there not promise of rain?" Ling Tan asked suddenly out

        of the darkness. There had been need of rain for many days.

       "Only a promise," Lao Er said.

                                       Pearl S. Buck - Dragon Seed
-

You should also have a look at the "MUA specific hints" section of

Documentation/SubmittingPatches in the Git source distribution which 
Alpine is the successor of Pine.  Issues that were found in some earlier

Pine versions wrt patch sending are now fixed.
Here's the relevant config options. In the "Sending Preferences"

section:
 - "Do Not Send Flowed Text" must be enabled
 - "Strip Whitespace Before Sending" must be disabled
When composing the message, the cursor should be placed where the patch

should appear, and then pressing CTRL-R let you specify the patch file

to insert into the message.
Nicolas

-

I have quell-flowed-text *disabled* and there is no problem.
	Jan
test:
--- /dev/fd/63	2007-09-11 21:08:05.555626230 +0200

+++ /dev/fd/62	2007-09-11 21:08:05.555626230 +0200

@@ -1,3 +1,3 @@

-total 52

--rw-r--r-- 1 jengelh users 52765 Sep 10 20:42 random.png

 -rw-r--r-- 1 jengelh users     0 Sep 11 21:07 pat

+-rw-r--r-- 1 jengelh users 52765 Sep 10 20:42 random.png

+total 52

-

There were no problems with sending patches in pine.
Pine had problems with UTF-8, and that's where alpine is fixed, but 
cu

Adrian
-- 
       "Is there not promise of rain?" Ling Tan asked suddenly out

        of the darkness. There had been need of rain for many days.

       "Only a promise," Lao Er said.

                                       Pearl S. Buck - Dragon Seed
-

Pine [4.64] has problems with ISO-2022-JP, but not UTF-8 AFAICT.
	Jan

--

-

One old version did have problems with spaces at the end of lines

despite the config option, and you had to manually patch it if your

distro didn't.
Nicolas

-

This could be, but it's not worth documenting that there once was one

broken version.
cu

Adrian
-- 
       "Is there not promise of rain?" Ling Tan asked suddenly out

        of the darkness. There had been need of rain for many days.

       "Only a promise," Lao Er said.

                                       Pearl S. Buck - Dragon Seed
-

When composing mail select: Preformat

  from Format->Heading->Preformatted (Ctrl-7)

  or the toolbar
Then use:

  Insert->Text File... (Alt-n x)
to insert the patch.
-

Yep, lousy keyboard.  ;)
I've updated the text file and will resend it shortly.
Thanks for everyone's comments.

(not replying to each one indiviually)
---

~Randy

-

You can also diff -Nru old.c new.c | xclip, select Preformat, then

paste with the middle button.
Lee

-

mutt does not come with text editor, so

I'd like to add note about vim:
=2E..if you want to include patch inline.

(a)ttach works fine without "set paste".
--=20

Do what you love because life is too short for anything else.

Ah, I shall try:
  cat `quilt top` | xclip
next time I have a single patch to send.
-

Oh, great! Thank you for this hint.
--

"Bill, look, we understand that you're interested in selling us this

operating system, but compare it to ours.  We can't possibly take such

a retrograde step."
-