HACKING

   1 ==============================================
   2  'gschem and Friends' Electronic Design Suite
   3 ==============================================
   4
   5 Copyright (C) 1998-2011 gEDA Developers
   6
   7 This file contains information which you may find useful if you wish
   8 to contribute to gEDA.
   9
  10 How to submit patches
  11 =====================
  12
  13 Please submit patches to the bug tracker on Launchpad:
  14
  15   <https://bugs.launchpad.net/geda>
  16
  17 Once you've submitted your patches, you may wish to also e-mail the
  18 `gEDA-user' mailing list [1] to announce that you've done so and to ask
  19 for feedback.
  20
  21 To make it easier for developers to promptly verify your patches and
  22 integrate them, please try to follow the following guidelines:
  23
  24   - If your patch is big, try to split it up into a series of small,
  25     logical steps, and use a separate patch for each.
  26
  27   - Avoid unnecessary whitespace changes. Please do not add trailing
  28     whitespace.  If you must make bulk whitespace changes
  29     (e.g. because a file or function is formatted in a way that is
  30     *offensively ugly*) then please do so as a separate patch.
  31
  32   - Ensure that each of your patches applies cleanly against the
  33     `master' branch of the gaf main git repository.
  34
  35   - Please format your patches with `git format-patch' [2], and ensure
  36     that they contain good commit messages.  The commit messages
  37     should include:
  38
  39       * A one-line summary of what the patch changes.
  40
  41       * A detailed explanation of what the patch changes, the problem
  42         it solves, and why you chose that approach to solving the
  43         problem.  Sometimes, the change will be very self-explanatory.
  44         Sometimes, the commit message will be considerably longer than
  45         the patch itself.
  46
  47       * If the patch is related to another bug in the Launchpad
  48         tracker, include its bug number.
  49
  50       * If your patch fixes a regression, and you know which commit
  51         introduced the regression, include the broken commit's ID.
  52
  53     If you don't use `git format-patch' to create your patch, please
  54     include the commands needed to apply it when you submit it.
  55     Assume the reader's current working directory is the top level of
  56     the gEDA/gaf source tree.
  57
  58   - Make sure it's clear whether, and in what ways, you've tested your
  59     patch.
  60
  61   - If you add functions, or change function definitions, make sure
  62     that the doxygen [3] comments are up-to-date.
  63
  64 Sometimes, you may submit a patch and not hear anything back for a
  65 while.  This can be for a number of reasons, and it's only very rarely
  66 that there's a great conspiracy of gEDA developers to obstruct your
  67 changes from getting included.  It might even be that your patch has
  68 been committed, but the developer who did so forgot to let you know!
  69 If it's been more than a couple of weeks since you submitted a patch,
  70 you should e-mail the `gEDA-user' mailing list with a reminder.
  71
  72 A final thought: to get your patches included, make it easy to accept
  73 them!
  74
  75 [1] http://www.seul.org/cgi-bin/mailman/listinfo/geda-user
  76 [2] http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html
  77 [3] http://www.stack.nl/~dimitri/doxygen/
  78
  79 C coding style
  80 ==============
  81
  82 gEDA C coding style is fairly flexible.  However, there are a few requests.
  83
  84   - Indent using spaces only, with an indentation step of two spaces.
  85
  86   - Avoid C++ style comments (`//').
  87
  88   - `switch' statements should always include a `default' label.
  89
  90   - Do not comment out code or omit it using `#if 0', unless
  91     absolutely necessary for documentation purposes.  If code is not
  92     needed, delete it.
  93
  94   - Wrap code at 80 columns.
  95
  96   - Wrap the body of an `if' statement in braces `{}', even if the
  97     body only contains one statement.
  98
  99   - When checking a pointer for validity, explicitly compare it with
 100     `NULL'.
 101
 102        if (ptr == NULL) { return; } /* Good */
 103        if (!ptr) { return; }        /* Bad */
 104
 105 Obviously, all these rules are made to be broken, and it'll be obvious
 106 when it's appropriate to do so. ;-)
 107
 108 Here is a set of options to GNU `indent' which approximates the gEDA
 109 indentation style:
 110
 111   -br -blf -bls -cdw -ce -cs -ts2 -sc -nut -bap -pcs -psl -lp l80 -bbo
 112
 113 Scheme coding style
 114 ===================
 115
 116 gEDA Scheme coding style is also fairly flexible.  Once again, though,
 117 there are a few things to bear in mind!
 118
 119   - When you need to iterate over a list, it's often better to use
 120     `map', `for-each' or SRFI-1 `fold' than to make your function
 121     recursive [1][2].
 122
 123   - Predicate functions should have names ending in `?', and
 124     destructive functions should have names ending in `!'.
 125
 126   - When defining a function, please use the "implicit define" form of
 127     `define' [3]:
 128
 129     (define (<name> <formals>) <body>)
 130
 131   - It's often clearer to use `format' to format strings rather than
 132     using a combination of `string-append', `display' and `newline'.
 133     This function is always available in Guile 1.8.x [4].
 134
 135 [1] http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_idx_558
 136 [2] http://www.gnu.org/software/guile/manual/html_node/SRFI_002d1-Fold-and-Map.html#index-fold-3609
 137 [3] http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-8.html#%_sec_5.2
 138 [4] http://www.gnu.org/software/guile/manual/html_node/Writing.html#index-simple_002dformat-2052