How to contribute

From mitk.org
Revision as of 19:08, 22 October 2013 by SaschaZelzer (talk | contribs) (fixed internal link)
Jump to navigation Jump to search

How to contribute to MITK

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.

To ensure that contributors actually have the rights to contribute copyrighted code, we use the "Sign Off" feature of Git to link your commits to a "Developer's Certificate of Origin" statement. Please read Signing off your contribution carefully and also read the paragraphs below to see some workflow examples for the actual process of contributing something.

If you are in doubt about something, feel free to ask on the mailinglist

For MBI members who are about to merge external contributions, you might find some help here: internal/HowToMergeContributions

Code contributions

Code should be preferably contributed in form of git branches or git patches. 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.
  • Optionally, create (or use your existing) GitHub account and fork MITK or just clone MITK locally.
  • Create a topic branch (use bug-<bug-id>-some-descriptive-text as the branch name if you intend to send a pull-request) 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 attach patches to the corresponding bug report. If you use a GitHub pull request, make sure that you additionally advertise your request on the mitk-users list or the corresponding bug report (don't rely on the GitHub notification system, because most of the MITK developers do not have a GitHub account).

If you really are not able to use Git, we will also accept plain diff files 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

  • Separate logical changes into single commits or patch files.
  • Use concise commit messages.
  • 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

The MITK Git repository is hosted on mitk.org and mirrored on GitHub at https://github.com/MITK/MITK. You can either clone the official MITK repository 

git clone http://git.mitk.org/MITK.git

or fork the MITK GitHub mirror. If you directly clone the official repository, you will have to send us your contributions in the form of a patch set. Using GitHub simplifies the whole process by making your contribution publicly available, allowing us to merge it directly.

Using GitHub for contributions

If you want to use GitHub for your contributions, please create an account on GitHub and read the 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. 

git remote add upstream http://git.mitk.org/MITK.git


Create a topic branch

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

Assuming that your bug id is 1001 and that you have a local clone of your MITK GitHub fork with upstream being a remote pointing to the original MITK 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


If you cloned directly from mitk.org, creating a topic branch is done by: 

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


Publish your changes

After you made a set of logically connected changes, create a commit and sign it off (in your GitHub fork or official MITK clone). 

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

Repeat the above step until your contribution is complete.

If you created a GitHub fork, publish your work by pushing the topic branch to your fork: 

(bug-1001-my-new-feature) ~/git/MITK-fork> git push origin bug-1001-my-new-feature

Otherwise, create a patch set via: 

(bug-1001-my-new-feature) ~/git/MITK-org> git format-patch -k master


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

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 and attach the generated patch files or send a pull request if you are using GitHub. In the latter case, you should also advertise your pull request on the mitk-users list or the corresponding bug report. Otherwise, MITK developers will not get notified about your request (many developers of the team do not have a GitHub account).

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.

Retrieved from "http://mitk.org/w/index.php?title=How_to_contribute&oldid=1040"