Contributing to OSIAM
Thank you for considering to contribute to OSIAM.
This document is here to offer you a few helpful notes to get you started and make your experience as smooth as possible. They should be seen as guidelines. They are not strict rules and we won't blame anyone who tries to contribute. By following the steps in this document you will make our lives a bit easier but we will still be happy about your contribution if you don't.
Reporting Issues on Github
The easiest way to contribute to OSIAM is by filing issues on Github. It does not have to be a bug, it can also be a feature request or a suggestion to improve our documentation. We will do our best to answer your issue as fast as possible. Before you create an issue on Github please consider doing the following:
- Search existing issues before creating a new one.
- If you are reporting a bug please include as much details as possible.
This might include:
- Which OS you're using
- Which version you've been running
- Logs/Stacktrace of the error that occurred
- Steps to reproduce
- The expected result
- The actual result
The Master is Read Only
We consider the master branch of all OSIAM projects read only. That means we don't want any code to be added to it without getting reviewed by somebody else. For that reason we don't want to accept any modifications to the master branch that doesn't have its origin in a pull request. We believe that not only does this improve the quality of our code base tremendously, but also offers us a good way to learn from our mistakes.
As coding conventions we adopted the Oracle's official [Coding conventions for the Java Programming Language] (http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html) with the following two exceptions:
- We use a line width of 120 characters.
- We indent with four spaces and no tabs.
You can find a formatter definition for the Eclipse IDE [here] (https://gist.github.com/tkrille/46e284a17c744243bc20).
If you want us to review a pull request with your modifications to OSIAM please consider doing the following:
- Add an issue on Github and let us know that you're working on something.
- Use a feature branch, not master.
- Rebase your feature branch onto origin/master before raising the PR.
- Be descriptive in your PR and commit messages. What is it for, why is it needed and how you implemented it.
- Make sure the [integration tests] (https://github.com/osiam/connector4java-integration-tests) pass.
- Please squash related commits.
- Please make sure that your pull request adheres to our [coding conventions] (#coding-conventions).
If while you've been working in the feature branch new commits were added to the master branch please don't merge them but use rebase:
git fetch origin git rebase origin/master
This will apply all commits on your feature branch on top of the master branch.
Any conflicts can be resolved just the same as if git merge was used. After
the conflict has been resolved use
git rebase --continue to continue the
Minor commits that only fix typos or rename variables that are related to a bigger change should be squashed into that commit.
This can be done using
git rebase -i ( <hash> | <branch> )
For example while working on a feature branch you'd use:
git add . git commit -m "implemented feature XY" # push and ask for a merge/review git add . git commit --fixup $(git rev-parse HEAD) # push and ask for a merge/review git add . git commit --fixup $(git rev-parse HEAD) git rebase -i origin/master
git commit --fixup will mark the commit as a fixup relating to the commit
HEAD currently points to. This is useful because
git rebase -i will then
automatically recognize the fixup commits and mark them to squash. But in
order for that to work the autosquash setting has to be enabled in the
git config --global rebase.autosquash true
Please be civilized in all interactions concerning OSIAM that you participate in. Most of us are working on OSIAM in our spare time while we have day jobs and other social and familiar obligations. We don't want to deal with toxic or abusive behaviour while we are spending time on something we love. We want to be a community that is welcoming to all and a place where everybody can feel save and appreciated.
Much of this document was taken from and inspired by the
document of the excellent crate project. We use it with
a lot of love.