CONTRIBUTING.md

   1 # Contribution guidelines
   2
   3 Thanks for taking the time to contribute to the [collectd
   4 project](https://collectd.org/)! This document tries to give some guidance to
   5 make the process of contributing to *collectd* as pleasant as possible.
   6
   7 ## Bug reports
   8
   9 Please report bugs as [GitHub
  10 Issues](https://github.com/collectd/collectd/issues). Try to answer the
  11 following questions:
  12
  13 *   Which version of *collectd* are you using?
  14 *   Which operating system (distribution) are you using at which version?
  15 *   What is the expected behavior / output?
  16 *   What is the actual (observed) behavior / output?
  17 *   How can we reproduce the problem you're having?
  18 *   If *collectd* crashes, try to get a
  19     [stack trace](https://collectd.org/wiki/index.php/Core_file).
  20
  21 Please monitor your issue for a couple of days and reply to questions. To keep
  22 the project manageable, we have to do some housekeeping; meaning we will close
  23 issues that have become stale.
  24
  25 ## Code contributions
  26
  27 Please open a [GitHub Pull Request](https://github.com/collectd/collectd/pulls)
  28 (PR) to contribute bug fixes, features, cleanups, new plugins, … Patches sent to
  29 the mailing list have a tendency to fall through the cracks.
  30
  31 *   *Focus:* Fix *one thing* in your PR. The smaller your change, the faster it
  32     will be reviewed and merged.
  33 *   *Coding style:* Please run `clang-format -style=file -i $FILE` after editing
  34     `.c`, `.h` and `.proto` files. If you don't want to install *clang-format*
  35     locally or your version produces a different result than the formatting
  36     check on Github, use `contrib/format.sh` to format files using the same web
  37     service used by our check.
  38 *   *Documentation:* New config options need to be documented in two places: the
  39     manpage (`src/collectd.conf.pod`) and the example config
  40     (`src/collectd.conf.in`). New plugins need to be added to the `README` file.
  41 *   *Continuous integration:* Once your PR is created, our continuous
  42     integration environment will try to build it on a number of platforms. If
  43     this reports a failure, please investigate and fix the problem. We will at
  44     best do a very casual review for failing PRs.
  45 *   *Don't rebase:* Rebasing your branch destroys the review history. If a review
  46     takes a long time, we may ask you to rebase on a more recent *master*, but
  47     please don't do it without being asked.
  48 *   *types.db:* One of the most common mistakes made by new contributors is the
  49     addition of (many) new *types* in the file `src/types.db`. The majority of
  50     usecases can be met with one of the existing entries. If you plan to add new
  51     entries to `src/types.db`, you should talk to us early in the design
  52     process.
  53
  54 ### ChangeLog
  55
  56 All PRs need to have a one-line description in the initial pull request body.
  57 This information is used to automatically generate release notes. Follow this
  58 style:
  59
  60 ```
  61 Foo plugin: A specific issue people had has been fixed.
  62 ```
  63
  64 Start with "Foo plugin" to give the reader context for the information. Other
  65 common prefixes are "collectd" for the core daemon and "Build system". Use past
  66 tense and passive voice the for remainder, e.g. "a bug has been fixed", "a
  67 feature has been added".
  68
  69 Some PRs should not be added to the release notes, e.g. changes to project
  70 internal documentation (such as this file). Those changes are not interesting
  71 for external users of the project and would reduce the value of the release
  72 notes. Maintainers may use the `Unlisted Change` label to mark those PRs.
  73
  74 ## Other resources
  75
  76 *   [Mailing list](http://mailman.verplant.org/listinfo/collectd)
  77 *   [#collectd IRC channel](https://webchat.freenode.net/?channels=#collectd)
  78     on *freenode*.
  79 *   [Old patch submission guideline](https://collectd.org/wiki/index.php/Submitting_patches)