Difference between revisions of "MailingListEtiquette"
(→Changing Subject) |
(→gmail) |
||
(8 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
− | + | ||
= Mailing List Etiquette = | = 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. | 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 = | + | === Subjects === |
+ | |||
+ | Per the mailing list you are sending out, add <code><nowiki>[mailing-list name]</nowiki></code> then a specific <code><nowiki>[project]</nowiki></code>. For instance, if you are sending to openstack-dev and you want to talk about nova, your subject would be <code><nowiki>[openstack-dev][nova] Nova should be renamed Avon instead!</nowiki></code>. | ||
+ | |||
+ | == Formatting == | ||
− | == Plain Text == | + | === 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. | 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. | ||
Line 12: | Line 16: | ||
If you do send HTML email (please don't), at least configure your client to include a plain text alternative as an attachment. | 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 == | + | === 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. | 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. | ||
Line 18: | Line 22: | ||
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. | 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 == | + | === Replies === |
We use the [http://en.wikipedia.org/wiki/Posting_style#Interleaved_style interleaved] style of replies. You place your replies to specific points directly under those points in the quoted text. | We use the [http://en.wikipedia.org/wiki/Posting_style#Interleaved_style interleaved] style of replies. You place your replies to specific points directly under those points in the quoted text. | ||
Line 32: | Line 36: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | == Reply Level Indication == | + | === Reply Level Indication === |
When quoting previous emails in our replies, we use <code><nowiki>> </nowiki></code> to differentiate the quoted text from our email. You can have multiple [http://en.wikipedia.org/wiki/Posting_style#Reply_level_indication levels of replies] indented like this. | When quoting previous emails in our replies, we use <code><nowiki>> </nowiki></code> to differentiate the quoted text from our email. You can have multiple [http://en.wikipedia.org/wiki/Posting_style#Reply_level_indication levels of replies] indented like this. | ||
Line 46: | Line 50: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | == Attribution Lines == | + | === Attribution Lines === |
Quoted text should also be preceeded by an [http://en.wikipedia.org/wiki/Posting_style#Attribution_lines attribution line]. | Quoted text should also be preceeded by an [http://en.wikipedia.org/wiki/Posting_style#Attribution_lines attribution line]. | ||
Line 66: | Line 70: | ||
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. | 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 == | + | === Trimming === |
You don't need to quote all of an email in order to respond to one specific point. Rather than doing: | You don't need to quote all of an email in order to respond to one specific point. Rather than doing: | ||
Line 110: | Line 114: | ||
However, don't go overboard with trimming. Retain any context that might be useful to people joining the thread later. | However, don't go overboard with trimming. Retain any context that might be useful to people joining the thread later. | ||
− | == Threading == | + | === Threading === |
Email clients insert a <code><nowiki>Message-ID:</nowiki></code> header and when you reply to an email, that email's ID will be included in the <code><nowiki>In-Reply-To:</nowiki></code> header of your response. This allows email clients to display the thread like this: | Email clients insert a <code><nowiki>Message-ID:</nowiki></code> header and when you reply to an email, that email's ID will be included in the <code><nowiki>In-Reply-To:</nowiki></code> header of your response. This allows email clients to display the thread like this: | ||
Line 148: | Line 152: | ||
This drives people crazy! Please make sure you avoid both problems. | This drives people crazy! Please make sure you avoid both problems. | ||
− | == Changing Subject == | + | === 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: | 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: | ||
Line 160: | Line 164: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | = Netiquette = | + | == Netiquette == |
− | The threading section above dips into a topic known as 'netiquette'. | + | The threading section above dips into a topic known as 'netiquette'. For example, it is considered bad form (i.e. bad etiquette) to hijack a thread, or to format your emails in some strange way. |
− | This is a large topic, but | + | This is a large topic, but let's try and cover the most important and relevant items. |
− | == Keep Discussions On-List == | + | === Avoid cross-posting === |
+ | |||
+ | ''Cross-posting'' is the action of posting the same message to several mailing-lists at the same time. While it may sound like a great way to reach a wider audience, it creates problems with replies, as not everyone will be able to post their reply back to every mailing-list you posted to. This results in cross-hatched threads, where some replies are missing depending on the mailing-list you're trying to follow the discussion to. | ||
+ | |||
+ | Alternate solutions include choosing a main mailing-list for your message and posting separate pointers to that discussion on other mailing-lists, asking to reply to the thread there if interested. Or post separate messages on each mailing-list, to create separate threads. | ||
+ | |||
+ | |||
+ | === 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. | When replying to a discussion, or starting a new discussion, your instinct should be to have that discussion on the appropriate mailing list. | ||
Line 178: | Line 189: | ||
Yes, sometimes it's not appropriate to discussion something on a mailing list. But this should be the exception, not the rule. | Yes, sometimes it's not appropriate to discussion something on a mailing list. But this should be the exception, not the rule. | ||
− | == Job postings == | + | === Job postings === |
OpenStack-related job postings should be posted to the (free) [http://www.openstack.org/community/jobs OpenStack job board], not the mailing lists. | OpenStack-related job postings should be posted to the (free) [http://www.openstack.org/community/jobs OpenStack job board], not the mailing lists. | ||
− | = | + | === Reviews request === |
− | + | Please don't send review request directly on the mailing list but use other channels like direct email or IRC ping, see Thierry's [http://lists.openstack.org/pipermail/openstack-dev/2013-September/015264.html email] on this : | |
− | + | ''Core reviewers already receive emails about things they should review, and use tools to prioritize their review queue. If you'd like someone in particular to review things, send an email to them or ping them on IRC. If you'd like to get your review prioritized up, chiming in in the corresponding weekly team meeting should be a hundred times more efficient. But sending something which duplicates the automatic email notification is ineffective and creates ML noise (which is a pain for everyone).'' | |
− | |||
− | + | == Instructions For Specific Clients == | |
− | |||
− | |||
− | |||
− | The | + | The kernel's [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/email-clients.txt Documentation/email-clients.txt] is pretty comprehensive. |
− | |||
− | |||
− | |||
− | |||
− | |||
+ | === gmail === | ||
− | + | To use 'Plain text mode': | |
− | + | # Click COMPOSE in your Gmail's left navigation bar (You can also press 'c' if keyboard shortcuts are enabled) | |
+ | # Click the 'More options' downward pointing triangle in the email composition pop-up | ||
+ | # Make sure 'Plain text mode' is checked. | ||
+ | # If 'Plain text mode' does not have a checkmark before it in the menu, click it. (Otherwise, click anywhere in the email's body text to close the 'More options' menu.) | ||
+ | # This setting is persistent, so new emails you compose will also be in 'Plain text mode'. However, if you (for a specific email) set back to 'HTML mode' (this happens automatically if you use some formatting options), that will also be persistent. So, if you send a one off HTML mail, you'll need to remember to go back into 'Plain text mode' following that. | ||
− | + | Note also that gmail wraps plain text messages at 78 characters, but it does not make this wrapping visible in the composer. | |
− | == Outlook == | + | === Outlook === |
Don't use it! | Don't use it! | ||
Line 215: | Line 222: | ||
Alternatively, try this [http://sourceforge.net/apps/mediawiki/macros4outlook/index.php?title=QuoteFix_Macro QuoteFix Macro]. | Alternatively, try this [http://sourceforge.net/apps/mediawiki/macros4outlook/index.php?title=QuoteFix_Macro QuoteFix Macro]. | ||
− | == Zimbra == | + | === Zimbra === |
It looks like the Zimbra email composer just can't handle these guidelines. | It looks like the Zimbra email composer just can't handle these guidelines. | ||
Line 223: | Line 230: | ||
Honestly, it looks like a lost cause. Use a proper email client like Thunderbird for most of your work. | Honestly, it looks like a lost cause. Use a proper email client like Thunderbird for most of your work. | ||
− | == Thunderbird == | + | === Thunderbird === |
To configure it to send plain-text email, go to Accounts, Composition & Addressing and uncheck "Compose messages in HTML format". | To configure it to send plain-text email, go to Accounts, Composition & Addressing and uncheck "Compose messages in HTML format". | ||
− | You should also disable <code><nowiki>text/plain; format=flowed</nowiki></code> or you'll see line wrapping issues. Go to Preferences, Advanced, Config Editor and disable <code><nowiki>mailnews.send_plaintext_flowed</nowiki></code>. | + | You should also disable <code><nowiki>text/plain; format=flowed</nowiki></code> or you'll see line wrapping issues. Go to Preferences, Advanced, Config Editor and disable <code><nowiki>mailnews.send_plaintext_flowed</nowiki></code>. Update: this setting seems to be disabled by default in recent versions of Thunderbird. It's still best to double check! |
Or you can just install the [http://hg.mozilla.org/users/clarkbw_gnome.org/asalted-patches/file/tip/src/readme.txt Asalted Patches add-on]. "Stops your patches from being assaulted". | Or you can just install the [http://hg.mozilla.org/users/clarkbw_gnome.org/asalted-patches/file/tip/src/readme.txt Asalted Patches add-on]. "Stops your patches from being assaulted". | ||
− | == Evolution == | + | === 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. | 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 == | + | === 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" | 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 == | + | === pine === |
Is this still common? I dunno, but it should work fine. | Is this still common? I dunno, but it should work fine. | ||
Line 245: | Line 252: | ||
Apparently it's a good idea to set the "quell-flowed-text" feature. | Apparently it's a good idea to set the "quell-flowed-text" feature. | ||
− | == mutt == | + | === mutt === |
If you're using mutt, you probably know all this already. | If you're using mutt, you probably know all this already. | ||
− | = References = | + | == References == |
# [http://en.wikipedia.org/wiki/Posting_style Wikipedia] | # [http://en.wikipedia.org/wiki/Posting_style Wikipedia] |
Revision as of 14:16, 15 April 2016
Contents
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.
Subjects
Per the mailing list you are sending out, add [mailing-list name]
then a specific [project]
. For instance, if you are sending to openstack-dev and you want to talk about nova, your subject would be [openstack-dev][nova] Nova should be renamed Avon instead!
.
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'. For example, it is considered bad form (i.e. bad etiquette) to hijack a thread, or to format your emails in some strange way.
This is a large topic, but let's try and cover the most important and relevant items.
Avoid cross-posting
Cross-posting is the action of posting the same message to several mailing-lists at the same time. While it may sound like a great way to reach a wider audience, it creates problems with replies, as not everyone will be able to post their reply back to every mailing-list you posted to. This results in cross-hatched threads, where some replies are missing depending on the mailing-list you're trying to follow the discussion to.
Alternate solutions include choosing a main mailing-list for your message and posting separate pointers to that discussion on other mailing-lists, asking to reply to the thread there if interested. Or post separate messages on each mailing-list, to create separate threads.
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.
Reviews request
Please don't send review request directly on the mailing list but use other channels like direct email or IRC ping, see Thierry's email on this :
Core reviewers already receive emails about things they should review, and use tools to prioritize their review queue. If you'd like someone in particular to review things, send an email to them or ping them on IRC. If you'd like to get your review prioritized up, chiming in in the corresponding weekly team meeting should be a hundred times more efficient. But sending something which duplicates the automatic email notification is ineffective and creates ML noise (which is a pain for everyone).
Instructions For Specific Clients
The kernel's Documentation/email-clients.txt is pretty comprehensive.
gmail
To use 'Plain text mode':
- Click COMPOSE in your Gmail's left navigation bar (You can also press 'c' if keyboard shortcuts are enabled)
- Click the 'More options' downward pointing triangle in the email composition pop-up
- Make sure 'Plain text mode' is checked.
- If 'Plain text mode' does not have a checkmark before it in the menu, click it. (Otherwise, click anywhere in the email's body text to close the 'More options' menu.)
- This setting is persistent, so new emails you compose will also be in 'Plain text mode'. However, if you (for a specific email) set back to 'HTML mode' (this happens automatically if you use some formatting options), that will also be persistent. So, if you send a one off HTML mail, you'll need to remember to go back into 'Plain text mode' following that.
Note also that gmail wraps plain text messages at 78 characters, but it does not make this wrapping visible in the composer.
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
. Update: this setting seems to be disabled by default in recent versions of Thunderbird. It's still best to double check!
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.