Wrote one.

2003-08-21  Not Zed  <NotZed@Ximian.com>

        * HACKING: Wrote one.

svn path=/trunk/; revision=22328

1 files changed, 279 insertions, 0 deletions

diff --git a/HACKING b/HACKING
index e69de29bb2..a975183e28 100644
--- a/HACKING
+++ b/HACKING
@@ -0,0 +1,279 @@
+
+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.  The list is specifically for the review of patches and subject
+lines such as these will lead to your patch submissions being ignored
+and/or simply forgotten.
+
+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.