Xfce Wiki

Sub domains
 

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
dev:howto:contribute [2013/02/02 13:17] – [Low-Hanging Fruit] jannisdev:howto:contribute [2013/02/02 13:48] – [Contribution Process] jannis
Line 30: Line 30:
  
 ==== Contribution Process ==== ==== Contribution Process ====
 +
 +=== 1. Clone and branch ===
 +
 +When you start working on a fix or new feature, clone the relevant repository (e.g. Thunar) and branch off the main development branch (master):
 +
 +  git clone git://git.xfce.org/xfce/thunar
 +  cd thunar
 +  git checkout -b <your name>/<branch name>
 +
 +=== 2. Write code ===
 +
 +Work on your fix or feature in the branch you created. Important:
 +
 +  * Make sure to commit frequently.
 +  * Keep commits clean:
 +    * Make incremental, atomic changes (one aspect at a time)
 +    * Keep code working after every commit
 +    * Comment the code you write
 +    * Write commit messages using the standard Git message format
 +    * Don't fear the rebase (against master) to reorder, reorganize and rewrite your branch to keep it clean
 +
 +=== 3. Push ===
 +
 +Before submitting your changes for review, it is a good idea to push them to a public repository, e.g. on GitHub. This will make it easier for others to check out your branch and test it as part of their reviews.
 +
 +=== 4. Submit for review ===
 +
 +Submitting your changes for review is as simple as running a single Git command. In your branch, run:
 +
 +  git send-email --suppress-cc=self --annotate --cover-letter origin/master --to=xfce4-dev@xfce.org
 +
 +This will drop you in an editor where you are being asked to define a subject and a message for the patch set you are submitting. The editor window will roughly look like this:
 +
 +  From 451e2ab7ea3d595476ec5e57f33da8eef1661773 Thu Jan 10 08:30:27 2013
 +  From: Jannis Pohlmann 
 +  Date: Thu, 10 Jan 2013 09:25:18 +0100
 +  Subject: [PATCH 0/2] ***SUBJECT***
 +  
 +  ***MESSAGE***
 +  
 +  ... auto-generated git log and diff stats ...
 +
 +Fill out the SUBJECT and MESSAGE by briefly describing what you are submitting. Then save the file and close the editor. ''git send-email'' will send your patch set to the ''xfce4-dev@xfce.org'' mailing list in the form of the above cover letter email, followed by an additional email for each commit in your branch. These mails will each include the commit message and the commit diff as plain text.
 +
 +=== 5. Review ===
 +
 +Once submitted to ''xfce4-dev@xfce.org'', your patches will be reviewed by other Xfce developers. These reviews should include:
 +
 +  * Testing the changes.
 +  * Comments on:
 +    * Coding style and bad code design
 +    * Potential issues
 +    * Possible side-effects
 +
 +The reviews will be sent as replies to your cover letter and patch emails. Thanks to having the patches included in your submission as plain text, they can be commented on in-line.
 +
 +Reviews may be performed in multiple rounds. If your submission is rejected, you are advised to rework your branch and re-submit it using the same approach as described above. 
 +
 +=== 6. Merge ===
 +
 +Once you get an ok, one of the reviewers will pull your branch into the official repository and merge as follows:
 +
 +  git checkout master
 +  git merge --no-ff <your username>/<branch name>
 +  
 +This will result in an explicit merge commit, confirming in the git history that your changes have been merged.
 +
 +At the bottom of the merge commit message, the reviewer should add the following lines:
 +
 +  Signed-off-by: <your name> <your email>
 +  Reviewed-by: <reviewer 1> <reviewer 1 email>
 +  Reviewed-by: <reviewer 2> <reviewer 2 email>
 +  
 +These fields are defined in the [[http://www.kernel.org/doc/Documentation/SubmittingPatches|Linux kernel contribution guidelines]] and are used to confirm authorship and code reviews.