diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c7c2c8d04..afb4cfa91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,27 @@ - - # Contributing +Icinga is is an open source project and lives from your ideas and contributions. + +There are many ways to contribute, from improving the documentation, submitting +bug reports and features requests or writing code to add enhancements or fix bugs. + #### Table of Contents -1. [Introduction][Introduction] -2. [Branches][Branches] -3. [Testing][Testing] -4. [Patches][Patches] +1. [Introduction](#contributing-intro) +2. [Fork the Project](#contributing-fork) +3. [Branches](#contributing-branches) +4. [Commits](#contributing-commits) +5. [Pull Requests](#contributing-pull-requests) +6. [Testing](#contributing-testing) +7. [Source Code Patches](#contributing-patches-source-code) +8. [Documentation Patches](#contributing-patches-documentation) +9. [Contribute CheckCommand Definitions](#contributing-patches-itl-checkcommands) ## 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. +Please consider our [roadmap](https://github.com/Icinga/icinga2/milestones) and +[open issues](https://github.com/icinga/icinga2/issues) 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. @@ -21,19 +30,216 @@ All pull requests will be reviewed and merged if they suit some general guidelin * Changes are located in a topic branch * For new functionality, proper tests are written -* Changes should not solve certain problems on special environments +* Changes should follow the existing coding style and standards + +Please continue reading in the following sections for a step by step guide. + +## Fork the Project + +[Fork the project](https://help.github.com/articles/fork-a-repo/) to your GitHub account +and clone the repository: + +``` +git clone git@github.com:dnsmichi/icinga2.git +cd icinga2 +``` + +Add a new remote `upstream` with this repository as value. + +``` +git remote add upstream https://github.com/icinga/icinga2.git +``` + +You can pull updates to your fork's master branch: + +``` +git fetch --all +git pull upstream HEAD +``` + +Please continue to learn about [branches](CONTRIBUTING.md#contributing-branches). ## 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. +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 ``` +Continue to apply your changes and test them. More details on specific changes: + +* [Source Code Patches](#contributing-patches-source-code) +* [Documentation Patches](#contributing-patches-documentation) +* [Contribute CheckCommand Definitions](#contributing-patches-itl-checkcommands) + +## Commits + +Once you've finished your work in a branch, please ensure to commit +your changes. A good commit message includes a short topic, additional body +and a reference to the issue you wish to solve (if existing). + +Fixes: + +``` +Fix problem with notifications in HA cluster + +There was a race condition when restarting. + +refs #4567 +``` + +Features: + +``` +Add ITL CheckCommand printer + +Requires the check_printer plugin. + +refs #1234 +``` + +You can add multiple commits during your journey to finish your patch. +Don't worry, you can squash those changes into a single commit later on. + +## Pull Requests + +Once you've commited your changes, please update your local master +branch and rebase your fix/feature branch against it before submitting a PR. + +``` +git checkout master +git pull upstream HEAD + +git checkout fix/notifications +git rebase master +``` + +Once you've resolved any conflicts, push the branch to your remote repository. +It might be necessary to force push after rebasing - use with care! + +New branch: +``` +git push --set-upstream origin fix/notifications +``` + +Existing branch: +``` +git push -f origin fix/notifications +``` + +You can now either use the [hub](https://hub.github.com) CLI tool to create a PR, or nagivate +to your GitHub repository and create a PR there. + +The pull request should again contain a telling subject and a reference +with `fixes` to an existing issue id if any. That allows developers +to automatically resolve the issues once your PR gets merged. + +``` +hub pull-request + + + +fixes #1234 +``` + +Thanks a lot for your contribution! + + +### Rebase a Branch + +If you accidentally sent in a PR which was not rebased against the upstream master, +developers might ask you to rebase your PR. + +First off, fetch and pull `upstream` master. + +``` +git checkout master +git fetch --all +git pull upstream HEAD +``` + +Then change to your working branch and start rebasing it against master: + +``` +git checkout fix/notifications +git rebase master +``` + +If you are running into a conflict, rebase will stop and ask you to fix the problems. + +``` +git status + + both modified: path/to/conflict.cpp +``` + +Edit the file and search for `>>>`. Fix, build, test and save as needed. + +Add the modified file(s) and continue rebasing. + +``` +git add path/to/conflict.cpp +git rebase --continue +``` + +Once succeeded ensure to push your changed history remotely. + +``` +git push -f origin fix/notifications +``` + + +If you fear to break things, do the rebase in a backup branch first and later replace your current branch. + +``` +git checkout fix/notifications +git checkout -b fix/notifications-rebase + +git rebase master + +git branch -D fix/notifications +git checkout -b fix/notifications + +git push -f origin fix/notifications +``` + +### Squash Commits + +> **Note:** +> +> Be careful with squashing. This might lead to non-recoverable mistakes. +> +> This is for advanced Git users. + +Say you want to squash the last 3 commits in your branch into a single one. + +Start an interactive (`-i`) rebase from current HEAD minus three commits (`HEAD~3`). + +``` +git rebase -i HEAD~3 +``` + +Git opens your preferred editor. `pick` the commit in the first line, change `pick` to `squash` on the other lines. + +``` +pick e4bf04e47 Fix notifications +squash d7b939d99 Tests +squash b37fd5377 Doc updates +``` + +Save and let rebase to its job. Then force push the changes to the remote origin. + +``` +git push -f origin fix/notifications +``` + + ## Testing Basic unit test coverage is provided by running `make test` during package builds. @@ -46,9 +252,7 @@ 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 +## Source Code Patches 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. @@ -62,7 +266,7 @@ More tips: * 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 +## Documentation Patches 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 @@ -93,7 +297,7 @@ also checks for broken URLs. ./doc/update-links.py doc/*.md ``` -### Contribute CheckCommand Definitions +## 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. @@ -235,8 +439,3 @@ 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