Evolution Patch Guidelines

This document lists some guidelines for writing a good patch which is more likely to be accepted.

Any new features or large scale work should first be discussed on the evolution-hackers list first. This will ensure the idea fits in the direction we wish to take Evolution, and also that the effort is not duplicated. See details on the mailing lists below.

Patch Basics

• The patch must apply cleanly at the time it is made.
• It must compile once applied.
• It should not generate any more compile time warnings than were already there. This may be platform dependent, so simply do your best on this one.
• It must conform to the C89/C90 standard (ANSI/ISO C), and build with gcc using the default compile flags. The trick here is that that in C99 you may define variables anywhere in the code, in C89 they must be declared in a declaration block which follows any block start '{'.
  • Note: If you wish to ensure the code is C89, follow these tips from the gcc manual page:

    To select this standard in GCC, use one of the options '-ansi', '-std=c89' or '-std=iso9899:1990'; to obtain all the diagnostics required by the standard, you should also specify '-pedantic'

    
    You may actually have to use '-std=gnu89' if libraries have taken advantage of gcc extensions and where not compiled similarly, as the above options will disable all GNU extensions.
• Your patch should not add any extra debug printing unless absolutely necessary. If you need to add debugging printing, consider submitting a seperate patch just to add that output.
• Do not use any gcc extensions, except where they are properly checked for and not used with other compilers. The glib library provides some of these features as portable macros and should be used when they cover the required functionality.

GUI Changes

If the change requires non-trivial user interface changes, then they will have to be discussed and approved on the evolution-hackers list first. This is highly recommended before embarking on any UI work, or large scale work in general. The GNOME Human Interface Guidelings (HIG) document is the place to start on any UI changes or additions.

Translated String Changes

Any changes to translated strings in a stable release must be discussed on the hackers list (see mailing lists), and/or as part of the patch submission. There must be very good reasons for changing the strings in this case, because they have already been translated once and we don't want to make the translators translate things all over again.

Coding style

Generally the coding style employed matches the "Linux Kernel" style. In other words, we use what is essentially a K&R style indenting with 8 space tabs. Tabs should be used rather than space characters. Do not submit patches which merely reformat otherwise unchanged code. To prevent your editor from doing that accidentally, turn off the automatic reformatting features in your editor.

K&R style indenting puts braces on the same line with code, not on their own. The opening parenthesis of a function call or conditional statement should be on the same line as the function. These items should always appear on lines by themselves:

• else
• } else
• } else {

A single blank line should follow { } blocks (if not immediately followed by the close of another block), and conditional statements, and be used to separate logical groups of statements in the same block.

A single blank line should separate functions and other structures at the top level of the file (i.e. outside functions). The same rule applies to variable declarations at the start of a block.

An example of the most-developer-preferred formatting:

TheType
the_function (int frank)
{
        int a = 1;

        if (a == frank) {
                a = foo (a);
        } else {
                do {
                        a = bob (frank) + a;
                } until (a == frank);

                frank = a;
        }

        return (TheType) a;
}

Where there are slight stylistic differences, the style in the surrounding code should be followed. These are guidelines; use your own best judgement.

Object Casts

Use GObject style casts for GObject instances, which provides extra safety checks over C style casts.

For example:

GtkWidget *widget = (GtkWidget *) button;  /* unsafe */
GtkWidget *widget = GTK_WIDGET (button);   /* preferred */

Preconditions

External api entry points should have preconditions (g_return_if_fail, etc), although their use varies from case to case. Internal entry points and/or when you are guaranteed the type has already been checked, are unecessary. Object initialisation and other virtual method invocations are considered internal entry points.

Line Lengths

Do not expend effort or resort to unreadable formatting merely to fit long lines into 80 columns. We use 8 space tabs, and because of the lack of namespacing other than extending the function name, many of the function and type names are too long for this to be practical. We're not stuck on VT100 terminals any more.

On the other hand, lines should generally not exceed 100 characters, and absolutely not exceed 160 characters. Very deep tab nesting may point to a flawed code design rather than a formatting issue.

Design

This is a tricky issue to document, but the design of new code should 'fit' with the existing design of the relevent module. It should at the very least, be no worse.

Code should not cross existing abstraction boundaries or attempt to remove or work around them, if required the existing design may need adjustment.

Type and method names should follow the existing practice in the surrounding code. Method arguments should follow the same order as related methods, and should use the same names for matching parameters.

Per file, static class globals are ok, true globals may be ok, but should be used sparingly. Use 'ii' for a loop variable, if that's all it is, don't use 'the_current_index'. etc.

If in doubt, ask on the lists.

Patch Submission Process

Patches should be submitted to our bug tracking system at bugzilla.gnome.org.

Note that the evolution-patches mailing list is no longer used since we've found that patches are easier to track and discuss in Bugzilla.

Historically, the Evolution project required the copyright on all non-trivial patches to be assigned to Novell. As of July 2008, this is no longer required. See this announcement for details.

Copyright © 2008-2012 The Evolution Team
Copyright © 2004-2008 Novell Inc.