How to Contribute to GNOME

GNOME is one of the leading open source organisations in the world. A lot of people work for it, fixing bugs, implementing new features, etc. Since people use various platforms for this, here’s a simple guide to installing the source code for GNOME on different platforms. Also learn how you can begin with your first contribution towards open source using GNOME and a few of its developer tools. You can contribute to different parts such as the GNOME shell, GNOME-music, GNOME-games, Evolution, Evolution data server, etc.

Hardware requirements
While installing the GNOME source code, you first need to install its dependencies. The minimum hardware requirements for the build are:

• 2GB RAM and a lot of free space
• To debug and to build: At least 8GB of free space
• For optimised builds: At least 1GB of free space (6GB recommended)

Build tools and dependencies

In GNOME, it is not necessary to have the dependencies. You only need to install JHBuild, which is a tool developed and used to build the whole GNOME desktop from the Git source. It can also be used to build other projects, creating a moduleset for it. Unlike some build scripts, JHBuild lets you specify what modules you want to build and, accordingly, it will build those modules, including the dependencies. JHBuild is preferred by developers who install GNOME from source.

Installing JHBuild
JHBuild helps users by making the installation process much easier. It needs the Python runtime environment, with version 2.3 as the least recommended.
The recommended way of downloading JHBuild is via the Git version control system. This can be done with the following command. It is recommended that you run the command from a new directory where all the source code will be installed, for example, ~/jhbuild/checkout.

git clone git://git.gnome.org/jhbuild

This will download JHBuild into a new folder named JHBuild under the current working directory. To build and install JHBuild, use the following commands:

cd jhbuild
. . . .
./autogen.sh
. . . .
make
. . . .
make install

If gnome-common, Yelp-tools and Autotools are available, autogen.sh will configure JHBuild to install via Autotools. If the three are not available, autogen.sh will configure JHBuild to install them via a plain Makefile. To always use the plain Makefile method, pass –-simple-install to autogen.sh

If the above steps complete successfully, a small shell script will be installed in ~/.local/bin to start JHBuild. For the script to run, you need to add ~/.local/bin to the PATH.

PATH = $PATH:~/.local/bin

To permanently add ~/.local/bin to the PATH variable, run the following command:

echo ‘PATH = $PATH:~/.local/bin’ >> ~/.bashrc

JHBuild prerequisites

Before any modules can be built, it is necessary to have certain build tools installed. Common build tools include the GNU Autotools (autoconf, automake, libtool and gettext), the GNU toolchain (binutils, gcc, g++), make, pkg-config and Python, depending on which modules will be built. JHBuild can check the tools installed using the sanitycheck command:

jhbuild sanitycheck

If this command displays any messages, please install the required packages from the distribution’s repository. A list of package names for different distributions is maintained on the GNOME wiki. Run the sanitycheck command again after installing the distribution’s packages to ensure the required tools are present.

Using JHBuild
After the set-up is complete, JHBuild can be used to build software. To build all the modules selected in the ~/.config/jhbuildrc file, run the following command:

jhbuild build

JHBuild will download, configure, compile and install each of the modules. If an error occurs at any stage, JHBuild will present a menu that asks you what needs to be done. The choices include dropping to a shell to fix the error, rerunning the build from various stages, giving up on the module, or ignoring the error and continuing.

Note: Giving up a module will cause other modules that depend on it to fail.

Shown below is an example of the menu displayed when you get an error message:

  [1] Return phase build
  [2] Ignore error and continue to install
  [3] Give up on module
  [4] Start shell
  [5] Reload configuration
  [6] Go to phase “wipe directory and start over”
  [7] Go to phase “configure”
  [8] Go to phase “clean”
  [9] Go to phase “distclean”
choice:

It is also possible to build a different set of modules and their dependencies by passing the module name as arguments to the build command. For example, to build gtk+, use:

jhbuild build gtk+

If JHBuild is cancelled half way through a build, it is possible to resume the build at a particular module using the –start-at option:

jhbuild build --start-at = module-name

To build one or more modules, ignoring their dependencies, JHBuild provides the buildone command. For the buildone command to complete successfully, all the dependencies must be previously built and installed or provided by the distribution package.

jhbuild buildone gtk+

When actively developing a module, you are likely to do so in a source working directory. The ‘make’ will invoke the build system and install the module. This will be a key part of the edit-compile-install-test cycle.

jhbuild make

If JHBuild is cancelled half way through a build, it is possible to resume the build at a particular module using the –start-at option. To get a list of the modules and dependencies JHBuild will build and the order in which they will be built, use the list command:

