Do you have something you’d like to contribute to Educama? We welcome pull requests, but ask that you carefully read this document first to understand how best to submit them; what kind of changes are likely to be accepted; and what to expect from the Educama core developers when evaluating your submission.

Please refer back to this document as a checklist before issuing any pull request; this will save time for everyone!

Language

The project language is English. This applies to code, comments in code, commit messages, documentation, ticketing system, ...
When working on existing documentation written in German please translate this to English.

Workflow in JIRA

If your change is non trivial then we ask you to create an issue (=ticket) in JIRA first (if none exists). Trivial changes can be made without an issue.

The following workflow applies to issues:

1. Start working on an issue:
   1. move the issue to state "In Progress"
   2. assign it to yourself
2. Finish your work
   1. comment your change (e.g. link the pull request)
   2. remove the assignment
   3. move the issue to state "Pair Review"
3. Review (done by some-one else)
   1. assign the issue to yourself
   2. comment the successful review / your findings
   3. OK: move the issue to state "Done" and re-assign it to the original author
   4. Findings: move the ticket to state "In Progress" and re-assign it to the original author.

Create your a pull request

Understanding the basics

Not sure what a pull request is, or how to submit one? Take a look at GitHub's excellent documentation at https://help.github.com/articles/about-pull-requests/ and http://help.github.com/send-pull-requests first.

Discuss non-trivial contribution ideas with committers

If you're considering anything more than correcting a typo or fixing a minor bug, please discuss it with the Educama developers before submitting a pull request. We're happy to provide guidance, but please spend an hour or two researching the subject on your own including searching the mailing list for prior discussions.

Mind the whitespace

Please carefully follow the whitespace and formatting conventions already present in the code.

• Eliminate all trailing whitespace
• Aim to wrap code at 120 characters, but favor readability over wrapping
• Preserve existing formatting; i.e. do not reformat code for its own sake. However, if you do then please provide it as a separate commit before your changes.
• Search the codebase to discover common naming conventions, etc.

Clean up commit history

Use `git rebase --interactive` to "squash" multiple commits into atomic changes. In addition to the man pages for git, there are many resources online to help you understand how these tools work. Here is one: <http://book.git-scm.com/4_interactive_rebasing.html>.

Use real name in git commits

Please configure git to use your real first and last name for any commits you intend to submit as pull requests, e.g.
Author: First Last <user@mail.com>

You can configure this globally with:

git config --global user.name "John Doe"
git config --global user.email john.doe@example.com

These settings will be written to ~/.gitconfig on Unix and %APPDATA%\.gitconfig on Windows, see https://help.github.com/articles/set-up-git/

Alternatively, you can configure this locally for the Showcase repository only by omitting the `--global` flag:

cd Showcase
git config user.name "John Doe"
git config user.email john.doe@example.com

Format commit messages

Most importantly, please format your commit messages in the following way:

• Prefix Git commit messages with the ticket number, e.g. "ECM-1: xyz"
• Describe WHY you are making the change, e.g. "ECM-1: Added logback to suppress the debug messages during maven build" (not only "changed logging").

Run all tests prior to submission

Make sure that all tests pass prior to submitting your pull request.
Note: If you like you can register at http://travis-ci.org and enable builds for your forked repository. Then the complete build will be executed every time you push changes to your forked repository.

Basis of you pull request

Please always base your (updated) pull request on the current master, i.e. rebase against the master branch before creating or updating your pull request. Please don't create pull requests which depend on other pull requests - instead put all commits into a single pull request or wait for the dependent pull request to be integrated.

Submit your pull request

Expect discussion and rework

The Educama team takes a conservative approach to accepting contributions. This is to keep code quality and stability as high as possible, and to keep complexity at a minimum. You may be asked to rework the submission for style (as explained above) and/or substance.

The continuous integration environment at https://travis-ci.org/Educama/Showcase will build and test your pull request, but not deploy it.

Note that you can always force push (`git push -f`) reworked / rebased commits against the branch used to submit your pull request. i.e. you do not need to issue a new pull request when asked to make changes.