Difference between revisions of "How to contribute"

From mitk.org
Jump to navigation Jump to search
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
__NOTOC__
+
First of all, we are happy about every piece of code/documentation that you contribute. Communication is key. Please coordinate your contributions ahead of time with us to minimize overhead work for both sides.
−
= How to contribute to MITK =
 
  
−
First of all, we are happy about every piece of code/documentation that you contribute!
+
We also kindly ask to follow a few rules & guidelines:
  
−
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.
+
* [[Sign_off_contribution|Sign off your contribution]] (this is a Git feature)
 +
* Follow [https://chris.beams.io/posts/git-commit/ the seven rules of a great Git commit message]
 +
* Split your work in easy to digest and coherent commits
 +
* Keep reformatting of existing code to a minimum or do it in a separate commit
 +
* If you touch code in header files or write documentation, build the doc target to check for any warnings
  
−
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 [[Sign_off_contribution|Signing off your contribution]] carefully and also read the paragraphs below to see some workflow examples for the actual process of contributing something.
+
That said, please use [https://github.com/MITK/MITK/compare GitHub pull requests] for your contribution. It would be also great if you could [https://phabricator.mitk.org/maniphest/task/edit/form/1/ open a ticket in our ticket system]. Leave the priority set at ''Needs Triage'' and add the ''#pull_request'' tag. This is the best way of raising awareness.
−
 
 
−
If you are in doubt about something, feel free to ask on [[Mailinglist|the mailinglist]]
 
−
 
 
−
''For MBI members who are about to merge external contributions, you might find some help here: [[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 [http://bugs.mitk.org  report a bug] for a defect in MITK or discuss new features on our [[Mailinglist]].
 
−
* Optionally, create (or use your existing) [http://github.com  GitHub] account and [http://github.com/MITK/MITK   fork MITK] or just [[Download|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 [http://bugs.mitk.org  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 [http://bugs.mitk.org  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 [http://docs.mitk.org/nightly-qt4/StyleGuideAndNotesPage.html 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
 
−
 
 
−
<pre><nowiki>
 
−
git clone http://git.mitk.org/MITK.git
 
−
</nowiki></pre>
 
−
 
 
−
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 [http://github.com  GitHub] and read the [http://help.github.com/linux-set-up-git/  Set up Git] guide.
 
−
 
 
−
If you do not already have a fork of MITK in your GitHub account, please create one (read the [http://help.github.com/fork-a-repo/  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''.
 
−
 
 
−
<pre><nowiki>
 
−
git remote add upstream http://git.mitk.org/MITK.git
 
−
</nowiki></pre>
 
−
 
 
−
 
 
−
==== Create a topic branch ====
 
−
 
 
−
To help us reviewing and merging your contribution, you should create a ''topic branch'' either on your [http://github.com/MITK/MITK  MITK] fork on [http://github.com  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):
 
−
 
 
−
<pre><nowiki>
 
−
(master) ~/git/MITK-fork> git fetch upstream
 
−
(master) ~/git/MITK-fork> git checkout -b bug-1001-my-new-feature upstream/master
 
−
</nowiki></pre>
 
−
 
 
−
 
 
−
If you cloned directly from mitk.org, creating a topic branch is done by:
 
−
 
 
−
<pre><nowiki>
 
−
(master) ~/git/MITK-org> git fetch
 
−
(master) ~/git/MITK-org> git checkout -b bug-1001-my-new-feature origin/master
 
−
</nowiki></pre>
 
−
 
 
−
 
 
−
==== Publish your changes ====
 
−
 
 
−
After you made a set of logically connected changes, create a commit and [[Sign_off|sign it off]] (in your GitHub fork or official MITK clone).
 
−
 
 
−
<pre><nowiki>
 
−
(bug-1001-my-new-feature) ~/git/MITK-fork> git commit -a -s -m "Describe your changes"
 
−
</nowiki></pre>
 
−
 
 
−
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:
 
−
 
 
−
<pre><nowiki>
 
−
(bug-1001-my-new-feature) ~/git/MITK-fork> git push origin bug-1001-my-new-feature
 
−
</nowiki></pre>
 
−
 
 
−
Otherwise, create a patch set via:
 
−
 
 
−
<pre><nowiki>
 
−
(bug-1001-my-new-feature) ~/git/MITK-org> git format-patch -k master
 
−
</nowiki></pre>
 
−
 
 
−
 
 
−
If you are unsure about the design/style/correctness/etc. use your bug report to discuss it with the MITK developers.
 
−
 
 
−
==== Advertise your contribution ====
 
−
 
 
−
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 [http://help.github.com/send-pull-requests/  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 [http://www.stack.nl/~dimitri/doxygen/manual.html doxygen manual], especially the [http://www.stack.nl/~dimitri/doxygen/commands.html list of keywords]. Check the source of [https://github.com/MITK/MITK/blob/master/Core/Code/DataManagement/mitkBaseProperty.h  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.
 

Latest revision as of 11:43, 11 February 2021

First of all, we are happy about every piece of code/documentation that you contribute. Communication is key. Please coordinate your contributions ahead of time with us to minimize overhead work for both sides.

We also kindly ask to follow a few rules & guidelines:

That said, please use GitHub pull requests for your contribution. It would be also great if you could open a ticket in our ticket system. Leave the priority set at Needs Triage and add the #pull_request tag. This is the best way of raising awareness.

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