jhbuild list

To get information about a particular module, use the info command:

jhbuild info module-name

To download or update all the software sources without building, use the update command, which provides an opportunity to modify the sources before building, and can be useful if Internet bandwidth varies:

jhbuild update

Later, JHBuild can build everything without downloading or updating the sources:

jhbuild build --no-network

To run a particular command with the same environment used by JHBuild, use the run command:

jhbuild run program

To start a shell with the same environment used by JHBuild, use the shell command:

jhbuild shell

Looking Glass (lg): A developer tool

Looking Glass (lg) is GNOME Shell’s integrated inspector tool and JavaScript console, which is useful for debugging. To access looking glass, type lg in the Alt+F2 prompt. To exit from this, you can just press the Esc key.
Looking Glass has four major panes (Evaluator, Windows, Errors and Extensions) and one tool (the Picker).
Evaluator: This is an interactive JavaScript prompt. You can type arbitrary JavaScript at the prompt, and it will be evaluated. Try, in order:

1+1
global.get_window_actors( )
global.get_window_actors( ).forEach(function (w) {Tweener.addTween(w, {time:3,   transition: ‘easeOutQuad’, scale_x: 0.3, scale_y: 0.3 } ) } )
global.get_window_actors( ).forEach(function (w) {w.set_scale(1, 1) } )
global.get_window_actor( ) [0]
it.scale_x

Special Evaluator features: This last bit deserves more explanation. One thing about the Evaluator that’s different from, say, Python’s default interactive prompt is that each computed value is saved, by default, and can be referred back to. Typing ‘r (number)’ will get you back the result with that number, and it is the last result.
The evaluator also has a history feature; you can press Up and Down to access previously used entries. The history is automatically saved to the dconf key /apps/gnome-shell /looking-glass-history, and loaded when you restart the shell.
Slowing down shell animations: You can use Looking Glass to call the special function St.set_slow_down_factor(factor) where ‘factor’ is a value greater than 1 to make all shell animations slower. This is particularly useful when implementing new animation behaviour.
The Picker: The Picker allows you to visually select any object from the shell’s scene. When you do so, it is inserted as a result into the Evaluator pane.
Getting started with your first contribution
Now, after building the source code of the particular module, you can start with your first contribution. This process basically consists of going through the source code and finding that part of the code responsible for the bug. For help, you can contact the GNOME developers on the IRC.
Connecting to the GNOME IRC
If your browser is Mozilla Firefox, then you can install the ChatZilla extension for the IRC, which is basically an IRC client developed by Mozilla. If you are not interested in using ChatZilla, you can try IRCCloud, Mibbit or XChat based on what suits you. The next step is to connect to the GNOME IRC server. For this, connect to the GNOME server by using the following command:

/server irc.gnome.org

Once you are connected to their IRC server, you can join a channel where you can get help for the bug. To join a channel, just type:

/join #channel-name

After you connect to any channel, you can start asking questions regarding the bug or about anything else too.

Starting with the first bug fix in GNOME

Once you are ready with the build, go to Bugzilla to search for bugs. As a beginner, it is recommended that you start with minor or trivial bugs. Once you find a bug, just mention that you are interested in working on this bug in the ‘bug comments’ section. After some time, you will get that bug assigned to you. Once you are done with selecting a bug, you can ask for any help regarding the bug in #gnome-love on the IRC. After you have fixed the bug, you have to make a patch, for which you have to use Git.
Submitting a patch using Git
Commit a patch: After you’ve made changes to the code, you are ready for a patch. For this, you need to commit the changes you have made locally.

git commit -a

In this command, -a means all the changes. The Git commit command takes you to an editor where you can add the 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 changes to the code. 
            Longer description and explanations if necessary. 
            Bug link

Create a patch: To create a patch you need to give the following command:

git format-patch HEAD^

Submit a patch: Send the patch to the project by attaching it to the relevant bug report in GNOME Bugzilla. Unless explicitly stated in the patch 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.
Tips for creating a patch

• In your commit messages, describe both what the patch does and how it is done, unless the patch is very trivial.
• 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 patch file; for other projects, just take a look at the surrounding code and try to use the same format.
• Avoid unrelated changes. This makes the patch easier to read and approve.
• Provide one patch per issue. Do not make big patches that fix unrelated bugs.
• Make sure the patch does not contain trailing whitespace and spurious empty lines. You can use git diff –check for this.
• 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 anyway.

References
[1] https://wiki.gnome.org/GnomeLove/SubmittingPatches
[2] https://wiki.gnome.org/action/show/Projects/Jhbuild