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