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 discouraged since some compilers
choke on them.
Commenting out a block of code is usually done by
enclosing it in #if 0 ... #endif
Statements. For example.
/* note about reason for commenting block */
#if 0
code
code /* comments */
code
#endif
The reason for using this method is that it does not
require that you edit comments that may be inside the
block of code.
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 80 columns. This helps prevent
mailers mangling patches by line wrap. Also 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. This will make it
easier for the maintainers of Bugzilla.
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.
Make sure that .diff files have
\r\n line ends, because if OE detects that there is no
\r\n line endings it switches to quoted-printable format
attachments.
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.
"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."
English
Español
