Contents
Staging notes
consolidated info from Finding tasks, Building & running the latest development code with JHBuild, Contributing code by submitting patches, Contributing code by submitting patches, Outdated Getting Started Guide, and Sindhu's Guide to GNOME contribution
- step by step guide/overview consolidated into one guide
- references more resources and provides examples
- provides definitions to 'basic' terms (bugs, submitting a patch, git, module, etc.)
to do: add General advice?
Guide to contributing code to GNOME
Welcome to the GNOME Love guide which provides step-by-step instructions on one way to contribute code: by solving a bug through submitting a patch. There are also many other ways to contribute to GNOME, and see the Get Involved page to explore non-coding contributions.
And if you ever have any questions, feel free to join in on the conversation on the IRC channel (#gnome-love on GIMPNet / irc.gnome.org) or reach out to any one of our friendly mentors.
Step 1: Learn your way around GNOME
If you haven't already, take the Project Tour to familiarize yourself with the many parts of GNOME. It will give you an overview of GNOME software, communication channels, and resources to get you started.
Step 2: Build and run the latest development code with JHBuild
Whether you want to try the latest features or contribute to the coding effort, using the latest development code is an essential step.
The recommended way to get the latest development code is through JHBuild, a software that compiles GNOME modules (a single term to include both libraries and programs) from source. GNOME applications are referred to as "modules" within JHbuild. See the GNOME Love introduction to JHBuild, which guides you through cloning the relevant Git repositories so that you can work on the code locally.
You can use JHbuild to keep an isolated development environment in your daily-use computer. This method is suitable for those who would like to keep their development environment and regular use operating system on a single computer.
Alternatively, you can use Git to manually clone the module that you are interested in:
$ git clone git://git.gnome.org/<module name>
Step 3: Find a bug to solve!
Solving problems that you encounter when using GNOME software is one way to start contributing code. These issues, called bugs, can be as minor as a button being too small to larger issues such as software closing abruptly or performing sluggishly.
These individual problems are described and filed through 'Bug Reports' in GNOME Bugzilla, the issue-tracking system. On Bugzilla you can report, track and discuss bugs, as well as submit and review solutions.
Find your personal itch
The best way to find things to work on is to use GNOME and identify things that you think need improving. Many GNOME contributors decide to work on certain bugs, features or non-coding contributions on their own, finding some problem or project that peaks their interest.
Once you've found something that you think needs improving, you can research the issue to see if other people agree that a change is necessary and to find the best solution to the problem. You can:
- Search the GNOME bug tracker to see if the issue has been reported as a bug. If it hasn't, you can report it yourself.
- Ask established GNOME contributors for their opinion on IRC [link]
- Investigate to see how other operating systems deal with the problem. Do they provide the feature that you want?
- Browse the wiki for information related to the problem.
Need help finding a bug to start with?
You can start with bugs that we've identified as good for newcomers are marked with the "gnome-love" keyword in Bugzilla. The gnome-love tag is used to indicate that the bug is relatively easy to fix and some assistance can be provided, given people's availability.
Also feel free to explore projects you're interested in the wiki and GNOME Bugzilla and explore its bug reports. Each software project has its own page on Bugzilla with its own list of "gnome-love" bugs. Click on the "gnome-love" link on a project page to see gnome-love marked bugs for that particular project. Or search it, for example, here are queries for GNOME Shell ''gnome-love'' bugs and GNOME Control Center ''gnome-love'' bugs.
GNOME goals also lists tasks that involve the whole of the GNOME project. They contain tasks that are great for beginners and a valuable way to contribute.
Step 4: Fix the bug
Now that you've identified your bug, you're ready to solve the problem or "fix the bug." The solutions to these problems are called "patches." When you are first starting, patches are the best way to contribute code to the GNOME project.
Following these guidelines will not only minimize the work for the maintainers, but also increase the chance of your patch being accepted. The guidelines on this page are generic and should more or less apply to every module; however, make sure to always follow any additional guidelines specified in the HACKING and README files included with the module you are working on.
If you're working on an existing bug, it is often worth adding a comment to the bug that you are working on it, especially if you expect the work to take some time.
* The following instructions will guide you through the steps, but interactivity is one of the best ways to learn. Read through this guide, then put everything you've learned into action with the Newcomers Tutorial, which walks you through the steps of submitting a patch to a sample module.
Due to the collaborative nature of the GNOME project, the case of multiple people making changes to source code may cause conflicts. To keep track of changes, also called "revisions," we use the Git Version Control System. For a detailed guide to using Git in GNOME, see the Git for GNOME developers guide. Make sure that you have followed the Git setup procedure before attempting to use it to create a patch.
Now that you're ready to fix your bug, you can walk through the following steps:
1. Download the source code of the project
- [elaborate]
2. Make your changes
- Provide one patch per issue, and don't make big patches that fix unrelated bugs
- Make sure to strictly follow the coding style used in the code you are working on. This may sound trivial, but consistency is very important. Many projects describe the preferred coding style in the HACKING file; for other projects just take a look at the surrounding code and try to use the same format.
- Use git diff --check to make sure the patch does not contain trailing whitespace and spurious empty lines
- Do not compress the patch with gzip or similar tools, since it makes reviewing more painful. If the patch is big enough to really require compression, chances are that you need to carefully discuss your patch with the maintainer.
3. Commit to save changes
- Did your commit message describe both what the patch does and how it does it? Great, let's move onto the next step!
Once you have made your changes, create a commit:
$ git commit -a
Here, the -a (meaning all) option includes all the changes you have made to the code in the new commit. You can also be more selective about what you include - the full guidelines contain details. The git commit command takes you to an editor where you can write a commit message.
Your commit message should follow a standard format: a short title, followed by a longer explanation, followed by a link to the relevant bug. Your commit message should look something like this:
Short title describing your change Longer description and explanation, if necessary. You might need to explain why you made the changes in the way that you did, for example. Bugzilla link
Here is an example of a good commit message (the first three lines are generated automatically):
commit d2ca14c270a8a0c01d8a897fad4ea2a9c2e31105
Author: Marc-André Lureau <marcandre.lureau@redhat.com>
Date: Sun Jul 17 21:18:04 2011 +0200
Add G_VALUE_INIT
The implementation of GValue is not public or documented. When
allocated on the stack, initializing a GValue is usually done as
documented with:
GValue value = { 0, };
There is lot code around (including WebKit) that added all the missing
fields, resulting in this ugly and non-obvious:
GValue value = { 0, { { 0 } } };
However, this doesn't play nice with -Wmissing-field-initializers for
example. Thus, G_VALUE_INIT.
http://bugzilla.gnome.org/show_bug.cgi?id=654793The commit message is good because it:
Has a concise summary of what the change is as the first line
Says why the change was made (avoid a gcc warning)
Gives a real-world concrete example of an affected codebase (WebKit)
Save and quit the editor when you are done (for vi, type :wq).
4. Create the Patch
This command creates a patch from your last commit:
$ git format-patch HEAD^
5. Submit your patch by attaching your file to the relevant bug report
- Unless explicitly stated in the HACKING file, do not send the patches privately to the maintainer.
If your patch is an enhancement and not a bug, you can create a new bug report with severity -> enhancement. Don't forget to attach your (Git) patch.
Step 5: Get your code reviewed
After uploading your patch, users who are interested in bugs and patches uploaded to that particular project will be notified via e-mail. Among these people, will be developers, maintainers and experienced contributors.
Your patch will likely go through several iterations of patch review. This kind of review process is standard practice within GNOME and helps to ensure that our code is all high-quality.
The reviewer may give you a full review or only review part of the patch indicating what issues you need to resolve first. A few common possible issues with a patch can be (but not limited to):
- Patch does not have a good commit message.
- Your changes are not complete.
- You changes have incorrect indenting, syntax and so on.
- Your changes give a solution that could introduce other problems.
You should then comment to confirm the review or ask for clarification if you need any help further resolving the issue, finding resources to improve the patch, or are encountering difficulty in correcting your changes
Step 6: Follow up with your review
If you've asked for review but the reviewer hasn't commented for several days, don't hesitate to ping them by adding a comment.
With the reviewer's comments, you can edit your patch and re-upload it. Wait for the review and repeat the procedure until the reviewer marks your patch with "accepted_commit-now" status. You will receive an e-mail notification about it. This indicates that the patch will be incorporated into the source code located on git.gnome.org.
Congratulations, you have now successfully made your first GNOME contribution!
Step 7: Repeat!
You're now ready to go to find another bug and repeat these steps. If you haven't already, you can put everything you've learned into action with the Newcomers Tutorial, which walks you through the steps of submitting a patch to a sample module.