Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionNext revisionBoth sides next revision | ||
dev:howto:contribute [2013/02/02 12:14] – created jannis | dev:howto:contribute [2013/02/02 16:06] – [Purpose of this document] jannis | ||
---|---|---|---|
Line 3: | Line 3: | ||
===== Purpose of this document ===== | ===== 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. Our aim should be to help them out with easy to find information that makes obvious | + | 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, for example, no easily accessible list of low-hanging fruit and tasks to get started with. Also, there is no well-defined and transparent contribution process. Our aim should be to make it obvious |
- | The two main hurdles (probably) are: | + | 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. |
- | * There is no easily accessible list of low-hanging fruit or tasks to get started with. | + | This document |
- | * There is no defined, transparent contribution process. | + | |
- | These hurdles make it difficult for potential contributors to know how they can contribute and what they could contribute in the first place. | + | ===== Present State ===== |
- | The purpose | + | ==== Documentation on Contributing ==== |
+ | |||
+ | The [[http:// | ||
+ | |||
+ | * [[http:// | ||
+ | * [[http:// | ||
+ | * [[http:// | ||
+ | |||
+ | 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, | ||
+ | |||
+ | ==== Current Contribution Process ==== | ||
+ | |||
+ | The current recommended (but undocumented) way to get started essentially is: subscribe to [[https:// | ||
+ | |||
+ | ===== 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:// | ||
+ | cd thunar | ||
+ | git checkout -b <your name>/< | ||
+ | |||
+ | === 2. Write code === | ||
+ | |||
+ | Work on your fix or feature in the branch you created. Important: | ||
+ | |||
+ | * Make sure to commit frequently. | ||
+ | * Make sure to pull in the latest Xfce master frequently. | ||
+ | * Keep commits clean: | ||
+ | * Make incremental, | ||
+ | * 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 the Xfce master branch). | ||
+ | |||
+ | === 3. Push === | ||
+ | |||
+ | Before submitting your changes | ||
+ | |||
+ | === 4. Submit for review === | ||
+ | |||
+ | Submitting your changes for review is as simple as running a single command. In your branch, run: | ||
+ | |||
+ | git send-email --suppress-cc=self --annotate --cover-letter origin/ | ||
+ | |||
+ | 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. '' | ||
+ | |||
+ | **Configuring '' | ||
+ | |||
+ | You will need to configure | ||
+ | |||
+ | git config --global sendemail.smtpserver mail.example.com | ||
+ | git config --global sendemail.smtpserverport 25 | ||
+ | |||
+ | If you need encryption to use your mail server, set: | ||
+ | |||
+ | git config --global sendemail.smtpencryption starttls | ||
+ | |||
+ | If you need to log in to your server, you can set the user name in the config and then git send-email will prompt you for the password during the sending | ||
+ | |||
+ | git config --global sendemail.smtpuser yourmailusername | ||
+ | |||
+ | You need to teach git send-email | ||
+ | |||
+ | git config --global sendemail.from "$(git config user.name) <$(git config user.email)>" | ||
+ | |||
+ | === 5. Review === | ||
+ | |||
+ | Once submitted to '' | ||
+ | |||
+ | * 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> | ||
+ | |||
+ | This will result in an explicit merge commit, confirming in the git history that your changes have been merged. | ||
+ | |||
+ | At the bottom | ||
+ | |||
+ | Signed-off-by: | ||
+ | Reviewed-by: | ||
+ | Reviewed-by: | ||
+ | |||
+ | These fields are defined in the [[http:// |