Difference between revisions of "How to contribute"

Latest revision as of 12: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:

Sign off your contribution (this is a Git feature)
Follow 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

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.

@@ 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.
-= We are thankful for every contribution! =
-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.
-The following paragraphs address some important points, but if you are in doubt about something, feel free to ask on [[Mailinglist|the mailinglist]]
+* [[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
-== Code contributions ==
+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.
-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 [http://bugs.mitk.org   report a bug] for a defect in MITK or discuss new features on our [[Mailinglist]].
-* Create (or use your existing) [http://github.com   GitHub] account and [http://github.com/MITK/MITK   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 [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 ====
-There are some [http://docs.mitk.org/nightly-qt4/StylesAndNotesPage.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 ====
-If you are new to git and GitHub, please create an account on [http://github.com   GitHub] and read the read [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''.
-==== Create a topic branch ====
-To help us reviewing and merging your contribution, you should create a ''topic branch'' on your [http://github.com/MITK/MITK   MITK] fork on [http://github.com   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):
-<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>
-==== Publish your changes ====
-After you made a set of changes and are ready to publish your work, you could do
-<pre><nowiki>
-(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
-</nowiki></pre>
-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 [http://help.github.com/send-pull-requests/   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 [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.

Difference between revisions of "How to contribute"

Latest revision as of 12:43, 11 February 2021

Navigation menu

Search