Jump to: navigation, search

MailingListEtiquette

Mailing List Etiquette

Across most open source projects a very specific email posting style is used. This is an attempt to document the main points of that style.

Formatting

Plain Text

Please don't send HTML email. Send your email as plain text only. You really don't need any fancy formatting that HTML allows. Also, HTML email will screw up the formatting of any code you quote in your email.

If you do send HTML email (please don't), at least configure your client to include a plain text alternative as an attachment.

Line Wrapping

Lines should be wrapped at 72 characters. That is, in the plain text email you send, every line will contain a carriage return character in the 72nd column or before.

The exception to this is quoted text - the quoted text should not be line wrapped at all, especially if you are quoting someone's patch in your reply.

Replies

We use the interleaved style of replies. You place your replies to specific points directly under those points in the quoted text.

> Red is my favorite color.

Red sucks.

> But yellow is nice sometimes.

I agree. Yellow is nice.

Reply Level Indication

When quoting previous emails in our replies, we use > to differentiate the quoted text from our email. You can have multiple levels of replies indented like this.

> > > Red is my favorite color.
> > 
> > Red sucks.
> 
> Does not!

Does too!

Attribution Lines

Quoted text should also be preceeded by an attribution line.

Bob wrote:
> Jim wrote:
> > Bob wrote:
> > > Red is my favorite color.
> > 
> > Red sucks.
> 
> Does not!

Does too!


This is important because if someone gets cc-ed on a conversation and is missing the context, the attribution lines help them make sense of the conversation so far.

Trimming

You don't need to quote all of an email in order to respond to one specific point. Rather than doing:

> Red is my favorite color.

Red sucks!

> But yellow is nice sometimes.
>
> I have a lot of opinions on colors.


you should trim the parts of the quoted email that aren't relevant to your contribution. So, this would be sufficient:

> Red is my favorite color.

Red sucks!


Also, it is okay to reformat the original email slightly when trimming. Rather than:

> Red is my favorite color. But yellow is nice sometimes. I have a

Yellow rocks!


it's better to do:

> But yellow is nice sometimes.

Yellow rocks!


However, don't go overboard with trimming. Retain any context that might be useful to people joining the thread later.

Threading

Email clients insert a Message-ID: header and when you reply to an email, that email's ID will be included in the In-Reply-To: header of your response. This allows email clients to display the thread like this:

From    Subject            Date
Joe     Pizza!             13.00
Ray       Re: Pizza!       13.25
Sue       Re: Pizza!       13.15
Bob     Colors             12.02
Jim       Re: Colors       13.05
Bob         Re: Colors     13.10
Mary      Re: Colors       12.30


See also this nice example of a mailing list thread.

Many folks who deal with a lot of email rely heavily on threading like this. For example, they can quickly glance at a thread and mark all the emails in the thread as read.

Things get annoying when people either use a mail client that does not handle threading correctly or hijack a thread for a completely different subject. So, instead, you might get:

From    Subject            Date
Bob     Colors             12.02
Joe       Pizza!           13.20
Ray         Re: Pizza!     13.25
Jim       Re: Colors       13.05
Mary      Re: Colors       12.30
Sue     Re: Pizza!         13.15
Bob     Re: Colors         13.10


What happened here is that Joe hijacked the Colors thread with his Pizza! email and both Bob and Sue are using mail clients that don't thread correctly.

This drives people crazy! Please make sure you avoid both problems.

Changing Subject

Sometimes it is appropriate to change the subject of a thread rather than starting a new thread. For example, you my want to drill down into a subset of subject of the original thread. One convention for doing this is:

From    Subject                        Date
Bob     Colors                         12.02
Jim       Red [was Re: Colors]         13.05
Bob         Re: Red [was Re: Colors]   13.10
Mary      Re: Colors                   12.30

Netiquette

The threading section above dips into a topic known as 'netiquette'. It is considered bad form (i.e. bad etiquette) to hijack a thread. Indeed, formatting your emails in some strange way is considered bad netiquette.

This is a large topic, but I'll try and cover the most important and relevant items.

Keep Discussions On-List

When replying to a discussion, or starting a new discussion, your instinct should be to have that discussion on the appropriate mailing list.

Avoid taking a discussion off-list by replying directly without cc-ing the mailing list.

Avoid starting a discussion off-list. If you find yourself cc-ing more than 2 or 3 people, you should probably just cc a mailing list.

We use mailing lists because it gives a wider audience the opportunity to stay involved or informed, it encourages openness and it means the discussion is archived for future reference.

Yes, sometimes it's not appropriate to discussion something on a mailing list. But this should be the exception, not the rule.

Job postings

OpenStack-related job postings should be posted to the (free) OpenStack job board, not the mailing lists.

Patches

(We don't usually send patches to the mailing list in OpenStack, but the sake of completeness ...)

The correct format for sending patches is a sizeable topic in itself, but is nicely covered by the SubmittingPatches file in the kernel source tree.

The main things to note are:

  1. Include [PATCH NN/MM] in the email subject
  2. If this is a revision of a previous series of patches, do e.g. [PATCH NN/MM v2]
  3. The patch should be in the body of the email, not a MIME attachment
  4. A marker line containg --- separates the commit message from the diff

The best thing is to just use git's send-email command:

$> git send-email --compose --to rhev-patches@redhat.com 00*.patch


Note, send-email works on Windows too, see these instructions for configuring it.

Instructions For Specific Clients

The kernel's Documentation/email-clients.txt is pretty comprehensive.

Outlook

Don't use it!

Alternatively, try this QuoteFix Macro.

Zimbra

It looks like the Zimbra email composer just can't handle these guidelines.

You can get close with "When replying to an email: Include original message" and "use prefix >", but it's still not good enough. Even with those settings, Zimbra doesn't allow you do nice attribution lines and it line-wraps quoted text.

Honestly, it looks like a lost cause. Use a proper email client like Thunderbird for most of your work.

Thunderbird

To configure it to send plain-text email, go to Accounts, Composition & Addressing and uncheck "Compose messages in HTML format".

You should also disable text/plain; format=flowed or you'll see line wrapping issues. Go to Preferences, Advanced, Config Editor and disable mailnews.send_plaintext_flowed.

Or you can just install the Asalted Patches add-on. "Stops your patches from being assaulted".

Evolution

To configure it to send plain-text email, go to Preferences, Composer Preferences and unset "Format messages in HTML". Also, set reply style to "Quoted". In Mail Preferences, set Plain Text Mode to Prefer PLAIN.

Kmail

Rumour has it that it "just works fine by default". HTML formatting can be enabled globally or per recipeint. Line wrap can be customized in "Configure Kmail > Composer > General"

pine

Is this still common? I dunno, but it should work fine.

Apparently it's a good idea to set the "quell-flowed-text" feature.

mutt

If you're using mutt, you probably know all this already.

References

  1. Wikipedia
  2. LKML FAQ
  3. Fedora guidelines
  4. OpenSUSE guidelines
  5. Instructions for configuring git send-email on Windows
  6. SubmittingPatches
  7. email-clients.txt
  8. An example of a mailing list thread.