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
  10    [discussions](https://github.com/ccache/ccache/issues/discussions).
  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 * Have a look in `ARCHITECTURE.md` for an overview of the source code tree.
  37 * If you plan to implement major changes it is wise to open an issue on GitHub
  38   (or ask in the Gitter room, or send a mail to the mailing list) asking for
  39   comments on your plans before doing the bulk of the work. That way you can
  40   avoid potentially wasting time on doing something that may need major rework
  41   to be accepted, or maybe doesn't end up being accepted at all.
  42 * Is your pull request "work in progress", i.e. you don't think that it's ready
  43   for merging yet but you want early comments and CI test results? Then create a
  44   draft pull request as described in [this Github blog
  45   post](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
  46 * Please add test cases for your new changes if applicable.
  47 * Please follow the ccache's code style (see the section below).
  48
  49 ## Commit message conventions
  50
  51 It is preferable, but not mandatory, to format commit messages in the spirit of
  52 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). The
  53 commit message subject should look like this:
  54
  55         <type>: <description>
  56         <type>(<scope>): <description>
  57
  58 `<description>` is a succinct description of the change:
  59
  60 * Use the imperative, present tense: "Change", not "Changed" nor "Changes".
  61 * Capitalize the first letter.
  62 * No dot (`.`) at the end.
  63
  64 Here is a summary of types used for ccache:
  65
  66 | Type         | Explanation |
  67 | ------------ | ----------- |
  68 | **build**    | A change of the build system or build configuration. |
  69 | **bump**     | An increase of the version of an external dependency or an update of a bundled third party package. |
  70 | **chore**    | A change that doesn't match any other type. |
  71 | **ci**       | A change of CI scripts or configuration. |
  72 | **docs**     | A change of documentation only. |
  73 | **enhance**  | An enhancement of the code without adding a user-visible feature, for example adding a new utility class to be used by a future feature or refactoring. |
  74 | **feat**     | An addition or improvement of a user-visible feature. |
  75 | **fix**      | A bug fix (not necessarily user-visible). |
  76 | **perf**     | A performance improvement. |
  77 | **refactor** | A restructuring of the existing code without changing its external behavior. |
  78 | **style**    | A change of code style. |
  79 | **test**     | An addition or modification of tests or test framework. |
  80
  81 ## Code style
  82
  83 Source code formatting is defined by `.clang-format` in the root directory. The
  84 format is loosely based on [LLVM's code formatting
  85 style](https://llvm.org/docs/CodingStandards.html) with some exceptions. Run
  86 `make format` (or `ninja format` if you use Ninja) to format changes according
  87 to ccache's code style. Or even better: set up your editor to run
  88 `<ccache-top-dir>/misc/clang-format` (or any other Clang-Format version 10
  89 binary) automatically when saving. Newer Clang-Format versions likely also work
  90 fine.
  91
  92 Please follow these conventions:
  93
  94 * Use `UpperCamelCase` for types (e.g. classes and structs).
  95 * Use `UPPER_CASE` names for macros and (non-class) enum values.
  96 * Use `snake_case` for other names (namespaces, functions, variables, enum class
  97   values, etc.). (Namespaces used to be in `UpperCamelCase`; transition is work
  98   in progress.)
  99 * Use an `m_` prefix for non-public member variables.
 100 * Use a `g_` prefix for global mutable variables.
 101 * Use a `k_` prefix for global constants.
 102 * Always use curly braces around if/for/while/do bodies, even if they only
 103   contain one statement.