1 # <a id="contributing"></a> Contributing
3 Icinga is is an open source project and lives from your ideas and contributions.
5 There are many ways to contribute, from improving the documentation, submitting
6 bug reports and features requests or writing code to add enhancements or fix bugs.
10 1. [Introduction](#contributing-intro)
11 2. [Fork the Project](#contributing-fork)
12 3. [Branches](#contributing-branches)
13 4. [Commits](#contributing-commits)
14 5. [Pull Requests](#contributing-pull-requests)
15 6. [Testing](#contributing-testing)
16 7. [Source Code Patches](#contributing-patches-source-code)
17 8. [Documentation Patches](#contributing-patches-documentation)
18 9. [Contribute CheckCommand Definitions](#contributing-patches-itl-checkcommands)
20 ## <a id="contributing-intro"></a> Introduction
22 Please consider our [roadmap](https://github.com/Icinga/icinga2/milestones) and
23 [open issues](https://github.com/icinga/icinga2/issues) when you start contributing
26 Before starting your work on Icinga 2, you should [fork the project](https://help.github.com/articles/fork-a-repo/)
27 to your GitHub account. This allows you to freely experiment with your changes.
28 When your changes are complete, submit a [pull request](https://help.github.com/articles/using-pull-requests/).
29 All pull requests will be reviewed and merged if they suit some general guidelines:
31 * Changes are located in a topic branch
32 * For new functionality, proper tests are written
33 * Changes should follow the existing coding style and standards
35 Please continue reading in the following sections for a step by step guide.
37 ## <a id="contributing-fork"></a> Fork the Project
39 [Fork the project](https://help.github.com/articles/fork-a-repo/) to your GitHub account
40 and clone the repository:
43 git clone git@github.com:dnsmichi/icinga2.git
47 Add a new remote `upstream` with this repository as value.
50 git remote add upstream https://github.com/icinga/icinga2.git
53 You can pull updates to your fork's master branch:
57 git pull upstream HEAD
60 Please continue to learn about [branches](CONTRIBUTING.md#contributing-branches).
62 ## <a id="contributing-branches"></a> Branches
64 Choosing a proper name for a branch helps us identify its purpose and possibly
65 find an associated bug or feature.
66 Generally a branch name should include a topic such as `fix` or `feature` followed
67 by a description and an issue number if applicable. Branches should have only changes
68 relevant to a specific issue.
71 git checkout -b fix/service-template-typo-1234
72 git checkout -b feature/config-handling-1235
75 Continue to apply your changes and test them. More details on specific changes:
77 * [Source Code Patches](#contributing-patches-source-code)
78 * [Documentation Patches](#contributing-patches-documentation)
79 * [Contribute CheckCommand Definitions](#contributing-patches-itl-checkcommands)
81 ## <a id="contributing-commits"></a> Commits
83 Once you've finished your work in a branch, please ensure to commit
84 your changes. A good commit message includes a short topic, additional body
85 and a reference to the issue you wish to solve (if existing).
90 Fix problem with notifications in HA cluster
92 There was a race condition when restarting.
100 Add ITL CheckCommand printer
102 Requires the check_printer plugin.
107 You can add multiple commits during your journey to finish your patch.
108 Don't worry, you can squash those changes into a single commit later on.
110 ## <a id="contributing-pull-requests"></a> Pull Requests
112 Once you've commited your changes, please update your local master
113 branch and rebase your fix/feature branch against it before submitting a PR.
117 git pull upstream HEAD
119 git checkout fix/notifications
123 Once you've resolved any conflicts, push the branch to your remote repository.
124 It might be necessary to force push after rebasing - use with care!
128 git push --set-upstream origin fix/notifications
133 git push -f origin fix/notifications
136 You can now either use the [hub](https://hub.github.com) CLI tool to create a PR, or nagivate
137 to your GitHub repository and create a PR there.
139 The pull request should again contain a telling subject and a reference
140 with `fixes` to an existing issue id if any. That allows developers
141 to automatically resolve the issues once your PR gets merged.
151 Thanks a lot for your contribution!
154 ### <a id="contributing-rebase"></a> Rebase a Branch
156 If you accidentally sent in a PR which was not rebased against the upstream master,
157 developers might ask you to rebase your PR.
159 First off, fetch and pull `upstream` master.
164 git pull upstream HEAD
167 Then change to your working branch and start rebasing it against master:
170 git checkout fix/notifications
174 If you are running into a conflict, rebase will stop and ask you to fix the problems.
179 both modified: path/to/conflict.cpp
182 Edit the file and search for `>>>`. Fix, build, test and save as needed.
184 Add the modified file(s) and continue rebasing.
187 git add path/to/conflict.cpp
188 git rebase --continue
191 Once succeeded ensure to push your changed history remotely.
194 git push -f origin fix/notifications
198 If you fear to break things, do the rebase in a backup branch first and later replace your current branch.
201 git checkout fix/notifications
202 git checkout -b fix/notifications-rebase
206 git branch -D fix/notifications
207 git checkout -b fix/notifications
209 git push -f origin fix/notifications
212 ### <a id="contributing-squash"></a> Squash Commits
216 > Be careful with squashing. This might lead to non-recoverable mistakes.
218 > This is for advanced Git users.
220 Say you want to squash the last 3 commits in your branch into a single one.
222 Start an interactive (`-i`) rebase from current HEAD minus three commits (`HEAD~3`).
228 Git opens your preferred editor. `pick` the commit in the first line, change `pick` to `squash` on the other lines.
231 pick e4bf04e47 Fix notifications
232 squash d7b939d99 Tests
233 squash b37fd5377 Doc updates
236 Save and let rebase to its job. Then force push the changes to the remote origin.
239 git push -f origin fix/notifications
243 ## <a id="contributing-testing"></a> Testing
245 Basic unit test coverage is provided by running `make test` during package builds.
246 Read the [INSTALL.md](INSTALL.md) file for more information about development builds.
248 Snapshot packages from the laster development branch are available inside the
249 [package repository](https://packages.icinga.com).
251 You can help test-drive the latest Icinga 2 snapshot packages inside the
252 [Icinga 2 Vagrant boxes](https://github.com/icinga/icinga-vagrant).
255 ## <a id="contributing-patches-source-code"></a> Source Code Patches
257 Icinga 2 is written in C++ and uses the Boost libraries. We are also using the C++11 standard where applicable (please
258 note the minimum required compiler versions in the [INSTALL.md](INSTALL.md) file.
260 Icinga 2 can be built on Linux/Unix and Windows clients. In order to develop patches for Icinga 2,
261 you should prepare your own local build environment and know how to work with C++.
265 * Requirements and source code installation is explained inside the [INSTALL.md](INSTALL.md) file.
266 * Debug requirements and GDB instructions can be found in the [documentation](https://github.com/Icinga/icinga2/blob/master/doc/20-development.md).
267 * If you are planning to debug a Windows client, setup a Windows environment with [Visual Studio](https://www.visualstudio.com/vs/community/). An example can be found in [this blogpost](https://blog.netways.de/2015/08/24/developing-icinga-2-on-windows-10-using-visual-studio-2015/).
269 ## <a id="contributing-patches-documentation"></a> Documentation Patches
271 The documentation is written in GitHub flavored [Markdown](https://guides.github.com/features/mastering-markdown/).
272 It is located in the `doc/` directory and can be edited with your preferred editor. You can also
273 edit it online on GitHub.
276 vim doc/2-getting-started.md
279 In order to review and test changes, you can install the [mkdocs](http://www.mkdocs.org) Python library.
285 This allows you to start a local mkdocs viewer instance on http://localhost:8000
291 Changes on the chapter layout can be done inside the `mkdocs.yml` file in the main tree.
293 There also is a script to ensure that relative URLs to other sections are updated. This script
294 also checks for broken URLs.
297 ./doc/update-links.py doc/*.md
300 ## <a id="contributing-patches-itl-checkcommands"></a> Contribute CheckCommand Definitions
302 The Icinga Template Library (ITL) and its plugin check commands provide a variety of CheckCommand
303 object definitions which can be included on-demand.
305 Advantages of sending them upstream:
307 * Everyone can use and update/fix them.
308 * One single place for configuration and documentation.
309 * Developers may suggest updates and help with best practices.
310 * You don't need to care about copying the command definitions to your satellites and clients.
312 #### <a id="contributing-itl-checkcommands-start"></a> Where do I start?
314 Get to know the check plugin and its options. Read the general documentation on how to integrate
315 your check plugins and how to create a good CheckCommand definition.
317 A good command definition uses:
319 * Command arguments including `value`, `description`, optional: `set_if`, `required`, etc.
320 * Comments `/* ... */` to describe difficult parts.
321 * Command name as prefix for the custom attributes referenced (e.g. `disk_`)
323 * If `host.address` is involved, set a custom attribute (e.g. `ping_address`) to the default `$address$`. This allows users to override the host's address later on by setting the custom attribute inside the service apply definitions.
324 * If the plugin is also capable to use ipv6, import the `ipv4-or-ipv6` template and use `$check_address$` instead of `$address$`. This allows to fall back to ipv6 if only this address is set.
325 * If `set_if` is involved, ensure to specify a sane default value if required.
326 * Templates if there are multiple plugins with the same basic behaviour (e.g. ping4 and ping6).
327 * Your love and enthusiasm in making it the perfect CheckCommand.
329 #### <a id="contributing-itl-checkcommands-overview"></a> I have created a CheckCommand, what now?
331 Icinga 2 developers love documentation. This isn't just because we want to annoy anyone sending a patch,
332 it's a matter of making your contribution visible to the community.
334 Your patch should consist of 2 parts:
336 * The CheckCommand definition.
337 * The documentation bits.
339 [Fork the repository](https://help.github.com/articles/fork-a-repo/) and ensure that the master branch is up-to-date.
341 Create a new fix or feature branch and start your work.
344 git checkout -b feature/itl-check-printer
347 #### <a id="contributing-itl-checkcommands-add"></a> Add CheckCommand Definition to Contrib Plugins
349 There already exists a defined structure for contributed plugins. Navigate to `itl/plugins-contrib.d`
350 and verify where your command definitions fits into.
353 cd itl/plugins-contrib.d/
357 If you want to add or modify an existing Monitoring Plugin please use `itl/command-plugins.conf` instead.
360 vim itl/command-plugins-conf
363 ##### Existing Configuration File
365 Just edit it, and add your CheckCommand definition.
368 vim operating-system.conf
371 Proceed to the documentation.
373 ##### New type for CheckCommand Definition
375 Create a new file with .conf suffix.
381 Add the file to `itl/CMakeLists.txt` in the FILES line in **alpha-numeric order**.
382 This ensures that the installation and packages properly include your newly created file.
387 -FILES ipmi.conf network-components.conf operating-system.conf virtualization.conf vmware.conf
388 +FILES ipmi.conf network-components.conf operating-system.conf printer.conf virtualization.conf vmware.conf
391 Add the newly created file to your git commit.
397 Do not commit it yet but finish with the documentation.
399 #### <a id="contributing-itl-checkcommands-docs"></a> Create CheckCommand Documentation
401 Edit the documentation file in the `doc/` directory. More details on documentation
402 updates can be found [here](CONTRIBUTING.md#contributing-documentation).
405 vim doc/7-icinga-template-library.md
408 The CheckCommand documentation should be located in the same chapter
409 similar to the configuration file you have just added/modified.
411 Create a section for your plugin, add a description and a table of parameters. Each parameter should have at least:
413 * optional or required
414 * description of its purpose
415 * the default value, if any
417 Look at the existing documentation and "copy" the same style and layout.
420 #### <a id="contributing-itl-checkcommands-patch"></a> Send a Patch
422 Commit your changes which includes a descriptive commit message.
426 Add printer CheckCommand definition
428 Explain its purpose and possible enhancements/shortcomings.
430 refs #existingticketnumberifany
432 Push the branch to the remote origin and create a [pull request](https://help.github.com/articles/using-pull-requests/).
435 git push --set-upstream origin feature/itl-check-printer
439 In case developers ask for changes during review, please add them
440 to the branch and push those changes.