4.2. Some notes about style

There are a few conventions about coding style that have been adopted over the years of development. The rational for these "rules" is explained for each one.

  • No HTML mail, since patches should be in-lined and HTML turns the patch into garbage. Also it is considered bad etiquette as it uglifies the message, and is not viewable by many of the subscribers.

  • Only one change set per patch. Patches should address only one bug/problem at a time. If a lot of changes need to be made then it is preferred to break it into a series of patches. This makes it easier to find regressions.

  • Tabs are not forbidden but discouraged. A tab is defined as 8 characters and the usual amount of indentation is 4 characters.

  • C++ style comments are forbidden since some compilers choke on them.

  • Commenting out a block of code is usually done by using if (0). For example:

    /* note about reason for commenting block */
    if (0) {
    code /* comments */

    The reason for using this method is that it does not require that you edit comments that may be inside the block of code and it makes sure the code gets maintained.

  • Patches should be in-lined (if you can configure your email client to not wrap lines), or attached as plain text attachments so they can be read inline. This may mean some more work for you. However it allows others to review your patch easily and decreases the chances of it being overlooked or forgotten.

  • Code is usually limited to 100 columns. It generally makes code easier to read.

  • If the patch fixes a bug in Bugzilla please provide a link to the bug in the comments of the patch. Also, mark the bug as "resolved fixed" after your patch gets committed.

4.2.1. Inline attachments with Outlook Express

Outlook Express is notorious for mangling attachments. Giving the patch a .txt extension and attaching will solve the problem for most mailers including Outlook. Also, there is a way to enable Outlook Express to send .diff attachments.

You need the following two things to make it work.

  1. Make sure that .diff files have "\r\n" line endings, because if OE detects that there are none it switches to quoted-printable format attachments.

  2. Using regedit add key Content Type with value text/plain to the .diff extension under HKEY_CLASSES_ROOT (same as for .txt extension). This tells OE to use Content-Type: text/plain instead of application/octet-stream.

Item #1 is important. After you hit the Send button, go to Outbox and using Properties verify the message source to make sure that the mail has the correct format. You might want to send several test emails to yourself too.

4.2.2. Alexandre's Bottom Line

"The basic rules are: no attachments, no MIME crap, no line wrapping, a single patch per mail. Basically if I can't do cat raw_mail | patch -p0 it's in the wrong format."