1# Contributing to Lepton
2
3Thank you for your interest in helping to make Lepton better!  There
4are many ways that you can make a difference.
5
6If you have any questions, you can jump into the Lepton [Gitter
7channel](https://gitter.im/Lepton-EDA/Lobby) or get in touch via the
8[geda-user mailing list](http://www.delorie.com/listserv/).
9
10Please remember that all contributors are expected to follow our [Code
11of Conduct](CODE_OF_CONDUCT.md).
12
13## Bug reports
14
15Bugs are unfortunate, but they happen sometimes.  We can't fix a bug
16if we don't know about it, so please report any bug you come across.
17Please feel free to file bug even if you're not sure if the behaviour
18you're seeing is actually a bug or not.
19
20If you have the chance, before reporting a bug, please [search
21existing
22issues](https://github.com/lepton-eda/lepton-eda/search?utf8=%E2%9C%93&q=&type=Issues),
23because someone else may have already reported your error.  Sometimes
24it's hard to know exactly what to search for, and sometimes the search
25doesn't show relevant results, so we don't mind if you accidentally
26file a duplicate report.
27
28You can open a new issue by following [this
29link](https://github.com/lepton-eda/lepton-eda/issues/new) and filling
30in the fields.  A bug report might look something like the following
31template, but it's okay not to follow it exactly:
32
33    <short summary of the bug>
34
35    I was trying to do this:
36
37    <description of what you were doing when the problem occurred>
38
39    I expected to see this happen: <explanation>
40
41    Instead, this happened: <explanation>
42
43    I am running this version of Lepton:
44
45    <put the output of running `lepton-cli --version` here>
46
47    Here is the related log output:
48    ...
49
50The most important things to include are: 1) what you did, 2) what
51you expected, and 3) what happened instead.  Please include the
52output of `lepton-cli --version`, which includes important
53information about exactly what version of Lepton you are using.
54
55Sometimes, there are log messages that are related to the problem;
56including them in your report is very helpful.
57Log files can be found in the `$XDG_CACHE_HOME/lepton-eda/logs/`
58directory (`$XDG_CACHE_HOME` usually expands to `$HOME/.cache`).
59
60## Pull Requests
61
62Pull requests are the main way that changes to Lepton are accepted.
63GitHub has some [detailed
64documentation](https://help.github.com/articles/about-pull-requests)
65on the use of Pull Requests.
66
67Please make pull requests against the `master` branch.
68
69Before opening a pull request, please make sure that `make distcheck`
70is successful with your changes.  This `make` target will create
71release tarball, compile Lepton from the release tarball, run all
72tests, and make sure that Lepton can be cleanly installed and
73uninstalled.  It takes a long time to run; during normal development,
74`make check` will run almost all of the tests.
75
76All pull requests are reviewed by another person.  Most proposed
77changes Lepton will require some revisions before they're accepted.
78The feedback left by reviewers is intended to make sure that Lepton
79continues to be high quality, stable and reliable software for all its
80users.
81
82## Tips for successful pull requests
83
84Some general suggestions:
85
86- If your changes are extensive, try to split them up into a series of
87  small, logical steps, and use a separate git commit for each
88
89- Write [clear, explanatory commit
90  messages](https://chris.beams.io/posts/git-commit/)
91
92- Provide updated tests and documentation
93
94- Do not leave trailing spaces in edited files
95
96When writing C code:
97
98- Do not use C++-style comments `// ...`; use C-style `/* ... */`
99  comments instead.
100
101- Avoid using macros for definition of function names, they
102  obfuscate the code and make git-grepping over it harder for the
103  developers.
104
105- This set of options to GNU `indent` approximates the lepton-eda C
106  indentation style: (note the `-nut` option, which disables
107  the use of tab characters: please use spaces for code indentation)
108
109      -br -blf -bls -cdw -ce -cs -ts2 -sc -nut -bap -pcs -psl -lp l80 -bbo
110
111When writing Scheme code:
112
113- When you need to iterate over a list, it's often clearer to use
114  [`map`, `for-each`](http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_idx_558)
115  or [SRFI-1 `fold`](http://www.gnu.org/software/guile/manual/html_node/SRFI_002d1-Fold-and-Map.html#index-fold-3609)
116  than to use a recursive function.
117
118- Predicate functions, i.e. functions that test something, should have
119  names ending in `?`, e.g. `object?`; destructive functions, that
120  modify one of their arguments or global state, should have names
121  ending in `!`, e.g. `set-config!`.
122  When implementing such a functions in `C`, please follow the naming
123  convention: for Scheme names with `?`, corresponding C functions'
124  names should have `_p` suffix (e.g. `object_p`), for Scheme names with
125  `!` - `_x` suffix (e.g. `set_config_x`).
126
127- When defining a function please use the
128  ["implicit `define`" form](http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-8.html#%_sec_5.2):
129
130      (define (<name> <formals>) <body>)
131
132- Code that uses `format` to format strings is usually a lot clearer
133  than a `string-append`, `display` and `newline`.  You can always use
134  the [Guile `(ice-9 format)` library](http://www.gnu.org/software/guile/manual/html_node/Writing.html#index-simple_002dformat-2052).
135
136When writing Makefile code:
137
138- Do not use `$<` ("implied source") variable in explicit rules.
139  In implementations of `make` other than GNU, it may be defined only
140  in implicit (i.e. suffix-transformation) rules.
141
142- When defining a makefile variable that contain a long list of files,
143put each file name on its own line.
144