This tutorial explains how to contribute to the Eclipse open source project for the Eclipse IDE.
1. Contributing to the Eclipse open source project
1.1. Code contributing
The development of the individual Eclipse projects is done by the Eclipse developers - companies and individuals alike - which develop the code.
As the Eclipse project is an open source project, it is possible to get the source code, modify it and provide the change back to the project. Most Eclipse projects use a code review process based on the Gerrit code review system. Some Eclipse projects also use Github for code contributions.
Contributing to an Eclipse project has the benefit of getting feedback directly from the core developers. It also allows developers and organizations to fix bugs which affect them and to drive the project into a desired direction.
This $book focuses on the process of contributing code to an Eclipse project. If case you do not want to contribute code, there are other ways of contributing, e.g., via updating the project documentation, but these are not covered here.
1.2. User interface guidelines
Eclipse has a description for its user interface guidelines. See Eclpise UI guidelines Wiki.
It is not expected that you read this UI guide completely. But in case you want to check what the Eclipse way of doing things is, you can have a look at this (old but still valid) description.
1.3. Users, Contributors and Committers
The Eclipse project distinguishes between the following group of people:
Eclipse User - Using at least one product, e.g., a JAR file, of the Eclipse project. Eclipse users consume the software created by the Eclipse developers. Users also report bugs and issue feature requests in Eclipse projects they are using.
Contributors are individuals who contribute code, fixes, tests, documentation, or other work that is part of the project.
Committers have write access to the project’s resources (source code repository, bug tracking system, website, build server, downloads, etc.) and are expected to influence the project’s development.
Everyone has read access to the code repositories hosted at eclipse.org.
1.4. Relevant Eclipse projects
Eclipse hosts multiple projects but several projects are critical for the development of the Eclipse IDE and RCP applications. These are described here.
1.4.1. The Eclipse Platform project
The Eclipse Platform project provides the core frameworks and services upon which all Eclipse based applications are created. It also provides the runtime in which Eclipse components are loaded, integrated, and executed. The primary purpose of the Eclipse Platform project is to enable other developers to easily build and deliver integrated tools and applications.
1.4.2. The Eclipse Plug-in Development Environment (PDE)
The Eclipse Plug-in Development Environment (PDE) project provides wizards for creating Eclipse RCP applications and plug-ins, editors and other tools to develop Eclipse plug-ins.
1.4.3. The Eclipse e4 project
Eclipse e4 is the name used for the Eclipse Platform incubator project. This incubator is used for exploratory projects relating to improving the Eclipse Platform.
The e4 project includes several technology evaluations. Some of these evaluations have been ported back to the core Eclipse framework. All functionalities described in this document are part of the official Eclipse release, except the Eclipse e4 tooling project.
The Eclipse e4 tooling project provides tools for developing Eclipse 4 applications. They are very useful, but have not yet been added to any main Eclipse project.
This tutorial assumes that you have already Eclipse plug-indevelopment experience. See the Eclipse Plug-in development tutorial for details.
2. The Eclipse foundation and the Eclipse public license
2.1. Eclipse foundation
The Eclipse projects are governed by the Eclipse Foundation. The Eclipse Foundation is a non-profit, member supported corporation that hosts the Eclipse Open Source projects. It helps to cultivate both its open source community and its ecosystem of complementary products and services.
The Eclipse Foundation does not work on the Eclipse code base, i.e., it does not have employee developers working on Eclipse. The mission of the Eclipse Foundation is enable the development by providing the infrastructure (Git, Gerrit, Hudson build server, the download sites, etc.) and a structured process. Eclipse projects follow a very well defined development process. To learn more about this process see the Eclipse development process description.
There is also an Eclipse Foundation Europe based in Germany.
In 2016 the Eclipse Foundation had approximately 30 employees. See Eclipse Foundation Staff for details.
2.2. The Eclipse Public License
The Eclipse Public License (EPL) is an open source software license. The EPL is designed to be business-friendly. EPL licensed programs can be used, modified, copied and distributed free of charge. The consumer of EPL-licensed software can choose to use this software in closed source programs.
Only modifications in the original EPL code must be released as EPL code. This can for example be done by filling a bug report at the public Eclipse bug tracker and by uploading a Gerrit change.
The Eclipse Foundation validates that source code contributed to Eclipse projects is free of intellectual property (IP) issues. This process is known as IP cleansing. Contributions with more than 1000 lines of code require the creation of a Contribution Questionnaire, and a review and approval by the IP team.
The permissive EPL and the IP cleansing effort of the Eclipse Foundation makes reusing the source code of Eclipse projects attractive to companies.
3. Finding information about an Eclipse project
3.1. The Eclipse project page
Eclipse lists all project repositories under their project page. This page can be found via the main Eclipse projects page.
Use the project page you can search for an Eclipse project. The individual project page includes information about future developments plans, documentation, wiki pages, developer mailing lists and the project charter. If you click on the Learn more in one of the search results you are taken to the project homepage. Click on the Developer resources tab to see all Git repositories of the project.
The following screenshot depicts the website for the JDT UI project.
3.2. Example: Finding the Git repositories for the Eclipse Platform UI project
The Eclipse platform UI project is responsible for the user interface, runtime, text and user assistant components of the Eclipse platform. In this example search for "Platform UI".
image::eclipsegitrepos10.png" scale="30[Eclipse Platform UI search result,pdfwidth=60%]
Click on the Learn more link and select the Developer resources tab.
3.3. The Eclipse dashboard
The Eclipse foundation provides also Dashboards.
For example http://dashboard.eclipse.org/its-contributors.html gives an overview of Eclipse contributions. The dashboard allows you to drill down as depicted in the following screenshot.
|The URL and appearance may still change over time. See Bug 405792 for details.|
image::eclipsedash10.png" scale="30[Project members dash,pdfwidth=60%]
You can select in the top the sub-project to see. For example the reporting for the Eclipse project is depicted in the following screenshot.
image::eclipsedash20.png" scale="30[Eclipse project dashboard,pdfwidth=60%]
4. Installation description
4.1. Download the latest integration build
You can download the latest integration build from the Eclipse developer builds webpage. This webpage is despicted in the following screenshot.
This is sometimes necessary to test the latest features or to test a build which is later promoted to M or RC build by the Eclipse platform team.
For most Eclipse projects, you can also use the Eclipse installer. See [usingtheinstaller]. The installer will also perform additional configuration and install additioanl plug-ins.
4.2. Install the Git tooling into the Eclipse IDE
After you downloaded a recent build for the Eclipse IDE, you should at least install the Eclipse Git tooling.
5. Exericse: Eclipse user creation and Gerrit server configuration
5.1. Create an Eclipse user account
To contribute to an Eclipse project you need to have valid user credentials. If you already have an Eclipse Bugzilla or Eclipse Forum account, you have already done this step. These systems use the same account.
You can create a new user via the following: Create Eclipse.org user account.
5.2. Sign the Contributor License Agreement (CLA)
You also need to confirm to the Eclipse foundation that you have the right to contribute your code to the Eclipse open source project. This requires that you sign an Eclipse license agreement (ELA) via a web interface of your user you created.
Eclipse.org user account and click on the Eclipse ECA tab.
The Eclipse ELA FAQ describes the process and purpose of the CLA. At the end this document contains a link for signing the CLA.
|In case you contribute to the Eclipse projectduring your work time, ensure that your employer agrees that the code can be contributed.|
5.3. Configure your Eclipse Gerrit user
You need to configure Gerrit if you want to use SSH or HTTPS to upload your contributions. The Gerrit user is NOT the same as your Eclipse user. Also, the Gerrit HTTPS password is NOT the same as your Eclipse user password.
To configure your access method open the Gerrit at Eclipse URL and and login with your Eclipse account. This can be done via your registered email address and password via the top right corner of your browser.
Afterwards select Settings as highlighted in the following screenshot.
You can either use SSH or HTTPS to push to Gerrit. See Authentication via HTTPS for the configuration of HTTPS and Authentication via SSH for the configuration of the SSH access. If you are not familiar with SSH, the HTTPS authentication is most likely easier to configure for you. If your company is using a proxy, you may have to use HTTPS as a proxy might block SSH.
5.4. Authentication via HTTPS
The web page of the Gerrit review system enables you to generate an HTTP password. Select the HTTP password in the Gerrit user settings and generate a password. This setting is depicted in the following screenshot (the password is obfuscated).
Take note or copy the password, as it will be needed to push your changes to the Eclipse Gerrit system. In contrast to SSH, when using HTTPS you will have to enter your password for each operation with Gerrit. You can visit this page later if you forgot the password.
5.5. Authentication via SSH
You need to upload your SSH key to the Gerrit installation so that you can push changes to Gerrit via SSH. Once you have created a SSH key pair, upload your public SSH key to Gerrit to be able to push to it.
6. Clone the selected Eclipse Git repository
6.1. Finding the correct Git repository
Ensure you are logged into the Gerrit server webpage. This will enable you to use SSH or HTTPS for cloning the repository.
Go to the Gerrit Eclipse homepage and select the menu entry. This opens the Project search page. Here you can search for the project you want to contribute to. In our example we want to contribute to the platform.ui project.
Select the correct project. This opens a new webpage. This page contains links for cloning the Git repository. The selection for HTTPS is depicted in the following screenshot. Please note that the URL for you is different, as it contains your user name.
6.2. Clone the repository via the Eclipse IDE
To clone, select.
Enter the URL from the Gerrit webpage in the first line of the wizard. The Eclipse Git tooling removes "git clone" from the clone URI automatically.
Note that the URL automatically includes your user name. This makes it easier to push a change to the Eclipse Gerrit review system. If you clone the repository using the Eclipse Git functionality, your local repository is already configured to push changes to Gerrit, no additional setup step is required. The following screenshot shows this selection, please the depicted user name with yours.
On the next wizard page you can select to clone all branches.
The Eclipse platform project uses the
master branch for all bug fixes and feature work.
Individual bug fixes are downported to maintenance branches but you should always first fix the issue in the master branch.
Finish this wizard by selecting the Next button until you the option Finish option becomes available. You end up with the projects from the repository imported into your workspace.
|You can also clone anonymously via Anonymous HTTP , if you just want to play with the source code locally and do not intend to contribute changes. In case you cloned a Git repository without using the Gerrit URL or not via Eclipse Git you have to adjust the push URL to provide Gerrit changes. See [eclipsegerritcontribution_adjustpush] for a description how to do that.|
7. Exercise: Install required plug-ins and configure your workspace
7.1. Exercise: Install additional plug-ins via install file
The Eclipse Platform UI team provides a file describing all the plug-ins typically needed for platform development. You can download from the following link this file, stored under version control: http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiTools.p2f
To install all the development plug-ins import the p2f file via themenu path.
7.2. Configure API baseline
Eclipse projects frequently needs to ensure that they do not break API, compared to the previous release. For this the API tooling is used, and a missing API baseline is reported as error.
Handling baseline issues and API is something which the core committers can help with. New contributors can set this error message to warning to have an easy start. This setting is highlighted in the following screenshot.
To define and use an API baseline, you need to download and install an official released version of Eclipse. This installation defines your baseline for the API, and you can specify its location in the Eclipse preferences. For this select themenu entry. Here you can define the Eclipse release to use as baseline. With this system, Eclipse can report API breakage by comparing the code in your workspace with the last released code.
For example if you develop for the next Eclipse 4.x+1 release (for example 4.7), you should select the official Eclipse release (for example Eclipse 4.6.1) as API baseline. This way the Eclipse API baseline tooling can check if you break the existing API and if you do this adds error or warning markers to your code. The tooling can also propose quickfixes for such violations.
The following screenshots demonstrates how to configure a API baseline. This assumes that the 4.5 is the latest official release. In the preference press the Add Baseline… button.
Enter a name for this baseline, select the folder which contains the latest official Eclipse release and press the Reset button to use this installation as baseline.
7.3. Closing projects
Sometimes a plug-in give you error messages, which you can’t solve. For example, if the plug-in is specific to the Windows operating system API and you are using Linux, you get compiler errors for it.
In this case, right-click on the project and select Close Project from the context menu. This instructs the Eclipse IDE to ignore this plug-in in your workspace.
7.4. Setup for other Eclipse projects
If you planning to contribute to another Eclipse project, please have a look at their contribution guide. This guide is typically available via the project website, which can be found via the search functionality of the https://projects.eclipse.org">Eclipse project side .
8. Exercise: make a change and push a review
8.1. Make a code change
Find a very simple change for your first contribution. For example fix a typo or a compiler warning. Eclipse projects frequently tag bugs with the keyword bugday or helpwanted , these are candidates for initial contributions.
8.2. Push to the Gerrit review system
Use the Git Staging view to commit your change and to push it to the Gerrit review server.
You need to sign off every commit. The Git functionality in Eclipse simplifies that via the sign-off push button. The Add Change-Id push button allows you to include a Change-Id entry to the commit message. Both buttons are highlighted in the following screenshot.
The Change-ID entry is initially set to "Change-Id: I0000000000000000000000000000000000000000". During the commit, this is replaced with an ID generated by the Git tooling. Like other Git IDs it is a SHA1 over the content of the commit and the letter 'I' is added a prefix to make it obvious that it is a Gerrit Change-Id and not a Git commit ID.
To get picked up by Gerrit, the Change-Id must be in the last paragraph together with the other footers. To avoid problems do not separate it from the Signed-off-by message with a new-line character.
8.3. Updating the Gerrit review
You may get review comments asking to improve the Gerrit change. Or you find a better way of doing the change. You can update an existing Gerrit review by using the same Change-Id for another commit. The easiest way of doing this is to amend the last commit and push this commit again to Gerrit.
Since the amended commit contains the same Change-Id as the initial commit, Gerrit knows that you want to update this change with the new commit. Also in your local Git repository commit amend replaces the previous commit in your local history (and keep the same parent commit).
9. Eclipse projects responsible for the Java IDE
9.1. The Eclipse project
The Eclipse IDE is an open source (OS) project. Eclipse.org hosts lots of OS projects with different purposes. The foundation of the whole Eclipse IDE is delivered by the Eclipse platform, the Java development tools (JDT) and the Plug-in Development Environment (PDE) project.
All these projects belong to the project called "Eclipse project". The name is a bit strange since nowadays there are many Eclipse projects. But it originates from the fact that these projects were at the beginning the only available Eclipse projects.
These components are bundled together as the Eclipse Standard Development Kit (SDK) release. This is also known as the Eclipse standard distribution. The Eclipse SDK contains all tools to develop Eclipse plug-ins.
In addition to these projects, the platform also has an incubator project called e4 which provides new tools for Eclipse 4 developments. It also serves as a testing ground for new ideas.
9.2. The Eclipse platform projects home pages and Git repositories
The following table lists the home pages of these projects along with the developer pages, which list the Git (and Gerrit) repositories. <table frame='all'> === Eclipse projects <tgroup cols='3' align='left' colsep='1' rowsep='1'> <colspec colname='c1' colwidth="1*" /> <colspec colname='c2' colwidth="2*" /> <colspec colname='c3' colwidth="3*" /> <thead> <row> <entry>Project</entry> <entry>Home page</entry> <entry>Developer pages with Git repositories </entry> </row> </thead> <tbody> <row> <entry>Platform</entry> <entry> http://www.eclipse.org/eclipse/"> Eclipse platform project
</entry> <entry> Not relevant, as platform is only the top project </entry> </row> <row> <entry>Platform UI</entry> <entry> https://www.eclipse.org/eclipse/platform-ui/"> Eclipse platform UI project
</entry> <entry> https://projects.eclipse.org/projects/eclipse.platform.ui/developer"> Platform UI developer page
</entry> </row> <row> <entry>Java development tools (JDT)</entry> <entry> http://www.eclipse.org/jdt"> JDT project
</entry> <entry> https://projects.eclipse.org/projects/eclipse.jdt.ui/developer"> JDT UI developer page and https://projects.eclipse.org/projects/eclipse.jdt.core/developer"> JDT core developer page </entry> </row> <row> <entry>Plug-in Development Environment (PDE)</entry> <entry> http://www.eclipse.org/pde/"> PDE project
</entry> <entry> https://projects.eclipse.org/projects/eclipse.pde/developer">PDE developer page </entry>
</row> <row> <entry>e4</entry> <entry> http://www.eclipse.org/e4/"> e4 project
</entry> <entry> https://projects.eclipse.org/projects/eclipse.e4/developer">e4 developer page </entry> </row> </tbody> </tgroup> </table>
10. Eclipse and tests
10.1. Eclipse projects and their test suite
Most Eclipse projects provide a test suite which can be used to validate that everything still works as planned. The Gerrit build validation will execute most of them, if you upload them. If changes in the tests are required, you should adjust the tests with the same Gerrit change.
|The target of most projects is to run 100% or the test suite during the Gerrit build validation but due to history reasons that is not always possible.|
At the time of this writing, some of the unit tests of the Eclipse projects are still based on JUnit 3.x but most have been migrated to JUnit 4.x. JUnit 3.x uses the test prefix of method names to identify test methods.
10.2. Running the Eclipse platform unit tests
10.2.1. Repositories for platform tests
Clone the following Git repositories as these contain the existing unit tests. The clone URLs (these are not URLs for the browser!) are listed below.
10.2.2. Example: JFace tests
In this section the procedure to run the unit tests of the JFace components is described as an example for running tests from an Eclipse project.
The unit tests for the JFace Bundle are placed in the org.eclipse.ui.tests plug-in. This plug-in includes also several other tests for the Eclipse platform.ui component.
To run theses tests, import the following required plug-ins:
org.eclipse.core.tests.harness from the eclipse.platform.runtime repository
org.eclipse.core.tests.runtime from the eclipse.platform.runtime repository
org.eclipse.test.performance from the eclipse.platform.releng repository
org.eclipse.ui.tests from the eclipse.platform.ui repository
org.eclipse.ui.tests.harness from the eclipse.platform.ui repository
To test the full JFace TestSuite, you only need to run the JFace-All Tests.launch run configuration from the
10.3. Running the unit tests on a virtual server
The Eclipse platform unit tests starts an Eclipse IDE and visually interacts with it. This screen flickering can be annoying. On Unix based system you can also run the user interface tests with a virtual display. You can of course run the tests without a virtual server but this makes the execution of the tests faster and allows to developer to continue to work on the same machine.
On Ubuntu you can install the virtual server and the client via the following commands.
# install the virtual server and client sudo apt-get install vnc4server sudo apt-get install xtightvncviewer (1)
|1||The client is not required to run the unit tests but useful in case you want to view the test execution on the virtual server.|
You start the server with the following parameters.
# start the server on display #1 vncserver :1 -name testing -depth 24 -geometry 1280x1024
In the Eclipse launch configuration you can define the display which is used for the test execution.
image::settingdisplayforunittests.png" scale="30[Setting the Display variable in Eclipse,pdfwidth=60%]
If you are running a Maven / Tycho build from the command line, you can export the display variable.
If you want to watch the unit tests, you can also connect to the virtual server via the vncclient.
# connect to the server, IP will be asked vncviewer
11. Creating a custom Eclipse IDE build
11.1. Building the Eclipse IDE
Eclipse uses a Maven based build system for automated builds using the Maven Tycho plug-in. Using this build system, you can create your custom build of the Eclipse IDE. If you building the Eclipse IDE from the current master branch you get an IDE based on the latest developments of the Eclipse development team.
The results of an Tycho build are archive files for the different platforms, which include everything to run an Eclipse IDE.
As the build continuously changes, the results and requirement of the build might be slightly changed at the time you read this. See [buildeclipse_additions_questions] for finding additional information.
Depending on your network connection and your machine power the build of the Eclipse IDE takes around 2 hours on a Core i5 machine with SSD, so of course time is required for this. Also, approximately 25 Gigs of free space and 4 Gigs of RAM are required on the hardware-side. Building of an Eclipse IDE is possible on Windows, OS X and Linux based distributions. This tutorial is tested with Linux.
On the software-side the following software is required:
Maven Version 3.3.1
Oracle 1.8 JDK or higher
11.3. Building the Eclipse IDE from source
You download the newest version of the source code by cloning the following repository and it’s submodules via Git. Afterwards you can start a build.
git clone -b master --recursive git://git.eclipse.org/gitroot/platform/eclipse.platform.releng.aggregator.git mvn clean verify
If you receive
java.lang.OutOfMemoryError error during the Maven build, you should increase the memory which is available for the build.
If the build is successful, the Eclipse SDK is packaged as archive files for all supported platforms. These packages can be found in the Git repository in the eclipse.platform.releng.tychoeclipsebuilder/sdk/target/products/* folder:
11.4. Cleanup before the next build
To ensure that the repository is clean and up to date we execute the following Git commands.
git submodule foreach git clean -f -d -x git submodule foreach git reset --hard HEAD git clean -f -d -x git reset --hard HEAD
12. Additional infos about building the Eclipse platform
12.1. Reporting issues or asking questions about the build
A good place to post questions about the CBI build is the CBI mailing list. The webinterface for this mailing list can be found under the following URL https://dev.eclipse.org/mailman/listinfo/cbi-dev">CBI mailing list .
12.2. Eclipse platform Hudson builds
The Eclipse platform has a Hudson build instance which can be found under the following URL: https://hudson.eclipse.org/platform/">Eclipse platform Hudson . This build instance is currently not used for the main build, only to validate Gerrit contributions.
See https://bugs.eclipse.org/bugs/show_bug.cgi?id=420101">Bug report for migrating the platform build to Hudson
12.3. Release and milestone builds
To have a reproducible and stable build, it is possible to switch to a specific version instead of using the newest source code. For this the platform aggregator repository has tags for every release build.
To build for example the R4_3 release, you have to checkout this specific tag out and start the build like the following: <programlisting language="bourne"> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="./examples/extras/build_release.txt
<warning> The CBI build still depends on external resources like p2 update sites. From time to time this resources change or will become unavailable. The R4_3_1 tag for example depends on a removed update site, so you have to add the new URL via a parameter to the build: <programlisting language="bourne"> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="./examples/extras/build_release_r4_3_1.txt" /> </programlisting> </warning> TIP: To check which properties can be overridden check the properties fields in the eclipse-platform-parent/pom.xml file. </tip> === Changing build ID A normal CBI Build shows, "Build id: @build@" in the "About Eclipse SDK" window. To define a custom build id use the `buildId` parameter and the `update-branding-plugins` profile. <programlisting language="bourne"> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="./examples/extras/buildid.txt
12.4. Build single parts of the aggregator
It is also possible to build just single parts of the aggregator
repository, by passing the
The following example shows how to build just the
<programlisting language="bourne"> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="./examples/extras/build-individual-bundles.txt