CONTRIBUTING.md

   1 # Contributing to ccache
   2
   3 Want to contribute to ccache? Awesome!
   4
   5 ## Asking a question?
   6
   7 There are several options:
   8
   9 1. Ask a question in the [issue
  10    tracker](https://github.com/ccache/ccache/issues/new/choose).
  11 2. Post your question to the [mailing
  12    list](https://lists.samba.org/mailman/listinfo/ccache/).
  13 3. Chat in the [Gitter room](https://gitter.im/ccache/ccache).
  14
  15 ## Reporting an issue?
  16
  17 Please include at least the following information in your bug report:
  18
  19 1. Which version of ccache you use.
  20 2. Which compiler you use, if applicable.
  21 3. Which operating system you use, if applicable.
  22 4. The problematic behavior you experienced (_actual behavior_).
  23 5. How you would like ccache to behave instead (_expected behavior_).
  24 6. Steps to reproduce the problematic behavior.
  25
  26 Also, consider reading [Effective Ways to Get Help from Maintainers](
  27 https://www.snoyman.com/blog/2017/10/effective-ways-help-from-maintainers).
  28
  29 ## Contributing code?
  30
  31 The preferred way is to create one or several pull request with your
  32 proposal(s) on [GitHub](https://github.com/ccache/ccache).
  33
  34 Here are some hints to make the process smoother:
  35
  36 * If you plan to implement major changes it is wise to open an issue on GitHub
  37   (or ask in the Gitter room, or send a mail to the mailing list) asking for
  38   comments on your plans before doing the bulk of the work. That way you can
  39   avoid potentially wasting time on doing something that may need major rework
  40   to be accepted, or maybe doesn't end up being accepted at all.
  41 * Is your pull request "work in progress", i.e. you don't think that it's ready
  42   for merging yet but you want early comments and CI test results? Then create
  43   a draft pull request as described in [this Github blog
  44   post](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
  45 * Please follow the ccache's code style (see the section below).
  46 * Consider [A Note About Git Commit
  47   Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
  48   when writing commit messages.
  49
  50 ## Code style
  51
  52 Ccache was written in C99 until 2019 when it started being converted to C++11.
  53 The conversion is a slow work in progress, which is why there is a lot of
  54 C-style code left. Please refrain from doing large C to C++ conversions; do it
  55 little by little.
  56
  57 Source code formatting is defined by `.clang-format` in the root directory. The
  58 format is loosely based on [LLVM's code formatting
  59 style](https://llvm.org/docs/CodingStandards.html) with some exceptions. It's
  60 highly recommended to install
  61 [Clang-Format](https://clang.llvm.org/docs/ClangFormat.html) 6.0 or newer and
  62 run `make format` to format changes according to ccache's code style. Or even
  63 better: set up your editor to run Clang-Format automatically when saving. If
  64 you don't run Clang-Format then the ccache authors have to do it for you.
  65
  66 Please follow these conventions:
  67
  68 * Use `UpperCamelCase` for types (e.g. classes and structs) and namespaces.
  69 * Use `UPPER_CASE` names for macros and (non-class )enum values.
  70 * Use `snake_case` for other names (functions, variables, enum class values, etc.).
  71 * Use an `m_` prefix for non-public member variables.
  72 * Use a `g_` prefix for global mutable variables.
  73 * Use a `k_` prefix for global constants.
  74 * Always use curly braces around if/for/while/do bodies, even if they only
  75   contain one statement.