1# Contributing to ccache
2
3Want to contribute to ccache? Awesome!
4
5## Asking a question?
6
7It's OK to ask questions in the issue tracker for now.
8
9However, please consider posting your question to the
10[mailing list](https://lists.samba.org/mailman/listinfo/ccache/) instead, since
11you are more likely to get an answer there.
12
13## Reporting an issue?
14
15Please include at least the following information in your bug report:
16
171. Which version of ccache you use.
182. Which compiler you use, if applicable.
193. Which operating system you use, if applicable.
204. The problematic behavior you experienced (_actual behavior_).
215. How you would like ccache to behave instead (_expected behavior_).
226. Steps to reproduce the problematic behavior.
23
24Also, consider reading [Effective Ways to Get Help from Maintainers](
25https://www.snoyman.com/blog/2017/10/effective-ways-help-from-maintainers).
26
27## Contributing code?
28
29The preferred way is to create one or several pull request with your
30proposal(s) on [GitHub](https://github.com/ccache/ccache).
31
32If you plan to implement major changes it is wise to open an issue on GitHub
33(or send a mail to the mailing list) asking for comments on your plans before
34doing the bulk of the work. That way you can avoid potentially wasting time on
35doing something that might not end up being accepted.
36
37### How to write commit messages
38
39* Write a summary (short description) on the first line.
40* Start the summary with a capital letter. Optional: prefix the short
41  description with a context followed by a colon.
42* The summary should be in imperative mood (see examples below).
43* The summary should not end with a period. It's a title and titles don't end
44  with a period.
45* If a longer description is wanted, add a second line empty and write the
46  longer description on line three and below.
47* Keep lines in the message at most 72 characters wide.
48
49Example 1:
50
51    Hash a delimiter string between parts to separate them
52
53    Previously, "gcc -I-O2 -c file.c" and "gcc -I -O2 -c file.c" would hash
54    to the same sum.
55
56Example 2:
57
58    win32: Add a space between filename and error string in x_fmmap()
59
60See also:
61
62* http://stopwritingramblingcommitmessages.com
63* http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
64* https://github.com/erlang/otp/wiki/Writing-good-commit-messages
65
66### Code style
67
68#### Formatting
69
70* Use tabs for indenting and spaces for aligning C code.
71* Use 4 spaces for indenting other code (and spaces for aligning).
72* Put the opening curly brace on a new line when defining a function, otherwise
73  at the end of the same line.
74* Put no space between function name and the following parenthesis.
75* Put one space between if/switch/for/while/do and opening curly brace.
76* Always use curly braces around if/for/while/do bodies, even if they only
77  contain one statement.
78* If possible, keep lines at most 80 character wide for a 2 character tab
79  width.
80* Use only lowercase names for functions and variables.
81* Use only uppercase names for enum items and (with some exceptions) macros.
82* Don't use typedefs for structs and enums.
83* Use //-style comments.
84
85Tip: Install the tool uncrustify <http://uncrustify.sourceforge.net> and then
86run "make uncrustify" to fix up source code formatting.
87
88#### Idioms
89
90* Declare variables as late as convenient, not necessarily at the beginning of
91  the scope.
92* Use NULL to initialize null pointers.
93* Don't use NULL when comparing pointers.
94* Use format(), x_malloc() and friends instead of checking for memory
95  allocation failure explicitly.
96* Use str_eq() instead of strcmp() when testing for string (in)equality.
97* Consider using str_startswith() instead of strncmp().
98* Use bool, true and false for boolean values.
99* Use tmp_unlink() or x_unlink() instead of unlink().
100* Use x_rename() instead of rename().
101
102#### Other
103
104* Strive to minimize use of global variables.
105* Write test cases for new code.
106