diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 224 |
1 files changed, 5 insertions, 219 deletions
@@ -1,195 +1,12 @@ - 1 Patch guidelines -This section 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 section 3 for details on the mailing lists. - -1.1 Patch basics - -o The patch should apply cleanly at the time it is made. - -o It must compile once applied. - -o It must not generate any more compile time warnings than were - already there. This may be platform dependent so simply do your - best. - -o It must conform to C89/C90 (ANSI/ISO C), and build with gcc using - the default compile flags. - - The primary trap is 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 '{'. - - If you wish to ensure the code is C89, try the following. - - 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. - - [FIXME: Add the same option for Forte here] - -o It should not add any extra debug printing by default, unless the - patch is specifically to add extra debug printing. - -o It should not use any gcc extensions, except where they are properly - checked for and not used with other compilers. glib provides some - of these features as portable macros and should be used when they - cover the required functionality. - -o It must include ChangeLog entries in the appropriate ChangeLog for - the file modified. Use emacs, C-4-a will start a properly formatted - ChangeLog entry in the correct ChangeLog file automatically. - -o If it is from a bug report, it must reference the bug number, and if - it isn't in the gnome bugzilla, it must reference the bug system from - whence it came. - -1.1 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 HIG document is the place to -start on any UI changes or additions. - -1.2 Translated string changes - -Any changes to translated strings in a stable release must be -discussed on the hackers list (see section 3), and/or as part of the -patch submission. There must be very good reasons for changing the -strings in this case. - -1.3 Coding style - -Generally the coding style employed matches the "Linux Kernel" style, -that is, basically K&R style indenting with 8 space tabs. Tabs should -be used rather than space characters. Reformatting of otherwise -unchanged code is not acceptable. Editors should have any automatic -reformatting features disabled. - -K&R style indenting puts braces on the same line. The opening -parenthesis of a function call or conditional statement should be on -the same line as the function. "else" "} else" and "} else {" must -always occur on lines by themselves. - -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 only 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; -} +Procedures that should be followed when submitting patches for +Evolution are available on +http://projects.gnome.org/evolution/patch.shtml -Where there are slight stylistic differences, the style in the -surrounding code should be followed. +Further information: -1.3.1 Object casts - -You can either use C style casts, or Gtk style casts. Note that Gtk -style casts can add significant execution overhead, which is not -adding any extra checking. e.g. if arguments have already been -type-checked by preconditions. Putting a space between a cast and a -variable is optional, but preferred by most of the developers. - -1.3.2 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. - -1.3.3 Line lengths - -Do not expend effort and resort to unreadable formatting merely to fit -any long lines into 80 column widths. 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 now all uses high resolution displays, and not -circa-80's VT100 terminals! - -On the other hand, lines should generally not exceed 100 characters, -and absolutely not exceed 160 characters. If your tab nesting is too -deep you probably have a poor design that needs rethinking. - -1.4 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 'i' for a loop variable, if that's all -it is, don't use 'the_current_index'. etc. - -If in doubt, ask on the lists. - -2. Patch submission guidelines - -This section outlines procedures that should be followed when -submitting patches for Evolution. - -The patch must simply be attached to an appropriate, open bug on -bugzilla.gnome.org. - -For discussion of the patch, or to expediate processing of the patch, -an email may be sent to the evolution-patches list. See the mailing -lists section for more information. You may attach patches when -sending to this list for discussion. - -Any non-trival patches (patches of more than 1 or 2 changed lines in -more than 5 isolated locations) also require copyright assignment. -See http://developer.ximian.com/projects/evolution/copyright.html for -details. - -If you follow the guidelines listed here, you should generally expect -a response within 2 working days. If you re-send the same patch -repeatedly, you will more likely receive less attention. Do not -re-send the same patch repeatedly. - -2.1 Subject Lines +1.1 Subject Lines If the patch addresses a specific bug in bugzilla.gnome.org, then the bug number must be included in the subject line, preferably near the @@ -240,34 +57,3 @@ Generally, any patch to the stable branch from non-core developers must address a specific bug in bugzilla.gnome.org. The patch should also be attached to the bug in question. The patch must not be applied until reviewed. - -3 Mailing lists - -3.1 Evolution Hackers - -If you wish to discuss patches before they are submitted, or ideas -before you start to work on them, do it on the evolution-hackers list, -which may be subscribed and viewed at -`http://lists.ximian.com/mailman/listinfo/evolution-hackers'. - -This is a low-volume list (5-10 posts per day on average). - -Some patches may be discussed here to get a wider audience, although -once a patch has been made it should generally be discussed on -evolution-patches. Large posts are blocked, so they should be sent to -the patches list intsead, or reference resources elsewhere. - -Feature requests, bug reports, and other user related discussions, -without the intention to write code to address them, will be ignored. - -3.2 Evolution Patches - -The patch discussion list evolution-patches may be subscribed and -viewed at -`http://lists.ximian.com/mailman/listinfo/evolution-patches'. Once a -patch has been written, it may be submitted here for discussion, as -well as final approval. - -Patches may be sent to this list as attachments for discussion. - -Any non-patch related postings to this list will be ignored. |