Chapter 13. Contributing to Eclipse

Making Eclipse better – one commit at a time

Now that you know how to write plug-ins and do development and testing inside Eclipse, you can fix issues and create new features for the Eclipse platform. This chapter shows how to work with Eclipse's source, create bugs with the Eclipse bug tracking system, and submit changes into Gerrit at Eclipse.

In this chapter, we shall:

• Import the source of plug-ins through the plug-in view

• Check out projects from Git

• Raise bugs in the Eclipse bug-tracking system

• Submit changes to Gerrit

Open source contributions

Eclipse is an open source code base, and has been written by thousands of individuals across the years. The Eclipse Foundation are the stewards of the code, but the foundation staff themselves are few in number and generally do not write the code for Eclipse itself; rather, they look after the ancillary services (bug tracker, git and Gerrit source code repositories, news groups, wiki, and website) and the EclipseCon and DevoxxUS conferences around the world (http://eclipsecon.org, http://devoxx.us). There are commercial companies who build their products on Eclipse and contribute to the underlying platform, but there are many open-source volunteers who contribute their time and effort to improve Eclipse. This chapter will show you how you can make a contribution to Eclipse by checking out a repository, raising a bug, and filing a patch.

Importing the source

Eclipse ships with source code for the provided plug-ins with the Eclipse SDK and the Eclipse IDE for Committers...

Time for action – installing the sources

In order to be able to see the source for a particular plug-in, it needs to be installed. This is achieved using the same installation dialog that has been covered previously in this book.

1. Go to Help | Install New Software and choose the repository that is associated with the release of Eclipse that is being used:

   • http://download.eclipse.org/releases/neon/

   • http://download.eclipse.org/releases/mars/

2. Ensure that the Group items by category checkbox is deselected. This will show all plug-ins, not just the main ones. Typically the source plug-ins are not shown in the main listing. In addition, deselecting this checkbox will result in a faster search in the next step.

3. Optionally deselect the Hide items that are already installed checkbox. This will ensure that the plug-ins show up even if they are already installed.

4. Search for source in the search box. This will result in a set of plug-ins being shown:

   

5. Select the following plug-ins and then click on Finish...

Time for action – debugging the platform

To debug the platform, make sure that at least one plug-in project is open and that it depends on the plug-ins that need to be debugged. This allows the editor to be opened for any of the classes for debugging.

1. Ensure that a plug-in that uses the Eclipse UI is open in the workspace, such as com.packtpub.e4.hello.ui or com.packtpub.e4.clock.ui. This will ensure that the platform classes are available.

2. Use the Navigate | Open Type menu or press Ctrl + Shift + T (Cmd + Shift + T on macOS) to open the Open Type search dialog. Type in Shell and select the Shell from the org.eclipse.swt.widgets package. Double-click or click on OK to open the file.

   Tip

   If the source code isn't shown, verify that the Eclipse Platform Plug-in Developer Resources plug-in has been installed and that there is an open plug-in project that depends on org.eclipse.ui or org.eclipse.swt. If the Open Type menu isn't shown, switch to the Java perspective or the Java Browsing perspective...

Time for action – modifying the platform

Once the location of interest has been found, it is necessary to modify the code to attempt a fix. For example, if the developer wanted to ensure that the window's title was all in upper case, it would be necessary to inject a title.toUpperCase() call. However, since the .class file is read-only, it is necessary to import the plug-in's source into the workspace to change the implementation.

1. Using the Window | Show View | Other… menu or the Quick Access box, open the Plug-ins view from the Plug-in Development category. This will show a list of all plug-ins installed into the system.

2. Type org.eclipse.swt to scroll down the list, and select both the org.eclipse.swt bundle and the org.eclipse.swt.* fragment that corresponds to the platform. For example, on macOS this will start with org.eclipse.swt.cocoa, while on Windows it will start with org.eclipse.swt.win32; and on Linux, org.eclipse.swt.gtk:

   

3. Right-click on the selected items and choose Import As |...

Time for action – checking out from EGit and Git

Eclipse's version control system of choice (and indeed, of many sane people's choice) is Git, the canonical distributed version control system for open-source projects. The EGit implementation in Eclipse is bundled by default for almost all of the standard packages, although it doesn't exist in the SDK package. The git command-line client is available for most operating systems and can be downloaded from http://git-scm.com.

1. It may be necessary to install the Eclipse Git team provider, but most packages of Eclipse come with EGit built in. If not, it can be installed using the Help | Install New Software... menu; select the main Eclipse repository for the release (Neon, Mars, and so on) and search for git. Install the Eclipse Git Team Provider from the Collaboration group:

   

2. Restart Eclipse to complete the installation process.

3. Since the org.eclipse.swt projects were imported from a source snapshot in the previous section, they need to be deleted...

Time for action – configuring the SWT project

