Skip to content

Commit

Permalink
Add CONTRIBUTING.md
Browse files Browse the repository at this point in the history
This also includes the old docs for CheckCommand definitions, etc.

fixes #5156
  • Loading branch information
Michael Friedrich committed Apr 18, 2017
1 parent dc79805 commit fac61a5
Show file tree
Hide file tree
Showing 2 changed files with 247 additions and 27 deletions.
242 changes: 242 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,242 @@


# <a id="contributing"></a> Contributing

#### Table of Contents

1. [Introduction][Introduction]
2. [Branches][Branches]
3. [Testing][Testing]
4. [Patches][Patches]

## <a id="contributing-intro"></a> Introduction

A roadmap of this project is located at https://github.com/Icinga/icinga2/milestones. Please consider
this roadmap when you start contributing to the project.

Before starting your work on Icinga 2, you should [fork the project](https://help.github.com/articles/fork-a-repo/)
to your GitHub account. This allows you to freely experiment with your changes.
When your changes are complete, submit a [pull request](https://help.github.com/articles/using-pull-requests/).
All pull requests will be reviewed and merged if they suit some general guidelines:

* Changes are located in a topic branch
* For new functionality, proper tests are written
* Changes should not solve certain problems on special environments

## <a id="contributing-branches"></a> Branches

Choosing a proper name for a branch helps us identify its purpose and possibly find an associated bug or feature.
Generally a branch name should include a topic such as `fix` or `feature` followed by a description and an issue number
if applicable. Branches should have only changes relevant to a specific issue.

```
git checkout -b fix/service-template-typo-1234
git checkout -b feature/config-handling-1235
```

## <a id="contributing-testing"></a> Testing

Basic unit test coverage is provided by running `make test` during package builds.
Read the [INSTALL.md](INSTALL.md) file for more information about development builds.

Snapshot packages from the laster development branch are available inside the
[package repository](http://packages.icinga.com).

You can help test-drive the latest Icinga 2 snapshot packages inside the
[Icinga 2 Vagrant boxes](https://github.com/icinga/icinga-vagrant).


## <a id="contributing-patches"></a> Patches

### <a id="contributing-source-code"></a> Source Code

Icinga 2 is written in C++ and uses the Boost libraries. We are also using the C++11 standard where applicable (please
note the minimum required compiler versions in the [INSTALL.md](INSTALL.md) file.

Icinga 2 can be built on Linux/Unix and Windows clients. In order to develop patches for Icinga 2,
you should prepare your own local build environment and know how to work with C++.

More tips:

* Requirements and source code installation is explained inside the [INSTALL.md](INSTALL.md) file.
* Debug requirements and GDB instructions can be found in the [documentation](https://github.com/Icinga/icinga2/blob/master/doc/20-development.md).
* 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/).

### <a id="contributing-documentation"></a> Update the Documentation

The documentation is written in GitHub flavored [Markdown](https://guides.github.com/features/mastering-markdown/).
It is located in the `doc/` directory and can be edited with your preferred editor. You can also
edit it online on GitHub.

```
vim doc/2-getting-started.md
```

In order to review and test changes, you can install the [mkdocs](http://www.mkdocs.org) Python library.

```
pip install mkdocs
```

This allows you to start a local mkdocs viewer instance on http://localhost:8000

```
mkdocs serve
```

Changes on the chapter layout can be done inside the `mkdocs.yml` file in the main tree.

There also is a script to ensure that relative URLs to other sections are updated. This script
also checks for broken URLs.

```
./doc/update-links.py doc/*.md
```

### <a id="contributing-itl-checkcommands"></a> Contribute CheckCommand Definitions

The Icinga Template Library (ITL) and its plugin check commands provide a variety of CheckCommand
object definitions which can be included on-demand.

Advantages of sending them upstream:

* Everyone can use and update/fix them.
* One single place for configuration and documentation.
* Developers may suggest updates and help with best practices.
* You don't need to care about copying the command definitions to your satellites and clients.

#### <a id="contributing-itl-checkcommands-start"></a> Where do I start?

Get to know the check plugin and its options. Read the general documentation on how to integrate
your check plugins and how to create a good CheckCommand definition.

A good command definition uses:

* Command arguments including `value`, `description`, optional: `set_if`, `required`, etc.
* Comments `/* ... */` to describe difficult parts.
* Command name as prefix for the custom attributes referenced (e.g. `disk_`)
* Default values
* 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.
* 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.
* If `set_if` is involved, ensure to specify a sane default value if required.
* Templates if there are multiple plugins with the same basic behaviour (e.g. ping4 and ping6).
* Your love and enthusiasm in making it the perfect CheckCommand.

#### <a id="contributing-itl-checkcommands-overview"></a> I have created a CheckCommand, what now?

Icinga 2 developers love documentation. This isn't just because we want to annoy anyone sending a patch,
it's a matter of making your contribution visible to the community.

Your patch should consist of 2 parts:

* The CheckCommand definition.
* The documentation bits.

[Fork the repository](https://help.github.com/articles/fork-a-repo/) and ensure that the master branch is up-to-date.

Create a new fix or feature branch and start your work.

```
git checkout -b feature/itl-check-printer
```

#### <a id="contributing-itl-checkcommands-add"></a> Add CheckCommand Definition to Contrib Plugins

There already exists a defined structure for contributed plugins. Navigate to `itl/plugins-contrib.d`
and verify where your command definitions fits into.

```
cd itl/plugins-contrib.d/
ls
```

If you want to add or modify an existing Monitoring Plugin please use `itl/command-plugins.conf` instead.

```
vim itl/command-plugins-conf
```

##### Existing Configuration File

Just edit it, and add your CheckCommand definition.

```
vim operating-system.conf
```

Proceed to the documentation.

##### New type for CheckCommand Definition

Create a new file with .conf suffix.

```
$ vim printer.conf
```

Add the file to `itl/CMakeLists.txt` in the FILES line in **alpha-numeric order**.
This ensures that the installation and packages properly include your newly created file.

```
vim CMakeLists.txt
-FILES ipmi.conf network-components.conf operating-system.conf virtualization.conf vmware.conf
+FILES ipmi.conf network-components.conf operating-system.conf printer.conf virtualization.conf vmware.conf
```

Add the newly created file to your git commit.

```
git add printer.conf
```

Do not commit it yet but finish with the documentation.

#### <a id="contributing-itl-checkcommands-docs"></a> Create CheckCommand Documentation

Edit the documentation file in the `doc/` directory. More details on documentation
updates can be found [here](CONTRIBUTING.md#contributing-documentation).

```
vim doc/7-icinga-template-library.md
```

The CheckCommand documentation should be located in the same chapter
similar to the configuration file you have just added/modified.

Create a section for your plugin, add a description and a table of parameters. Each parameter should have at least:

* optional or required
* description of its purpose
* the default value, if any

Look at the existing documentation and "copy" the same style and layout.


#### <a id="contributing-itl-checkcommands-patch"></a> Send a Patch

Commit your changes which includes a descriptive commit message.

```
git commit -av
Add printer CheckCommand definition
Explain its purpose and possible enhancements/shortcomings.
refs #existingticketnumberifany
```
Push the branch to the remote origin and create a [pull request](https://help.github.com/articles/using-pull-requests/).

```
git push --set-upstream origin feature/itl-check-printer
hub pull-request
```

In case developers ask for changes during review, please add them
to the branch and push those changes.

<!-- TOC URLs -->
[Introduction]: #contributing-intro
[Branches]: #contributing-branches
[Testing]: #contributing-testing
[Patches]: #contributing-patches
32 changes: 5 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
3. [Installation][Installation]
4. [Documentation][Documentation]
5. [Support][Support]
6. [Development and Contributions][Development]
6. [Contributing][Contributing]

## About

Expand Down Expand Up @@ -48,41 +48,19 @@ Check the project website at https://www.icinga.com for status updates. Join the
[community channels](https://www.icinga.com/community/get-involved/) for questions
or ask an Icinga partner for [professional support](https://www.icinga.com/services/support/).

## Development

The Git repository is located on [GitHub](https://github.com/Icinga/icinga2).

Icinga 2 is written in C++ and can be built on Linux/Unix and Windows.
Read more about development builds in the [INSTALL.md](INSTALL.md) file.

### Contributing
## Contributing

There are many ways to contribute to Icinga -- whether it be sending patches,
testing, reporting bugs, or reviewing and updating the documentation. Every
contribution is appreciated!

Please read the [contributing section](https://www.icinga.com/community/get-involved/)
first. Then you should have a look at the [roadmap](https://github.com/Icinga/icinga2/milestones)
and remaining [open issues](https://github.com/Icinga/icinga2/issues).

Pick issues you want to help resolve, fork the [repository on GitHub](https://github.com/Icinga/icinga2)
and send a pull request with your changes. Thanks for your contribution!

### Testing

Basic unit test coverage is provided by running `make test` during package builds.
Read the [INSTALL.md](INSTALL.md) file for more information about development builds.

Snapshot packages from the laster development branch are available inside the
[package repository](http://packages.icinga.com).

You can help test-drive the latest Icinga 2 snapshot packages inside the
[Icinga 2 Vagrant boxes](https://github.com/icinga/icinga-vagrant).
Please continue reading in the [Contributing chapter](CONTRIBUTING.md).


<!-- TOC URLs -->
[About]: #about
[License]: #license
[Installation]: #installation
[Documentation]: #documentation
[Support]: #support
[Development]: #development
[Contributing]: #contributing

0 comments on commit fac61a5

Please sign in to comment.