mirror of
https://github.com/Icinga/icinga2.git
synced 2025-04-08 17:05:25 +02:00
Add more insights on commits, PRs, rebase, squash to CONTRIBUTING.md
refs #5156
This commit is contained in:
Michael Friedrich
parent
d7b939d99b
commit
a022bed1b2
243
CONTRIBUTING.md
243
CONTRIBUTING.md
@ -1,18 +1,27 @@
|
||||
|
||||
|
||||
# <a id="contributing"></a> 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)
|
||||
|
||||
## <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.
|
||||
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.
|
||||
|
||||
## <a id="contributing-fork"></a> 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).
|
||||
|
||||
## <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.
|
||||
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)
|
||||
|
||||
## <a id="contributing-commits"></a> 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.
|
||||
|
||||
## <a id="contributing-pull-requests"></a> 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
|
||||
|
||||
<a telling subject>
|
||||
|
||||
fixes #1234
|
||||
```
|
||||
|
||||
Thanks a lot for your contribution!
|
||||
|
||||
|
||||
### <a id="contributing-rebase"></a> 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
|
||||
```
|
||||
|
||||
### <a id="contributing-squash"></a> 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
|
||||
```
|
||||
|
||||
|
||||
## <a id="contributing-testing"></a> 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).
|
||||
|
||||
|
||||
## <a id="contributing-patches"></a> Patches
|
||||
|
||||
### <a id="contributing-source-code"></a> Source Code
|
||||
## <a id="contributing-patches-source-code"></a> 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/).
|
||||
|
||||
### <a id="contributing-documentation"></a> Update the Documentation
|
||||
## <a id="contributing-patches-documentation"></a> 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
|
||||
```
|
||||
|
||||
### <a id="contributing-itl-checkcommands"></a> Contribute CheckCommand Definitions
|
||||
## <a id="contributing-patches-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.
|
||||
@ -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.
|
||||
|
||||
<!-- TOC URLs -->
|
||||
[Introduction]: #contributing-intro
|
||||
[Branches]: #contributing-branches
|
||||
[Testing]: #contributing-testing
|
||||
[Patches]: #contributing-patches
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user