diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 277 |
1 files changed, 0 insertions, 277 deletions
diff --git a/HACKING b/HACKING deleted file mode 100644 index ce31d66dac..0000000000 --- a/HACKING +++ /dev/null @@ -1,277 +0,0 @@ - -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. - -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; -} - -Where there are slight stylistic differences, the style in the -surrounding code should be followed. - -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 to evolution, via the evolution-patches mailing -list. - -You must subcribe to the list at -`http://lists.ximian.com/mailman/listinfo/evolution-patches' before you -can submit patches to it. - -Also note that if you attach a patch to a bug report, it should always -be sent to the list for attention. - -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 - -If the patch addresses a specific bug in bugzilla.ximian.com, then the -bug number must be included in the subject line, preferably near the -beginning of the subject line. A concise summary of the bug(s) being -addressed, should be the remainder of the subject. - -It is unnecessary to add "[PATCH]", "patch" or similar to the subject -line, unless it is being cross-posted to other non-patch lists. - -It is absolutely unnecessary to add "please consider", "please review", -or "seeking review", or similar, to the subject line. Please do not do -this. - -Where the patch does not address a specific bug number, then the subject -line should simply be a concise summary of the problem/feature it -addresses. - -In all cases the subject line should include the module(s) to which the -patch applies, and would generally match the component on the bug or -the top-level module directory (e.g. camel, mail, addressbook, use 'all' -for more than 3 or 4 modules). - -2.2 Message Body - -Patches should be attached as attachments, preferably as a single -diff, when possible, and the changes are related. The diff must be in -unified diff format, "-up" is a suitable argument to give to "cvs -diff" (-p may be dropped if not supported by your diff). If you have -added files, then -N should also be used, but if you are using cvs, -"cvs add" is needed, and requires write access to the repository. - -If the patch does not address a specific bug, then the patch email -should describe which feature or problem it addresses. If it does -address a specific bug, then further explanation beyond the bug -commentary is optional, although often convenient. - -It would also be helpful to summarise the module to which it applies -in the message body. - -In all cases you should include which branch, or branches, the patch -is intended to apply to. If this is not given it will be assumed to -be the trunk (HEAD), and such patches will and must not be applied to -any stable branch without further approval. - -2.3 ChangeLogs - -All patches must include appropriate ChangeLog diff's, to the -appropriate ChangeLog(s) for the given change (emacs will automatically -find the correct one, and format the entry appropriately). All but -the most trivial of patches will not be considered or discussed -without this. It is ok to contain extra ChangeLog entries for other -pending patches, but they should not be excessively long - it isn't -that hard to isolate patch diffs. If the patch addresses a bug in -bugzilla.ximian.com, then the ChangeLog entry must include some -reference to that bug number (either the number, or #number, or 'bug -xxx'). If it addresses a bug in another bug system, it must also -indicate which bug system ('gnome bugzilla' 'red-hat bugzilla', etc). - -2.4 Stable branches - -Generally, any patch to the stable branch from non-core developers -must address a specific bug in bugzilla.ximian.com. The patch should -also be attached to the bug in question, with the keyword 'patch' set -on the bug report. The patch email must identify which stable branch -and version it is to apply to. - -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. - -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 submission 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. - -Any non-patch related postings to this list will be ignored. |