| 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 |
| 46 |
review takes a long time, we may ask you to rebase on a more recent commit |
| 47 |
on the *main* branch, but please don't do that 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 |
PRs need to have a one-line summary in the *PR description*. This information |
| 57 |
is used to automatically generate release notes. If you got here after creating |
| 58 |
the PR, you need to go to the *PR description* (shown as the first "comment" on |
| 59 |
the PR, made by yourself) and *edit* that description. Editing a PR will |
| 60 |
trigger the "ChangeLog" status to be updated. |
| 61 |
|
| 62 |
For the summary itself, follow this style: |
| 63 |
|
| 64 |
``` |
| 65 |
ChangeLog: Foo plugin: A specific issue people had has been fixed. |
| 66 |
``` |
| 67 |
|
| 68 |
The summary must be on a line of its own, with a "ChangeLog:" prefix at the |
| 69 |
beginning of the line. The text should start with "Foo plugin" to give the |
| 70 |
reader context for the information. Other common contexts are "collectd" for |
| 71 |
the core daemon, "Build system", and "Documentation". Use past tense and |
| 72 |
passive voice the for remainder, e.g. "a bug has been fixed", "a feature has |
| 73 |
been added". |
| 74 |
|
| 75 |
Some PRs should be excluded from the release notes, e.g. changes to project |
| 76 |
internal documentation (such as this file). Those changes are not interesting |
| 77 |
for external users of the project and would reduce the value of the release |
| 78 |
notes. Maintainers may use the `Unlisted Change` label to mark those PRs. |
| 79 |
|
| 80 |
## Other resources |
| 81 |
|
| 82 |
* [Mailing list](http://mailman.verplant.org/listinfo/collectd) |
| 83 |
* [#collectd IRC channel](https://webchat.freenode.net/?channels=#collectd) |
| 84 |
on *freenode*. |
| 85 |
* [Old patch submission guideline](https://collectd.org/wiki/index.php/Submitting_patches) |