Avoid GNUism '\|' by using extended REs.
[geda-gaf.git] / HACKING
blob1372ca0f4cd72a758966d2feae5d1d4d10cb2e00
1 ==============================================
2  'gschem and Friends' Electronic Design Suite
3 ==============================================
5 Copyright (C) 1998-2020 gEDA Developers
7 This file contains information which you may find useful if you wish
8 to contribute to gEDA.
10 How to submit patches
11 =====================
13 Please submit patches to the bug tracker on Launchpad:
15   <https://bugs.launchpad.net/geda>
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.
21 To make it easier for developers to promptly verify your patches and
22 integrate them, please try to follow the following guidelines:
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.
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.
32   - Ensure that each of your patches applies cleanly against the
33     `master' branch of the geda-gaf main git repository.
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:
39       * A one-line summary of what the patch changes.
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.
47       * If the patch is related to another bug in the Launchpad
48         tracker, include its bug number.
50       * If your patch fixes a regression, and you know which commit
51         introduced the regression, include the broken commit's ID.
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.
58   - Make sure it's clear whether, and in what ways, you've tested your
59     patch.
61   - If you add functions, or change function definitions, make sure
62     that the doxygen [3] comments are up-to-date.
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.
72 A final thought: to get your patches included, make it easy to accept
73 them!
75 [1] http://www.delorie.com/listserv/
76 [2] http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html
77 [3] http://www.stack.nl/~dimitri/doxygen/
79 C coding style
80 ==============
82 gEDA C coding style is fairly flexible.  However, there are a few requests.
84   - Indent using spaces only, with an indentation step of two spaces.
86   - Avoid C++ style comments (`//').
88   - `switch' statements should always include a `default' label.
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.
94   - Wrap code at 80 columns.
96   - Wrap the body of an `if' statement in braces `{}', even if the
97     body only contains one statement.
99   - When checking a pointer for validity, explicitly compare it with
100     `NULL'.
102        if (ptr == NULL) { return; } /* Good */
103        if (!ptr) { return; }        /* Bad */
105 Obviously, all these rules are made to be broken, and it'll be obvious
106 when it's appropriate to do so. ;-)
108 Here is a set of options to GNU `indent' which approximates the gEDA
109 indentation style:
111   -br -blf -bls -cdw -ce -cs -ts2 -sc -nut -bap -pcs -psl -lp l80 -bbo
113 Scheme coding style
114 ===================
116 gEDA Scheme coding style is also fairly flexible.  Once again, though,
117 there are a few things to bear in mind!
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].
123   - Predicate functions should have names ending in `?', and
124     destructive functions should have names ending in `!'.
126   - When defining a function, please use the "implicit define" form of
127     `define' [3]:
129     (define (<name> <formals>) <body>)
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].
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