4 This section lists some guidelines for writing a good patch which is
5 more likely to be accepted.
7 Any new features or large scale work should first be discussed on the
8 evolution-hackers list first. This will ensure the idea fits in the
9 direction we wish to take Evolution, and also that the effort is not
10 duplicated. See section 3 for details on the mailing lists.
14 o The patch should apply cleanly at the time it is made.
16 o It must compile once applied.
18 o It must not generate any more compile time warnings than were
19 already there. This may be platform dependent so simply do your
22 o It must conform to C89/C90 (ANSI/ISO C), and build with gcc using
23 the default compile flags.
25 The primary trap is that in C99 you may define variables anywhere in
26 the code, in C89 they must be declared in a declaration block which
27 follows any block start '{'.
29 If you wish to ensure the code is C89, try the following.
31 From the gcc manual page:
33 this standard in GCC, use one of the options `-ansi', `-std=c89' or
34 `-std=iso9899:1990'; to obtain all the diagnostics required by the
35 standard, you should also specify `-pedantic'" ...
37 You may actually have to use '-std=gnu89' if libraries have taken
38 advantage of gcc extensions and where not compiled similarly, as the
39 above options will disable all gnu extensions.
41 [FIXME: Add the same option for Forte here]
43 o It should not add any extra debug printing by default, unless the
44 patch is specifically to add extra debug printing.
46 o It should not use any gcc extensions, except where they are properly
47 checked for and not used with other compilers. glib provides some
48 of these features as portable macros and should be used when they
49 cover the required functionality.
53 If the change requires non-trivial user interface changes, then they
54 will have to be discussed and approved on the evolution-hackers list
55 first. This is highly recommended before embarking on any UI work, or
56 large scale work in general. The Gnome HIG document is the place to
57 start on any UI changes or additions.
59 1.2 Translated string changes
61 Any changes to translated strings in a stable release must be
62 discussed on the hackers list (see section 3), and/or as part of the
63 patch submission. There must be very good reasons for changing the
68 Generally the coding style employed matches the "Linux Kernel" style,
69 that is, basically K&R style indenting with 8 space tabs. Tabs should
70 be used rather than space characters. Reformatting of otherwise
71 unchanged code is not acceptable. Editors should have any automatic
72 reformatting features disabled.
74 K&R style indenting puts braces on the same line. The opening
75 parenthesis of a function call or conditional statement should be on
76 the same line as the function. "else" "} else" and "} else {" must
77 always occur on lines by themselves.
79 A single blank line should follow {} blocks (if not immediately
80 followed by the close of another block), and conditional statements,
81 and be used to separate logical groups of statements in the same
84 A single blank line only should separate functions, and other
85 structures at the top level of the file (i.e. outside functions). The
86 same rule applies to variable declarations at the start of a block.
88 An example of the most-developer-preferred formatting:
91 the_function (int frank)
100 } until (a == frank);
108 Where there are slight stylistic differences, the style in the
109 surrounding code should be followed.
113 You can either use C style casts, or Gtk style casts. Note that Gtk
114 style casts can add significant execution overhead, which is not
115 adding any extra checking. e.g. if arguments have already been
116 type-checked by preconditions. Putting a space between a cast and a
117 variable is optional, but preferred by most of the developers.
121 External api entry points should have preconditions (g_return_if_fail,
122 etc), although their use varies from case to case. Internal entry
123 points and/or when you are guaranteed the type has already been
124 checked, are unecessary. Object initialisation and other virtual
125 method invocations are considered internal entry points.
129 Do not expend effort and resort to unreadable formatting merely to fit
130 any long lines into 80 column widths. We use 8 space tabs, and
131 because of the lack of namespacing other than extending the function
132 name, many of the function and type names are too long for this to be
133 practical. We now all uses high resolution displays, and not
134 circa-80's VT100 terminals!
136 On the other hand, lines should generally not exceed 100 characters,
137 and absolutely not exceed 160 characters. If your tab nesting is too
138 deep you probably have a poor design that needs rethinking.
142 This is a tricky issue to document, but the design of new code should
143 `fit' with the existing design of the relevent module. It should at
144 the very least, be no worse.
146 Code should not cross existing abstraction boundaries or attempt
147 to remove or work around them, if required the existing design may
150 Type and method names should follow the existing practice in the
151 surrounding code. Method arguments should follow the same order as
152 related methods, and should use the same names for matching
155 Per file, static class globals are ok, true globals may be ok, but
156 should be used sparingly. Use 'i' for a loop variable, if that's all
157 it is, don't use 'the_current_index'. etc.
159 If in doubt, ask on the lists.
161 2. Patch submission guidelines
163 This section outlines procedures that should be followed when
164 submitting patches to evolution, via the evolution-patches mailing
167 You must subcribe to the list at
168 `http://lists.ximian.com/mailman/listinfo/evolution-patches' before you
169 can submit patches to it.
171 Also note that if you attach a patch to a bug report, it should always
172 be sent to the list for attention.
174 Any non-trival patches (patches of more than 1 or 2 changed lines in
175 more than 5 isolated locations) also require copyright assignment.
176 See http://developer.ximian.com/projects/evolution/copyright.html for
179 If you follow the guidelines listed here, you should generally expect
180 a response within 2 working days. If you re-send the same patch
181 repeatedly, you will more likely receive less attention. Do not
182 re-send the same patch repeatedly.
186 If the patch addresses a specific bug in bugzilla.ximian.com, then the
187 bug number must be included in the subject line, preferably near the
188 beginning of the subject line. A concise summary of the bug(s) being
189 addressed, should be the remainder of the subject.
191 It is unnecessary to add "[PATCH]", "patch" or similar to the subject
192 line, unless it is being cross-posted to other non-patch lists.
194 It is absolutely unnecessary to add "please consider", "please review",
195 or "seeking review", or similar, to the subject line. Please do not do
198 Where the patch does not address a specific bug number, then the subject
199 line should simply be a concise summary of the problem/feature it
202 In all cases the subject line should include the module(s) to which the
203 patch applies, and would generally match the component on the bug or
204 the top-level module directory (e.g. camel, mail, addressbook, use 'all'
205 for more than 3 or 4 modules).
209 Patches should be attached as attachments, preferably as a single
210 diff, when possible, and the changes are related. The diff must be in
211 unified diff format, "-up" is a suitable argument to give to "cvs
212 diff" (-p may be dropped if not supported by your diff). If you have
213 added files, then -N should also be used, but if you are using cvs,
214 "cvs add" is needed, and requires write access to the repository.
216 If the patch does not address a specific bug, then the patch email
217 should describe which feature or problem it addresses. If it does
218 address a specific bug, then further explanation beyond the bug
219 commentary is optional, although often convenient.
221 It would also be helpful to summarise the module to which it applies
224 In all cases you should include which branch, or branches, the patch
225 is intended to apply to. If this is not given it will be assumed to
226 be the trunk (HEAD), and such patches will and must not be applied to
227 any stable branch without further approval.
231 All patches must include appropriate ChangeLog diff's, to the
232 appropriate ChangeLog(s) for the given change (emacs will automatically
233 find the correct one, and format the entry appropriately). All but
234 the most trivial of patches will not be considered or discussed
235 without this. It is ok to contain extra ChangeLog entries for other
236 pending patches, but they should not be excessively long - it isn't
237 that hard to isolate patch diffs. If the patch addresses a bug in
238 bugzilla.ximian.com, then the ChangeLog entry must include some
239 reference to that bug number (either the number, or #number, or 'bug
240 xxx'). If it addresses a bug in another bug system, it must also
241 indicate which bug system ('gnome bugzilla' 'red-hat bugzilla', etc).
245 Generally, any patch to the stable branch from non-core developers
246 must address a specific bug in bugzilla.ximian.com. The patch should
247 also be attached to the bug in question, with the keyword 'patch' set
248 on the bug report. The patch email must identify which stable branch
249 and version it is to apply to.
253 3.1 Evolution Hackers
255 If you wish to discuss patches before they are submitted, or ideas
256 before you start to work on them, do it on the evolution-hackers list,
257 which may be subscribed and viewed at
258 `http://lists.ximian.com/mailman/listinfo/evolution-hackers'.
260 This is a low-volume list (5-10 posts per day on average).
262 Some patches may be discussed here to get a wider audience, although
263 once a patch has been made it should generally be discussed on
266 Feature requests, bug reports, and other user related discussions,
267 without the intention to write code to address them, will be ignored.
269 3.2 Evolution Patches
271 The patch submission list evolution-patches may be subscribed and
273 `http://lists.ximian.com/mailman/listinfo/evolution-patches'. Once a
274 patch has been written, it may be submitted here for discussion, as
275 well as final approval.
277 Any non-patch related postings to this list will be ignored.