There are a couple of extra steps that are specifically required in order to work with SWT. The first is setting up the main SWT project for the specific operating system, and the second is obtaining the pre-compiled native libraries that are required in order to communicate with the operating system.

1. Firstly, the project's platform-specific .classpath needs to be copied (or symlinked) so that the project compiles. Since SWT has a number of platform-specific elements, they need to be referred to in the classpath. In the root of the org.eclipse.swt project, there are three files: .classpath_cocoa (for macOS), .classpath_gtk (for Linux), and .classpath_win32 (for Windows). Copy or symlink the appropriate one to .classpath in order to compile the project.

   Tip

   On Windows, Explorer may not be able to display or rename files that start with a dot character. Use either the command prompt and rename or copy commands, or use Eclipse's Navigator view (which...

Contributing to Eclipse

Creating a bug fix and offering it to a project is a great way to make contributions to Eclipse. This section will show how to get involved and get to the stage where it's possible to file bugs and fixes against an upstream Eclipse project.

Creating bugs on Bugzilla

As an open source project, everything starts with a bug. Eclipse uses Bugzilla, an open source bug tracking tool initially created by Mozilla to manage bugs for their web browser.

Time for action – creating an account at Eclipse

All Eclipse foundation systems use the same account information, including name and e-mail address. In order to participate in the Eclipse foundation systems, an account is required.

1. Go to the https://dev.eclipse.org/site_login/ page to create an account. This contains the terms of use (visible at http://www.eclipse.org/legal/termsofuse.php) and the privacy policy (visible at http://www.eclipse.org/legal/privacy.php).

2. There are additional options which may be relevant, such as signing up for the Eclipse newsletter and an explicit checkbox to say that you have read the terms and privacy policy. This sign-up page may change from time to time.

3. Click on the Create Account button and a new user account will be created with the given name and e-mail address. There may be an additional e-mail confirmation step to verify that the e-mail address step is correct.

4. Once the account is created, log in to the site at https://dev.eclipse.org/site_login/ to verify...

Time for action – creating a bug

Reporting bugs in Eclipse is a simple way of getting involved. These steps will use the example of the title case of SWT as an example, although this is not likely to be accepted as a real bug!

1. Open a web browser and go to https://bugs.eclipse.org in order to create a bug. It may be necessary to log into the account if the option is not set. It may be beneficial to uncheck the Restrict this login session to this IP address, as otherwise if the computer's IP address changes, then it will be necessary to log in again.

2. Once logged in, a File a Bug button will be displayed; alternatively the new link at the top of the page will allow a bug to be created.

3. The Eclipse bug wizard will show the steps necessary to create a bug. The form will guess the operating system and hardware type based on the browser information, but for non-OS-specific bugs such as documentation, these should be set to All.

4. The bugs are categorized into different areas; Technology contains general...

Time for action – setting up a Gerrit profile

Gerrit is a distributed version control system review tool that can be used to upload patches for review and ultimate merging with the repository. It provides a Git interface and acts as a remote Git server, so using it with existing tools or command lines is trivial.

1. Navigate to the Gerrit user interface at https://git.eclipse.org/r/ and ensure that the profile is correctly set up. The name and e-mail address will be taken from the information provided when creating the Eclipse account.

   Note

   A password is required in order to push changes to Gerrit. This can be done either through a Gerrit-specific randomly generated HTTP password, or through an uploaded SSH key. Note that while the e-mail address and login details used to access Gerrit are the same as for Bugzilla, for pushing changes through Git a different password is used.

2. An HTTP password can be generated by going to https://git.eclipse.org/r/#/settings/http-password and clicking on the Generate...

Time for action – committing and pushing a patch

To submit patches to Gerrit, the change must first be committed locally, and the remote repository pointed to Gerrit. Then the change can be pushed and the builds triggered.

1. When committing for the first time, Git will ask for a user name and an e-mail address. That's because changes in Git are associated with a name and e-mail address and nothing else. In Eclipse, triggering a commit will bring up a dialog asking for these details; alternatively they can be specified in the Preferences | Team | Git | Configuration panel under the user.name and user.email values. Alternatively the git command line can be used to set them, using:

   $ git config --global user.name "My Name"
   $ git config --global user.email "[e-mail]"

2. The change can be committed in Eclipse by right-clicking on the project (or folder) and choosing Team | Commit. This will show a dialog or view of information where the details can be entered. The general Eclipse practice...

Summary

The first step in getting involved with the Eclipse projects is understanding how they work. The Eclipse plug-ins all come with source code and the IDE is self-sufficient for debugging and developing plug-in code. It's possible to view this source code for debugging purposes or to import the source code for modification processes, without needing to talk to remote Eclipse sites.

However, being able to fix bugs and provide patches upstream helps improve Eclipse for everyone; and once the fix has been identified, using Bugzilla to create a bug and Gerrit to receive the patch is the next logical step.

This chapter has shown how to follow all of these steps to be able to contribute to Eclipse. The rest is up to you.