Calligra/Contributing a Patch: Difference between revisions

Latest revision as of 19:39, 10 September 2014

This page describes how one can send a contributed patch for discussion to the Calligra developers.

Quick Links:

Complete list of review requests for calligra
Review Board rules for Calligra
Detailed description of the Review Board on KDE Techbase
KDE Commit policy on KDE Techbase

Create a patch

In order to create a patch with git, there are two cases:

Approach #1. You did not commit your patch in your local repository. Then in given branch (often calligra/x.y or master) type:

% git diff branchname > my.patch

my.patch will appear. Try to use better name than my.patch :)

Approach #2. You have commited the patch in your local repository. Copy the commit number to the clipboard and type:

% git format-patch -1 {paste-commit-number-here}

Then a nicely named file will appear.

Use the patch when publishing your review request as specified below.

Submit the patch to Review Board

If you are new to Calligra development you should almost always submit your patch to Calligra on KDE's Review Board. But some code needs to be reviewed even if it is created by long time core developers. If you are unsure check out the rules of the Review Board.

Log in to the Review Board. It is using the KDE identity (if you do not have an account, you can get one from KDE identity, it is open to everyone)
Click on "New Review Request"
In Repository field, choose calligra
In Diff field select the patch you want to upload
Optionally: in Parent Diff field, give a patch that needs to be applied before yours (this is only needed if the patch is based on an other patch from Review Board or on a branch different from master)
Click the "Create Review Request" button
Fill the Branch, Summary, Description, and Testing done fields
Add "calligra" in the Groups field
Add numbers of bugs (from bugs.kde.org) that are related to your patch to the Bugs field
Optionally: add specific people to the People field
Don't forget to press "Publish" button at the top of the page. You can do this later, when you're ready. Edited fields are saved for you.
After publishing Review Board sends email to the calligra-devel mailing list and other contributors can start reviewing
If you think about some specific person that should perform the review, ask specifically via email or IRC
You will be informed about any reviews that come to you. You will get either
- "Ship It!" signal allowing you to push the patch to the Calligra git repository or
- Notes on what to fix in the patch
When you improve your patch (it can happen several times) use the Update->Update Diff command to upload a new patch. Contributors will be notified about the update.

Automated creation of requests

If you happen to use reviewboard more often, automating the creation of review requests is useful. Refer to the Using post-review to post changes for review section on KDE Techbase.

@@ Line 1: / Line 1: @@
 This page describes how one can send a contributed patch for discussion to the Calligra developers.
+<b>Quick Links:</b>
+*[http://reviewboard.kde.org/groups/calligra/ Complete list of review requests for calligra]
+*[[Calligra/Policies/Review board rules|Review Board rules for Calligra]]
+*[http://techbase.kde.org/Development/Review_Board Detailed description of the Review Board] on KDE Techbase
+*[http://techbase.kde.org/Policies/Commit_Policy KDE Commit policy] on KDE Techbase
 == Create a patch ==
+In order to create a patch with git, there are two cases:
-=== SVN Users ===
+Approach #1. You did not commit your patch in your local repository. Then in given branch (often calligra/x.y or master) type:
-The easiest way to make a patch is to have a checkout of Calligra source tree, and to run "svn diff > mypatch.diff" from the calligra root dir.
+ % git diff branchname > my.patch
-=== Git Users ===
-In order to create a patch with git, which complies to the formatting expected by reviewboard:
+my.patch will appear. Try to use better name than my.patch :)
-* first create the following script:
-  #!/bin/sh
-  REV=`git svn find-rev $(git-rev-list --date-order --max-count=1 git-svn)`
-  git diff --no-prefix $* HEAD | sed -e 's/^+++ .*/&  (working copy)/' -e "s/^--- .*/&  (revision $REV)/"
-  | sed -e "N;s/^--- \/dev\/null  (revision $REV)\n+++ \([A-Za-z\/\.]*\)  (working copy)/--- \1  (revision 0)\n+++ \1  (working copy)/"
-* rebase and reset the index to the remote version: which means, the last commit is remote HEAD and all your local changes appear as uncommited changes (if new files were created, make sure they have been added to the index, git add is your friend there).
+Approach #2. You have commited the patch in your local repository. Copy the commit number to the clipboard and type:
+ % git format-patch -1 {paste-commit-number-here}
-* run the script, outputing the result to a file. Voilà, you have your patch.
+Then a nicely named file will appear.
-== Submit it to review board ==
+Use the patch when publishing your review request as specified below.
-If you are new to Calligra development you should almost submit almost always your patch to [http://reviewboard.kde.org/groups/calligra/ Calligra on KDE's review board]. But some code need to be reviewed even if it is created by long time core developers.  If you are
+== Submit the patch to Review Board ==
-unsure check out the [[Calligra/Review board rules|rules of the review board]].
+If you are new to Calligra development you should almost always submit your patch to [http://reviewboard.kde.org/groups/calligra/ Calligra on KDE's Review Board]. But some code needs to be reviewed even if it is created by long time core developers.  If you are
+unsure check out the [[Calligra/Policies/Review board rules|rules of the Review Board]].
-* Log in to the review board.  If it's the first time you use it, you have to create an account as well.
+* Log in to the Review Board.  It is using the KDE identity (if you do not have an account, you can get one from [http://identity.kde.org KDE identity], it is open to everyone)
 * Click on "New Review Request"
-* ??? In "Base Diff Path", put "trunk/" with the source directory where you generated the patch (ie where you executed "svn diff") appended
+* In Repository field, choose calligra
-* In Diff select the patch you want to upload
+* In Diff field select the patch you want to upload
-* After clicking on "Create a review request" you will have to add "calligra" in the list of group and a description
+* Optionally: in Parent Diff field, give a patch that needs to be applied before yours (this is only needed if the patch is based on an other patch from Review Board or on a branch different from master)
-* Don't forget to press "publish" at the top of the page
+* Click the "Create Review Request" button
+* Fill the Branch, Summary, Description, and Testing done fields
+* Add "calligra" in the Groups field
+* Add numbers of bugs (from bugs.kde.org) that are related to your patch to the Bugs field
+* Optionally: add specific people to the People field
+* Don't forget to press "Publish" button at the top of the page. You can do this later, when you're ready. Edited fields are saved for you.
+* After publishing Review Board sends email to the calligra-devel mailing list and other contributors can start reviewing
+* If you think about some specific person that should perform the review, ask specifically via email or IRC
+* You will be informed about any reviews that come to you. You will get either
+**"Ship It!" signal allowing you to push the patch to the Calligra git repository or
+**Notes on what to fix in the patch
+* When you improve your patch (it can happen several times) use the Update->Update Diff command to upload a new patch. Contributors will be notified about the update.
-For previous requests, see also the [http://reviewboard.kde.org/groups/koffice/ old KOffice SVN reviewboard page].
+== Automated creation of requests  ==
+If you happen to use reviewboard more often, automating the creation of review requests is useful. Refer to the [https://techbase.kde.org/Development/Review_Board#Using_post-review_to_post_changes_for_review Using post-review to post changes for review] section on KDE Techbase.