diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..863876ad4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,242 @@ + + +# Contributing + +#### Table of Contents + +1. [Introduction][Introduction] +2. [Branches][Branches] +3. [Testing][Testing] +4. [Patches][Patches] + +## 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 + +## 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 +``` + +## 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). + + +## Patches + +### 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/). + +### 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 +``` + +### 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. + +#### 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. + +#### 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 +``` + +#### 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. + +#### 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. + + +#### 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. + + +[Introduction]: #contributing-intro +[Branches]: #contributing-branches +[Testing]: #contributing-testing +[Patches]: #contributing-patches diff --git a/README.md b/README.md index 441d0fba5..7a90b75e8 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ 3. [Installation][Installation] 4. [Documentation][Documentation] 5. [Support][Support] -6. [Development and Contributions][Development] +6. [Contributing][Contributing] ## About @@ -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). + [About]: #about [License]: #license [Installation]: #installation [Documentation]: #documentation [Support]: #support -[Development]: #development +[Contributing]: #contributing