We are thankful for every contribution!

First of all, we are happy about every piece of code/documentation that you contribute! Since we have not got a publicly writable git repository, there are some things that you should know before working on contributions. This is mainly to save us integration work, but also to save you frustration, in case something is implemented in parallel.

The following paragraphs address some important points, but if you are in doubt about something, feel free to ask on the mailinglist

Code contributions

Code should be contributed in form of git branches. The following list quickly explains the usual steps, which are explained in more detail further below.

Either report a bug for a defect in MITK or discuss new features on our Mailinglist.
Create (or use your existing) GitHub account and fork MITK.
Create a topic branch (use bug-<bug-id>-some-descriptive-text as the branch name) and push your changes into that branch on your fork.
Use the corresponding bug for communication with the MITK developers (not the GitHub features)
Send a pull request via GitHub or just as a comment in the bug

If you really are not able to use Git, we will also accept patches attached to the according bug reports.

Before you start coding

To avoid redundant/parallel implementations, you should consider telling us your plans before you really start coding. Preferably, you use the MITK mailing list, so everybody knows about your plans.

Announcing your ideas has the additional advantage that we may provide some useful hints/ideas/suggestions, that may save you work.

If you feel confident that you found a bug, please report it directly on our bug tracker. If you would like to contribute a feature and MITK developers expressed their interest in merging your contribution in the official MITK repository, please file a feature request on our bug tracker.

After having created a bug report (for an actual bug or a feature request), all technical discussions should be carried out using this bug.

Some rules

There are some rules about naming classes and files. Please try to follow them!

If you change existing classes, please start from the latest commit! If you work on your contribution over an extended time period, check for updates of these classes or tell us if you want to get notified of updates, so that merging will result in less conflicts.

One thing you should not do, is create copies of the MITK files you are about to change and simply omit the mitk:: namespace or the Qmitk part in class names. This makes it extremely difficult to produce diffs between your code and the original code.

We greatly appreciate if you provide tests for any newly introduced classes.

Git Workflow

MITK uses Git as its version control system. Every contribution should be contained in a separate topic branch.

Set up your local MITK clone

If you are new to git and GitHub, please create an account on GitHub and read the read Set up Git guide.

If you do not already have a fork of MITK in your GitHub account, please create one (read the Fork a Repo guide if you don't know how to do it). Then create a local clone of your MITK GitHub fork.

You should also add a remote pointing to the original MITK GitHub repository, which we will name upstream.

Create a topic branch

To help us reviewing and merging your contribution, you should create a topic branch on your MITK fork on GitHub.

Assuming that your bug id is 1001 and that you have a local clone of your MITK fork with upstream being a remote pointing to the original MITK GitHub repository, create a new topic branch for your code contribution (using the latest MITK commit):

(master) ~/git/MITK-fork> git fetch upstream
(master) ~/git/MITK-fork> git checkout -b bug-1001-my-new-feature upstream/master

Publish your changes

After you made a set of changes and are ready to publish your work, you could do

(bug-1001-my-new-feature) ~/git/MITK-fork> git commit -a -m "Describe your changes"
(bug-1001-my-new-feature) ~/git/MITK-fork> git push origin bug-1001-my-new-feature

If you are unsure about the design/style/correctness/etc. use your bug report to discuss it with the MITK developers.

Final pull request

After you finished your work and tested in on your available platforms, you can notify the MITK developers that your contribution is ready to be merged. You can either comment on your bug report or send a pull request.

Documentation contributions

If you have spent some time to figure out how some things work, which are currently undocumented but regularly used in MITK, you may want to share your knowledge with other users. Sometimes even some short lines of explanation help to learn about new classes.

Classes in MITK are documented using doxygen. So it is easiest for us, if you send us pieces of documentation as expected by the doxygen parser. For some formatting issues, you may want to read the doxygen manual, especially the list of keywords. Check the source of mitkBaseProperty.h for some example formatting (and doxygen usage).

Documentation contributions should generally follow the same guidelines as code contributions. However, we are happy to accept small pieces of added/improved documentation in any way.

How to contribute