This is an old revision of the document!
Contributing to Xfce
Purpose of this document
At the time of writing (FOSDEM 2013), the entry barrier for contributing to Xfce is substantially higher than it could be. There are several hurdles that people have to figure out themselves. There is no easily accessible list of low-hanging fruit or tasks to get started with. Also, there is no defined, transparent contribution process. Our aim should be to make obvious to interested developers how they can contribute and what they can contribute.
The purpose of this document is to come up with a concept for providing low-hanging fruit to the developer community and a contribution process that removes uncertainty about what the right way/format of contributing code is. This document is only about contributing code since other areas, like translations, are already well documented.
Present State
Documentation on Contributing
The Get Involved page on the Xfce website has no information about contributing code at all. There is no documentation describing the contribution process. Possible tasks to work on are scattered across various areas of the Xfce wiki. Unless you know the wiki inside-out, you'll have a hard time finding these pages:
- Design SIG - working on improving the user experience of Xfce.
- Component wish list - populated by our users.
- Panel plugin wish list - populated by our users.
The Design SIG is an initiative that Xfce developers and designers use to collaborate on improving the user experience of Xfce in general. It's been quite successful in the last 1-2 years. However, the majority of Design SIG topics are complex and thus not necessarily useful for people looking to start contributing to Xfce.
The two wish lists are, unfortunately, rarely used by developers, if at all, so their usefulness is questionable.
Current Contribution Process
The current recommended (but undocumented) way to get started essentially is: subscribe to xfce4-dev@xfce.org, join us in #xfce-dev on IRC and start by fixing bugs filed on http://bugzilla.xfce.org. Code can be attached to bugs in the form of patches but that is up to contributors to figure out themselves and the desired patch format (ideally patches generated by git, with commit messages included) is not documented anywhere.
Proposals
Presenting Low-Hanging Fruit
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 Mon Sep 17 00:00:00 2001 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 the cover letter to the xfce4-dev@xfce.org
mailing list, followed up by one mail per commit in your branch. These commit mails will each include the commit message and the commit diff as plain text.