CONTRIBUTING.md

   1 Contributing to PowerDNS
   2 ------------------------
   3 Thank you for you interest to contribute to the PowerDNS project. This document
   4 will explain some of the things you need to keep in mind when contributing to
   5 ease the workflow of this.
   6
   7 # Issue Tracker
   8 When you post an issue or feature request to the
   9 [issue tracker](https://github.com/PowerDNS/pdns/issues), make sure this hasn't
  10 been reported before. If there is an open issue, add extra information on this
  11 issue or show that you have the same issue/want this feature by adding a `:+1:`.
  12
  13 If there is no similar issue, feature request or you're not sure, open a new
  14 issue.
  15
  16 ## Filing a Feature Request
  17 When filing a feature request, please use the Feature request template provided.
  18
  19 Please be as elaborate as possible when describing the feature you need. Provide
  20 at least the following information (if they are relevant):
  21
  22 * Use case (what is the 'masterplan' that requires this feature)
  23 * Description of what the feature should do
  24
  25 ## Filing an Issue or Bug
  26 **Note:** if you're planning to file a security bug, look at our
  27 [Security Policy](https://doc.powerdns.com/md/security/) first.
  28
  29 When filing an issue or bug report, make the title of the issue a very short
  30 summary (e.g. "Recursor crash when some-setting is set to 'crash'"). In the
  31 content of the issue, be as detailed as possible. Supply at least the following
  32 information:
  33
  34 * PowerDNS version
  35 * Where you got the software from (e.g. distribution, compiled yourself)
  36 * Operating System and version
  37 * Steps to reproduce: How can we reproduce the issue
  38 * Expected behavior: what did you expect what would happen?
  39 * Observed behavior: what actually happened when following the steps?
  40 * Relevant logs: Please use code blocks (\`\`\`) to format console output, logs, and code as it's very hard to read otherwise.
  41
  42 We provide convenient templates that make it easy to not forget any of these steps.
  43
  44 If you have already looked deeper into the problem, provide what you found as
  45 well.
  46
  47 # Filing a Pull Request
  48 Code contributions are sent as a pull request on [GitHub](https://github.com/PowerDNS/pdns/pulls).
  49 By submitting a Pull Request you agree to your code becoming GPLv2 licensed.
  50
  51 ## Pull Request Guidelines
  52 A pull request, at the least, should have:
  53
  54 * A clear and concise title (not e.g. 'Issue #1234')
  55 * A description of the patch (what issue does it solve or what feature does it add)
  56 * Documentation for the feature or when current behaviour changes
  57 * Regression and/or unit tests
  58
  59 And must:
  60 * Be filed against the master branch before any release branch
  61 * Pass all tests in our CI (currently Github Actions and CircleCI)
  62
  63 Information on the tests can be found in the repository at
  64 [/regression-tests/README.md](https://github.com/PowerDNS/pdns/blob/master/regression-tests/README.md)
  65 ,
  66 [/regression-tests.recursor/README.md](https://github.com/PowerDNS/pdns/blob/master/regression-tests.recursor/README.md),
  67 plus various other directories with `regression-tests.*` names.
  68
  69 ## Commit Guidelines
  70 * Tell why the change does what it does, not how it does it.
  71 * The first line should be short (preferably less than 50 characters)
  72 * The rest of the commit body should be wrapped at 72 characters (see [this](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) for more info)
  73 * If this commit fixes an issue, put "Closes #XXXX" in the message
  74 * Do not put whitespace fixes/cleanup and functionality changes in the same commit
  75
  76 # Coding Guidelines
  77
  78 ## `clang-format`
  79
  80 We have `clang-format` in place, but not for all files yet.
  81 This is an incremental process.
  82 If you're adding new code, adhering to the formatting config is appreciated.
  83 Formatting breakage in already formatted files will be caught by the CI.
  84 To format all files that are supposed to be formatted, run `make format-code` in the root of the tree.
  85
  86 ## Additional guidelines
  87
  88 * Don't have end-of-line whitespace
  89 * Use spaces instead of tabs
  90 * Although the codebase does not consistently have them, [docblock](https://www.doxygen.nl/manual/docblocks.html)s on functions and classes are appreciated
  91 * Never hesitate to write comments on anything that might not be immediately clear just from reading the code
  92 * When adding whole new things, consider putting them in a `pdns::X` namespace. Look for `namespace pdns` in the codebase for examples.
  93
  94 ## Code Checkers
  95
  96 Even though we don't automatically run any of the code checkers listed below as part of our CI, it might make sense to run them manually, not only on newly added code, but to also improve existing code.
  97
  98 ### `clang-tidy`
  99
 100 `clang-tidy` requires a [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html) to work.
 101 See the ["Compilation Database" section of the DEVELOPMENT document](DEVELOPMENT.md#compilation-database) on how to generate a compilation database.
 102
 103 Once the compilation database has been generated, you can pick one of the two available `clang-tidy` configuration files to run checks on source files.
 104 Picking a configuration file is a matter of creating a symbolic link called `.clang-tidy` to said file in the topmost level of the sub-project you're working on (or the toplevel repository directory if you're working on PowerDNS auth).
 105
 106 We provide two configuration files for `clang-tidy`:
 107
 108 1. A minimal [.clang-tidy.bugs](.clang-tidy.bugs) which only enables a few checks for common bugs.
 109    This configuration can be enabled using `ln -sf .clang-tidy.bugs .clang-tidy`.
 110
 111 2. A more complete [.clang-tidy.full](.clang-tidy.full) which enables almost all available checks.
 112    This configuration can be enabled using `ln -sf .clang-tidy.full .clang-tidy` and is recommended for all new code.
 113
 114 # Development Environment
 115
 116 Information about setting up a development environment using a language server like [`clangd`](https://clangd.llvm.org/) or [`ccls`](https://github.com/MaskRay/ccls) can be found in [DEVELOPMENT.md](DEVELOPMENT.md).
 117
 118 # Debugging
 119
 120 ## Using GDB
 121
 122 To get a good debugging experience with `gdb`, it is recommended to build PowerDNS using the following flags:
 123
 124 * `CC` and `CXX` set to `gcc` and `g++`, respectively.
 125 * `CFLAGS` and `CXXFLAGS` set to `-ggdb -Og -fno-inline`.
 126
 127 These variables need to be set during the `configure` step, as follows:
 128
 129 ```sh
 130 export CC=clang CXX=clang++
 131 export CFLAGS="-ggdb -Og -fno-inline" CXXFLAGS="-ggdb -Og -fno-inline"
 132 ./configure --with-modules=gsqlite3 --disable-lua-records --enable-unit-tests
 133 make -j 8
 134 ```
 135
 136 [GDB Dashboard](https://github.com/cyrus-and/gdb-dashboard) can be used to vastly improve the GDB debugging experience.