Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Platform/How to Contribute"

(Commit Message Conventions)
(47 intermediate revisions by 13 users not shown)
Line 8: Line 8:
 
* Via Atom.  You can convert any query in bugzilla to a feed that will update when a matched bug changes.  To convert a search to a feed perform a search and select "Feed" at the bottom of the search results.
 
* Via Atom.  You can convert any query in bugzilla to a feed that will update when a matched bug changes.  To convert a search to a feed perform a search and select "Feed" at the bottom of the search results.
  
== Contributing Code==
+
== Bug triage==
Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature for Platform UI you'll need to know a few things before you contribute code.
+
  
Platform UI is using Git as version control system.
+
If you are interested to help with bug solving, the Eclipse platform project has a huge backlog of existing bug reports. It is often not possible for the committer to re-test all old bug reports. A contributor can re-test bug reports and report if they are already solved. If you want to help in this area, please send a message to the [https://dev.eclipse.org/mailman/listinfo/platform-ui-dev platform.ui mailing list]. We can nominate you to give you rights to close bugs via the process described [https://wiki.eclipse.org/Bug_Reporting_FAQ#Bug_Editing_and_Triage Platform Bug triage process].  
  
=== Setting up your SDK ===
+
== Setting up your SDK for code contributions ==
  
First you need to set up your environment. You need to:
+
Our goal is to have a completely automated installer for setting up your workspace to contribute to Eclipse. There are still some manual steps in this setup guide but we're working on eliminating them.
  
# Get an Eclipse SDK
+
Before to start, please note the installer works only on the 64bit version of Java. So if you strictly need to use a 32bit version, please, follow [https://wiki.eclipse.org/index.php?title=Platform_UI/How_to_Contribute&oldid=394080 this same contribution guide as updated to Nov'2015]
# Install the tools we use during development
+
# Get the code for Platform UI
+
# Use the correct target platform
+
  
Our current branches:
+
Prerequisites: You can use a Java 8 JDK/JRE to run Eclipse but you still need a Java 7 JDK/JRE installed because the source code is still on Java 7.
 +
You can download an Oracle Java 7 JDK/JRE from here: http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html
 +
Alternatively OpenJDK builds are available for linux via their default package managers.
  
* master - development towards Luna/4.4
+
Go to [https://eclipse.org/downloads/ Eclipse Downloads] and download the installer for your platform.
* R4_3_maintenance - fixes for 4.3.x/Kepler service releases
+
* R4_2_maintenance - fixes for 4.2.x/Juno service releases
+
* R3_8_maintenance - fixes for 3.8.x/Juno service releases
+
  
==== Get an Eclipse SDK ====
+
[[File:uisetup-1-download_eclipse.png|border]]
  
Your best bet is to download the appropriate version (a Luna I-build or Kepler M-build) from http://download.eclipse.org/eclipse/downloads/
+
Launch the installer.
  
==== Install the development tools ====
+
If you see a yellow exclamation mark in the top-right, it means the installer is out-of-date. Click on the exclamation mark and then click on the word UPDATE. After the installer finishes updating, it will restart and you can continue with these steps.
  
You can install the development tools by using ''File>Import...>Install>Install Software Items from File''.  You can use http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiTools.p2f (make sure you use the version from R4_3_maintenance for Kepler SR2).
+
Click on the menu button in the upper-right.
  
==== Get the code for Platform UI ====
+
[[File:uisetup-2-Installer_Screen.png]]
  
* Use ''File>Import...>Team>Team Project Set'' to import the Platform UI projects into your workspace.  Use http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiProjects.psf (make sure you use the version from R4_3_maintenance for Kepler).
+
Click on ADVANCED MODE...
  
Please note that the user id of your host will be used as gerrit user id to connect to eclipse servers. If they are not matching you have three solutions:
+
[[File:Uisetup-3-Advanced_Mode.png]]
* Modify URL directly in the file to specify gerrit user id, ssh://gerritUserid@git... instead of ssh://git
+
 
* Modify the URL to point to the ''https'' version of the Gerrit repo location, https://gerritUserid@git...
+
Select "Eclipse IDE for Eclipse Committers"
* Modify URL directly in the file in order to point to http://git.eclipse.org/gitroot for anonymous access (you won't be able to push changes for review).
+
 
 +
Select "Latest (Neon)"
 +
 
 +
Select the location of a 64-bit 1.8 JDK.
 +
 
 +
Click Next
 +
 
 +
[[File:uisetup-4-Select_Product.png]]
 +
 
 +
Click the checkbox next to the Platform > UI
 +
 
 +
You may also select other projects in this menu, but DO NOT SELECT SWT unless you are doing so to help work on the SWT setup scripts (please remove this warning once the SWT setup works). If you work on SWT, it must be configured manually after the rest of these steps.
 +
 
 +
Click Next
 +
 
 +
[[File:uisetup-5-Click_The_Down_Arrow.png]]
 +
 
 +
Fill in the "Root install folder" with the parent folder under which you want all your Eclipse installs to go. (If you've run the installer before, it will remember your decision and you won't see this again unless you click "Show all variables").
 +
 
 +
Fill in "Installation folder name" with the name you want to give this Eclipse installation.
 +
 
 +
Click on "Platform UI Git or Gerrit Repository" and select the one starting with SSH.
 +
 
 +
Fill in your gerrit username. Alternatively, if you don't plan to contribute anything back to Eclipse you can use the default selection and omit filling in a username.
 +
 
 +
Leave the other values set to their defaults.
 +
 
 +
Click Next
 +
 
 +
[[File:uisetup-6-Edit_Variables.png]]
 +
 
 +
Click Next, Click Finish.
 +
 
 +
Accept the license agreements.
 +
 
 +
Wait for the message "Press Finish to close the dialog" then do that thing.
 +
 
 +
Wait for the new Eclipse workspace to start up, initialize, and build.
 +
 
 +
It's possible that you will see a red X in your status bar after the restart. If so, you may be seeing [https://bugs.eclipse.org/bugs/show_bug.cgi?id=493265 Bug 493265]. Click the red X on your status line, click back, deselect any task containing the word "API Baseline", then click Finish to retry. You will have to set up your API Baseline manually.
 +
 
 +
=== Setting up an API baseline ===
 +
 
 +
Once Eclipse is set up, you must set an API baseline. (We plan to automate this as part of the Oomph setup, but it must be done manually right now.)
 +
 
 +
Download the latest RELEASE of Eclipse (not a milestone or integration build). You can download Eclipse 4.5.2 from [https://www.eclipse.org/downloads/packages/eclipse-ide-eclipse-committers-452/mars2 this page].
 +
 
 +
Extract it to a folder. You should never launch or install any updates on this copy of Eclipse.
 +
 
 +
Select Window > Preferences > Plug-in Development > API Baselines > Add Baseline... > An existing Eclipse installation directory > Next
 +
 
 +
Enter the name "Eclipse Release"
 +
Click Browse... and select the "eclipse" folder of the Eclipse installation you extracted.
 +
Click Refresh
 +
Click Finish
 +
 
 +
=== Setting up the Execution Environments ===
 +
 
 +
Select Window > Preferences > Java > Installed JREs
 +
  Make sure you have defined a Java 7 JRE
 +
Select Window > Preferences > Java > Installed JREs > Execution Environments
 +
  Make sure you point JavaSE-1.7 to a Java 7 JRE defined above.
 +
 
 +
=== Launching Eclipse ===
 +
When you want to launch Eclipse again, you'll find the executable in the "Root install folder" you selected above. The executable will be here:
 +
 
 +
<Root install folder>/<Installation folder name>/eclipse
 +
 
 +
For example, if I'm on Linux and selected ~/oomph for my root install folder and platform-master for my installation folder name, the executable I launch to run Eclipse will be called:
 +
 
 +
~/oomph/platform-master/eclipse/eclipse
 +
 
 +
=== Running specific builds ===
 +
 
 +
If you want to always be using the latest integration build or - say - a specific nightly build, follow these steps after you've finished installing Eclipse as described above.
 +
 
 +
Go to the download site for the integration build you wish to use (or any integration build if you want to auto-upgrade to each integration build).
 +
 
 +
The download page for each build will contain two links to update sites. One is for the stream (which always points to the latest build of that type) and the other is for that specific build. Copy the URL for the one you want. The links look like this on the download page:
 +
 
 +
[[File:Upsetup-Eclipse Download Page.png]]
 +
 
 +
Go to Window > Preferences > Install/Update > Available Software Sites
 +
Add...
 +
Paste the URL of the update site and type in any name.
 +
Click OK > OK
 +
Go to Help > Check for updates
 +
Install any updates it finds
 +
Restart Eclipse if prompted
 +
 
 +
You will then be running the specific build you selected. If you selected a stream rather than a specific build, you can update to the latest build of that type by rerunning the "Check for updates" command.
 +
 
 +
=== Active branches ===
 +
 
 +
Our currently active branches:
 +
 
 +
* master - development towards the next release
 +
* R4_5_maintenance - fixes for 4.5.x/Mars service releases, no active development but sometimes we cherry pick patches from master to it
 +
 
 +
=== Use ssh for clone/push ===
  
 
When using ssh, you also need to upload your ssh key if not already done. See [https://wiki.eclipse.org/Gerrit#Git_over_SSH Gerrit over SSH] for more information.  When using ''https'' with Gerrit, you'll need to set your https password in Gerrit.  See [https://wiki.eclipse.org/Gerrit#Git_over_HTTPS Gerrit over HTTPS].
 
When using ssh, you also need to upload your ssh key if not already done. See [https://wiki.eclipse.org/Gerrit#Git_over_SSH Gerrit over SSH] for more information.  When using ''https'' with Gerrit, you'll need to set your https password in Gerrit.  See [https://wiki.eclipse.org/Gerrit#Git_over_HTTPS Gerrit over HTTPS].
  
==== Tweaks for after your environment is set up ====
+
When you are using ssh with a passphrase you probably get ''USERAUTH fail'' errors (possible import wizard bug). As workaround start cloning a repository listed in the team project set via the default EGit wizard over ssh. After you entered the passphrase you should see the available branches -- you can now abort the EGit wizard and retry importing the team project set as JGit should have been cached the ssh information.
  
'''API Baseline Errors''':  For developing on Luna, you can either unzip a version of Kepler (4.3.1) and use that install as the API baseline or go to ''Preferences>Plug-in Development>API Baseline'' and set the missing API baseline to Ignore.  Committers and regular contributors '''must''' set their API baseline.
+
=== 4. Tweaks for after your environment is set up ===
  
 
'''Build Path problems''': if you have build path problems for org.eclipse.core.expressions* you need to go to ''Preferences>Java>Installed JREs'' and add the missing JREs.  This usually involves getting an install for 1.4, 1.5, 1.6, and 1.7.
 
'''Build Path problems''': if you have build path problems for org.eclipse.core.expressions* you need to go to ''Preferences>Java>Installed JREs'' and add the missing JREs.  This usually involves getting an install for 1.4, 1.5, 1.6, and 1.7.
Line 71: Line 165:
 
  exec metacity --replace --sm-disable
 
  exec metacity --replace --sm-disable
  
 +
 +
==== Use Gerrit for clone/push ====
  
 
'''Pushing a Gerrit commit''': Make sure you use the signed-of-by and change-id buttons before you create your commit.  If you haven't, just amend your commit and add them.  Then you can push a commit for review by switching to the Git Repositories view, right-clicking on the repo, and selecting '''Push to Gerrit...'''.  You want to enter the branch you are pushing to, for example '''refs/for/master'''.  That will create a Gerrit review, and the review URL will be in the dialog that contains the status.  The git command line equivalent would be:
 
'''Pushing a Gerrit commit''': Make sure you use the signed-of-by and change-id buttons before you create your commit.  If you haven't, just amend your commit and add them.  Then you can push a commit for review by switching to the Git Repositories view, right-clicking on the repo, and selecting '''Push to Gerrit...'''.  You want to enter the branch you are pushing to, for example '''refs/for/master'''.  That will create a Gerrit review, and the review URL will be in the dialog that contains the status.  The git command line equivalent would be:
  
 
  git push origin HEAD:refs/for/master
 
  git push origin HEAD:refs/for/master
 +
 +
Now you can commit and ''Team->Push to Upstream'' will push your commits directly to Eclipse Gerrit instance. First time push dialog will ask you for your Gerrit username and password, which you can see if you are logged into Gerrit under [https://git.eclipse.org/r/#/settings/http-password ''Settings->HTTP Password''].
 +
 +
== Contributing Code==
 +
Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature for Platform UI you'll need to know a few things before you contribute code.
 +
 +
Platform UI is using Git as version control system.
  
 
=== More information about getting the code into your workspace ===
 
=== More information about getting the code into your workspace ===
Line 105: Line 208:
 
=== Creating a Gerrit review or a patch ===
 
=== Creating a Gerrit review or a patch ===
  
Once a Gerrit change set is created, the change set should be posted on the bugzilla it came from so it can be reviewed.
+
The preferred method of contributing bugfixes or new features is via the [[Gerrit]] review system. Once a Gerrit change set is created, the link to the Gerrit change should be posted on the Bugzilla. If you are using the [https://wiki.eclipse.org/Platform_UI/How_to_Contribute#Commit_Message_Conventions correct commit format], this is done automatically by the Eclipse infrastructure.
  
The preferred method of contributions is now [[Gerrit]]. See [http://www.vogella.com/articles/Gerrit/article.html#eclipsegerritcontribution Contributing to Eclipse via Gerrit] for a detailed description.
+
See [http://www.vogella.com/tutorials/EclipsePlatformDevelopment/article.html#eclipsecontribution_usersetup Contributing to Eclipse via Gerrit] for a detailed description.
 +
 
 +
It is totally fine to upload a partial fix so that people can give early feedback, please mark in case the review so, e.g., by using [WIP] in the commit message. WIP stands for Work in Progress.
  
 
=== Unit Testing===
 
=== Unit Testing===
Line 121: Line 226:
 
=== Coding Conventions ===
 
=== Coding Conventions ===
 
* Follow the Eclipse Platform's [[Development Conventions and Guidelines]].
 
* Follow the Eclipse Platform's [[Development Conventions and Guidelines]].
* Every file must contain a copyright header, as described in [[Development Conventions and Guidelines]]. The copyright header goes before the package declaration, starting in the very first line. For new files, list "yourself and others" instead of "IBM and others" in the first line. For changed files, add a contribution comment in the copyright header with your name and affiliation, and a bug id.
+
* Every file must contain a copyright header, as described in [[Development Conventions and Guidelines]]. The copyright header goes before the package declaration, starting in the very first line. For new files, list "yourself and others" instead of "IBM and others" in the first line.
 +
 
 
For instance:
 
For instance:
 
{{codeblock|/*******************************************************************************
 
{{codeblock|/*******************************************************************************
  * Copyright (c) 2008, 2014 IBM Corporation and others.
+
  * Copyright (c) 2015, 2016 [Your Company or your name] and others.
 
  * All rights reserved. This program and the accompanying materials
 
  * All rights reserved. This program and the accompanying materials
 
  * are made available under the terms of the Eclipse Public License v1.0
 
  * are made available under the terms of the Eclipse Public License v1.0
Line 131: Line 237:
 
  *  
 
  *  
 
  * Contributors:
 
  * Contributors:
  *    IBM Corporation - initial API and implementation
+
  *    [Your Company or your name] - initial API and implementation
*    John Doe <John.Doe@eclipse.org> - Bug 429728
+
 
  *******************************************************************************/}}
 
  *******************************************************************************/}}
* UI will need you to use project-specific settings for compiler warnings/errors, code formatting etc. that are copied from the other UI plug-ins' settings.
+
 
 +
* UI will need you to use project-specific settings for compiler warnings/errors, code formatting, save actions etc. These settings are typically copied into new projects from an existing one.
 +
* Avoid formatting the whole files - as this can generate pseudo-changes (white-space related) when committing changes to existing source files.
 +
** The easiest way, for Java files, is to have "Format edited lines" activated in the Preferences -> Java -> Editor -> Save Actions (this ''should'' be already pre-configured in the project settings).
 +
** One can also format just the needed block by selecting it and using "format" (Ctrl+Shift+F).
 
* Use &quot;organize imports&quot; (Ctrl-Shift-O) to clean up the imports (we do not use org.eclipse.* type notation).
 
* Use &quot;organize imports&quot; (Ctrl-Shift-O) to clean up the imports (we do not use org.eclipse.* type notation).
 
* It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them.
 
* It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them.
Line 141: Line 250:
 
* Avoid adding trailing whitespace. You can use the save actions in Eclipse to auto-remove them, via the Preferences -> Java -> Editor -> Save Actions. Activate them and as additional action select Configure and select "Remove trailing whitespace"
 
* Avoid adding trailing whitespace. You can use the save actions in Eclipse to auto-remove them, via the Preferences -> Java -> Editor -> Save Actions. Activate them and as additional action select Configure and select "Remove trailing whitespace"
 
* Write/update Javadoc for all API you introduce/change. See [http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs Evolving Java-based APIs] by Jim des Rivi&egrave;res to understand what it means to maintain an API.
 
* Write/update Javadoc for all API you introduce/change. See [http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs Evolving Java-based APIs] by Jim des Rivi&egrave;res to understand what it means to maintain an API.
* Use the following format for your commit message:
 
  
Bug XXXX - bug title<br />
+
 
<space><br />
+
=== Optional: Update the copyright header for existing files ===
Short description of what the fix contains, or the direction of the fix<br />
+
For changed files, you can optional add a contribution comment in the copyright header with your name and affiliation, and a bug id. If the top "Copyright (c)" line does not contain the current year, update it by changing the second year to be the current year or by adding a comma and the current year after the initial year.
<space><br />
+
For instance:
Signed-off-by: email-with-CLA
+
{{codeblock|/*******************************************************************************
 +
* Copyright (c) 2008, 2016 IBM Corporation and others.
 +
* All rights reserved. This program and the accompanying materials
 +
* are made available under the terms of the Eclipse Public License v1.0
 +
* which accompanies this distribution, and is available at
 +
* http://www.eclipse.org/legal/epl-v10.html
 +
*
 +
* Contributors:
 +
*    IBM Corporation - initial API and implementation
 +
*    John Doe <John.Doe@eclipse.org> - Bug 429728
 +
*******************************************************************************/}}
 +
 
 +
=== Commit Message Conventions ===
 +
 
 +
* In general, each commit requires a [https://bugs.eclipse.org/bugs/ bug] entry. Only trivial and non-controversial changes (like typos) can be committed without a bug.
 +
* A commit related to an existing bug report has to start with "Bug XXXXXX - " or "Bug XXXXXX: " or "Fixed bug XXXXXX: summary".
 +
* Don't tie unrelated changes to a bug (number) just because you are working on that bug. Simply use e.g. "Fixed typo in XYZ" or "Removed trailing whitespace in XYZ".
 +
* Don't include such unrelated changes in the real fix/change.
 +
* The change summary should be short, clear and concise description about the change.
 +
* The body of the commit message should be more detailed explanatory text (if necessary), describing the change.
 +
** Important architectural explanations should go into code comments, not just into the commit message.
 +
* Use the following format for your commit message. The Change-Id is only required if you use Gerrit.
 +
 
 +
{{codeblock|Bug XXXXXX - Functional change in service XYZ
 +
 +
More detailed explanatory text (if necessary), describing the change, the direction of the fix etc.
 +
 +
Change-Id: I0000000000000000000000000000000000000000
 +
Signed-off-by: Your Name <your.email@with-CLA.org>}}
 +
 
 +
 
 +
* N&N commits that add an entry should always include the bug number.
  
 
=== Before You Check In ===
 
=== Before You Check In ===
Line 159: Line 298:
  
 
== Forum ==
 
== Forum ==
We try to be prompt and responsive on the [http://www.eclipse.org/forums/?group=eclipse.platform forum] (newsgroup) but there's always room for improvement. If you know the answer to a query feel free to respond. Also the [http://www.eclipse.org/forums/index.php/f/12/ Eclipse 4] forum is meant for pure Eclipse 4 (non 3.x) related questions.  
+
The [http://www.eclipse.org/forums/?group=eclipse.platform Eclipse platform forum] (newsgroup) is used to ask and answer questions. If you know the answer to a query it would be great if you would respond to it. Also the [http://www.eclipse.org/forums/index.php/f/12/ Eclipse 4 forum] is meant for pure Eclipse 4 (non 3.x) related questions.  
  
 
== Wiki==
 
== Wiki==
The wiki is open and can be edited by all. If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it.  If wanting to contribute a significant amount of information or create a new article we request that you [[../FAQ#How_do_I_report_a_bug.3F|log a bug]] so that we're aware of what you're contributing.  This is so that we can ensure consistency structurally and in the message conveyed.
+
The wiki is open and can be edited by all. If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it.  If wanting to contribute a significant amount of information or create a new article we request that you [[../FAQ#How_do_I_report_a_bug.3F|log a bug]] so that we're aware of what you're contributing.  This is so that we can ensure consistency structurally and in the message conveyed.
  
 
== IRC ==
 
== IRC ==
Line 172: Line 311:
 
== Meetings ==
 
== Meetings ==
  
The team has bi-weekly phone calls for development discussions and planning. Anyone is welcome to join in. For call in details and minutes see [[E4/Meeting_Minutes]].
+
There are currently no calls scheduled. They can be arranged upon request.
 +
For call in details and minutes see [[E4/Meeting_Minutes]].

Revision as of 06:40, 29 June 2016

This page is a starting point for where to begin when wanting to contribute to the project. The goal is to educate and to be as up front as possible with expectations so that the process can be as efficient as possible. Template:Platform UI

Bugs

If you find a bug, log it. See the FAQ entry "How to Report a Bug", and a description of how a great bug report looks like. If you find a bug that you think is a duplicate, is not a bug, etc. feel free to comment saying so.

If wanting to track bug changes in Platform UI there are a few ways:

  • Via email. If you want to receive email when a bug is logged you can watch the Platform-UI-Inbox@eclipse.org user. You will receive email anytime a new bug is logged to this user or an update is made while assigned to this user. To set this up see Preferences -> Email Preferences -> User Watching. This will email you for all incoming Platform UI bugs; to follow all changes for Platform UI and IDE for bugs that an individual has not yet taken, watch platform-ui-triaged@eclipse.org as well.
  • Via Atom. You can convert any query in bugzilla to a feed that will update when a matched bug changes. To convert a search to a feed perform a search and select "Feed" at the bottom of the search results.

Bug triage

If you are interested to help with bug solving, the Eclipse platform project has a huge backlog of existing bug reports. It is often not possible for the committer to re-test all old bug reports. A contributor can re-test bug reports and report if they are already solved. If you want to help in this area, please send a message to the platform.ui mailing list. We can nominate you to give you rights to close bugs via the process described Platform Bug triage process.

Setting up your SDK for code contributions

Our goal is to have a completely automated installer for setting up your workspace to contribute to Eclipse. There are still some manual steps in this setup guide but we're working on eliminating them.

Before to start, please note the installer works only on the 64bit version of Java. So if you strictly need to use a 32bit version, please, follow this same contribution guide as updated to Nov'2015

Prerequisites: You can use a Java 8 JDK/JRE to run Eclipse but you still need a Java 7 JDK/JRE installed because the source code is still on Java 7. You can download an Oracle Java 7 JDK/JRE from here: http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html Alternatively OpenJDK builds are available for linux via their default package managers.

Go to Eclipse Downloads and download the installer for your platform.

Uisetup-1-download eclipse.png

Launch the installer.

If you see a yellow exclamation mark in the top-right, it means the installer is out-of-date. Click on the exclamation mark and then click on the word UPDATE. After the installer finishes updating, it will restart and you can continue with these steps.

Click on the menu button in the upper-right.

Uisetup-2-Installer Screen.png

Click on ADVANCED MODE...

Uisetup-3-Advanced Mode.png

Select "Eclipse IDE for Eclipse Committers"

Select "Latest (Neon)"

Select the location of a 64-bit 1.8 JDK.

Click Next

Uisetup-4-Select Product.png

Click the checkbox next to the Platform > UI

You may also select other projects in this menu, but DO NOT SELECT SWT unless you are doing so to help work on the SWT setup scripts (please remove this warning once the SWT setup works). If you work on SWT, it must be configured manually after the rest of these steps.

Click Next

Uisetup-5-Click The Down Arrow.png

Fill in the "Root install folder" with the parent folder under which you want all your Eclipse installs to go. (If you've run the installer before, it will remember your decision and you won't see this again unless you click "Show all variables").

Fill in "Installation folder name" with the name you want to give this Eclipse installation.

Click on "Platform UI Git or Gerrit Repository" and select the one starting with SSH.

Fill in your gerrit username. Alternatively, if you don't plan to contribute anything back to Eclipse you can use the default selection and omit filling in a username.

Leave the other values set to their defaults.

Click Next

Uisetup-6-Edit Variables.png

Click Next, Click Finish.

Accept the license agreements.

Wait for the message "Press Finish to close the dialog" then do that thing.

Wait for the new Eclipse workspace to start up, initialize, and build.

It's possible that you will see a red X in your status bar after the restart. If so, you may be seeing Bug 493265. Click the red X on your status line, click back, deselect any task containing the word "API Baseline", then click Finish to retry. You will have to set up your API Baseline manually.

Setting up an API baseline

Once Eclipse is set up, you must set an API baseline. (We plan to automate this as part of the Oomph setup, but it must be done manually right now.)

Download the latest RELEASE of Eclipse (not a milestone or integration build). You can download Eclipse 4.5.2 from this page.

Extract it to a folder. You should never launch or install any updates on this copy of Eclipse.

Select Window > Preferences > Plug-in Development > API Baselines > Add Baseline... > An existing Eclipse installation directory > Next

Enter the name "Eclipse Release" Click Browse... and select the "eclipse" folder of the Eclipse installation you extracted. Click Refresh Click Finish

Setting up the Execution Environments

Select Window > Preferences > Java > Installed JREs

 Make sure you have defined a Java 7 JRE

Select Window > Preferences > Java > Installed JREs > Execution Environments

 Make sure you point JavaSE-1.7 to a Java 7 JRE defined above.

Launching Eclipse

When you want to launch Eclipse again, you'll find the executable in the "Root install folder" you selected above. The executable will be here:

<Root install folder>/<Installation folder name>/eclipse

For example, if I'm on Linux and selected ~/oomph for my root install folder and platform-master for my installation folder name, the executable I launch to run Eclipse will be called:

~/oomph/platform-master/eclipse/eclipse

Running specific builds

If you want to always be using the latest integration build or - say - a specific nightly build, follow these steps after you've finished installing Eclipse as described above.

Go to the download site for the integration build you wish to use (or any integration build if you want to auto-upgrade to each integration build).

The download page for each build will contain two links to update sites. One is for the stream (which always points to the latest build of that type) and the other is for that specific build. Copy the URL for the one you want. The links look like this on the download page:

Upsetup-Eclipse Download Page.png

Go to Window > Preferences > Install/Update > Available Software Sites Add... Paste the URL of the update site and type in any name. Click OK > OK Go to Help > Check for updates Install any updates it finds Restart Eclipse if prompted

You will then be running the specific build you selected. If you selected a stream rather than a specific build, you can update to the latest build of that type by rerunning the "Check for updates" command.

Active branches

Our currently active branches:

  • master - development towards the next release
  • R4_5_maintenance - fixes for 4.5.x/Mars service releases, no active development but sometimes we cherry pick patches from master to it

Use ssh for clone/push

When using ssh, you also need to upload your ssh key if not already done. See Gerrit over SSH for more information. When using https with Gerrit, you'll need to set your https password in Gerrit. See Gerrit over HTTPS.

When you are using ssh with a passphrase you probably get USERAUTH fail errors (possible import wizard bug). As workaround start cloning a repository listed in the team project set via the default EGit wizard over ssh. After you entered the passphrase you should see the available branches -- you can now abort the EGit wizard and retry importing the team project set as JGit should have been cached the ssh information.

4. Tweaks for after your environment is set up

Build Path problems: if you have build path problems for org.eclipse.core.expressions* you need to go to Preferences>Java>Installed JREs and add the missing JREs. This usually involves getting an install for 1.4, 1.5, 1.6, and 1.7.

Running the tests: you should be able to run a couple of pre-filled launch configs from Run>Run Configurations. on linux: The launch configs often come with DISPLAY=:1.0. You should either run a vnc server or remove that variable from the environment tab. An example of a $HOME/.vnc/xstartup that works for the Platform UI tests is:

#!/bin/sh

# Uncomment the following two lines for normal desktop:
# unset SESSION_MANAGER
# exec /etc/X11/xinit/xinitrc

[ -x /etc/vnc/xstartup ] && exec /etc/vnc/xstartup
[ -r $HOME/.Xresources ] && xrdb $HOME/.Xresources
xsetroot -solid grey
#vncconfig -iconic &
xterm -geometry 80x24+10+10 -sb -sl 5000 -ls -title "$VNCDESKTOP Desktop" &
#gnome-session --sm-disable --failsafe --disable-sound &

exec metacity --replace --sm-disable


Use Gerrit for clone/push

Pushing a Gerrit commit: Make sure you use the signed-of-by and change-id buttons before you create your commit. If you haven't, just amend your commit and add them. Then you can push a commit for review by switching to the Git Repositories view, right-clicking on the repo, and selecting Push to Gerrit.... You want to enter the branch you are pushing to, for example refs/for/master. That will create a Gerrit review, and the review URL will be in the dialog that contains the status. The git command line equivalent would be:

git push origin HEAD:refs/for/master

Now you can commit and Team->Push to Upstream will push your commits directly to Eclipse Gerrit instance. First time push dialog will ask you for your Gerrit username and password, which you can see if you are logged into Gerrit under Settings->HTTP Password.

Contributing Code

Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature for Platform UI you'll need to know a few things before you contribute code.

Platform UI is using Git as version control system.

More information about getting the code into your workspace

See Platform-releng/Git_Workflows#Gerrit_workflow_for_a_committer and Gerrit#Doing Code Reviews with Gerrit. Even if you are a contributor, the workflows should give you an idea of how to get set up.


Our code is now contained in the git repo at

git://git.eclipse.org/gitroot/platform/eclipse.platform.ui.git
https://<userid>@git.eclipse.org/r/platform/eclipse.platform.ui
ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.ui

The Dependency Injection and runtime Eclipse Context code is in

git://git.eclipse.org/gitroot/platform/eclipse.platform.runtime.git
https://<userid>@git.eclipse.org/r/platform/eclipse.platform.runtime
ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.runtime


Note: we also maintain some E4-specific tools, hosted in the e4 incubator at (supports Gerrit):

git://git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git
https://<userid>@git.eclipse.org/r/e4/org.eclipse.e4.tools
ssh://<userid>@git.eclipse.org:29418/e4/org.eclipse.e4.tools

And we support User Assistance (Help) contributions at:

git://git.eclipse.org/gitroot/platform/eclipse.platform.ua.git
https://<userid>@git.eclipse.org/r/platform/eclipse.platform.ua
ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.ua

Creating a Gerrit review or a patch

The preferred method of contributing bugfixes or new features is via the Gerrit review system. Once a Gerrit change set is created, the link to the Gerrit change should be posted on the Bugzilla. If you are using the correct commit format, this is done automatically by the Eclipse infrastructure.

See Contributing to Eclipse via Gerrit for a detailed description.

It is totally fine to upload a partial fix so that people can give early feedback, please mark in case the review so, e.g., by using [WIP] in the commit message. WIP stands for Work in Progress.

Unit Testing

Testing is imperative to the health of the project. We have a significant amount of tests. The quantity of tests will keep growing as more functionality is added to Platform UI. If you are contributing a fix or writing an enhancement, it is a requirement that tests are written. If you don't write them a committer will have to and that could slow down the contribution process.

There are a couple of things that you should know about our testing process:

  • The most tests are included in org.eclipse.ui.tests, but you will need the other test plug-ins as well to avoid missing dependencies.
  • If looking for tests for a specific class look for a class named {THECLASS}Test.java (e.g. UpdateStrategy.java -> UpdateStrategyTest.java).
  • To run tests, open the Run Configurations dialog (Ctrl+3, 'run...') and expand the "JUnit Plug-in Test" category to see the launch configurations we use to run the tests.
  • If you create a new TestCase make sure to add it to the correct test suite. The test suite class can be found by looking at the launch configuration on the "Test" tab under "Test class". For example, the test suite for JFace is called org.eclipse.jface.tests.AllTests; the main UI test suite is org.eclipse.ui.tests.UiTestSuite.
  • If you want to make a good impression, write tests. This goes for any project, of course.

Coding Conventions

For instance:

/*******************************************************************************
* Copyright (c) 2015, 2016 [Your Company or your name] and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
* 
* Contributors:
*     [Your Company or your name] - initial API and implementation
*******************************************************************************/
  • UI will need you to use project-specific settings for compiler warnings/errors, code formatting, save actions etc. These settings are typically copied into new projects from an existing one.
  • Avoid formatting the whole files - as this can generate pseudo-changes (white-space related) when committing changes to existing source files.
    • The easiest way, for Java files, is to have "Format edited lines" activated in the Preferences -> Java -> Editor -> Save Actions (this should be already pre-configured in the project settings).
    • One can also format just the needed block by selecting it and using "format" (Ctrl+Shift+F).
  • Use "organize imports" (Ctrl-Shift-O) to clean up the imports (we do not use org.eclipse.* type notation).
  • It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them.
  • Non-externalized strings are considered errors, do not ship non-externalized strings or use the NON-NLS tag to indicate that you are not relevant for translation
  • Use unix line delimiters (In Eclipse select Window-> Properties -> Workspace and set the file delimiter to Unix
  • Avoid adding trailing whitespace. You can use the save actions in Eclipse to auto-remove them, via the Preferences -> Java -> Editor -> Save Actions. Activate them and as additional action select Configure and select "Remove trailing whitespace"
  • Write/update Javadoc for all API you introduce/change. See Evolving Java-based APIs by Jim des Rivières to understand what it means to maintain an API.


Optional: Update the copyright header for existing files

For changed files, you can optional add a contribution comment in the copyright header with your name and affiliation, and a bug id. If the top "Copyright (c)" line does not contain the current year, update it by changing the second year to be the current year or by adding a comma and the current year after the initial year. For instance:

/*******************************************************************************
* Copyright (c) 2008, 2016 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
* 
* Contributors:
*     IBM Corporation - initial API and implementation
*     John Doe <John.Doe@eclipse.org> - Bug 429728
*******************************************************************************/

Commit Message Conventions

  • In general, each commit requires a bug entry. Only trivial and non-controversial changes (like typos) can be committed without a bug.
  • A commit related to an existing bug report has to start with "Bug XXXXXX - " or "Bug XXXXXX: " or "Fixed bug XXXXXX: summary".
  • Don't tie unrelated changes to a bug (number) just because you are working on that bug. Simply use e.g. "Fixed typo in XYZ" or "Removed trailing whitespace in XYZ".
  • Don't include such unrelated changes in the real fix/change.
  • The change summary should be short, clear and concise description about the change.
  • The body of the commit message should be more detailed explanatory text (if necessary), describing the change.
    • Important architectural explanations should go into code comments, not just into the commit message.
  • Use the following format for your commit message. The Change-Id is only required if you use Gerrit.
Bug XXXXXX - Functional change in service XYZ

More detailed explanatory text (if necessary), describing the change, the direction of the fix etc.

Change-Id: I0000000000000000000000000000000000000000
Signed-off-by: Your Name <your.email@with-CLA.org>


  • N&N commits that add an entry should always include the bug number.

Before You Check In

  • Commit comments are required for all code commits, bugs should be logged to track work and the bug number and a description is then used in the commit comment to describe the change. For example when fixing a bug, use exactly: "Fixed bug xxx: <title of bug>". The "bug xxxx" part is really important as this is what is used to relate the bugs to the build submissions, so it must be formatted exactly that way (uppercase or lowercase bug should work).
  • Before committing changes, catch up to all changes made by others, and then run the tests.
  • Don't commit your changes if this will cause compile errors for others.

The Build

The Eclipse build is a bit of a mystery to newcomers. But rest assured that if you break something everyone will know about it and we will laugh at you (not really but we might tease you, or send you a clown nose if it was really bad). If you do one thing it should be to sign up for the platform-releng-dev mailing list. You'll receive emails when builds complete and when build and test failures occur. It's always good to pay extra special attention on the mornings after you make a commit or someone makes a commit on your behalf. The normal reaction to "breaking the build" is to log a bug, notify the platform-releng-dev list about it so that others can gauge the quality of the build, and then fix the bug.

Forum

The Eclipse platform forum (newsgroup) is used to ask and answer questions. If you know the answer to a query it would be great if you would respond to it. Also the Eclipse 4 forum is meant for pure Eclipse 4 (non 3.x) related questions.

Wiki

The wiki is open and can be edited by all. If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it. If wanting to contribute a significant amount of information or create a new article we request that you log a bug so that we're aware of what you're contributing. This is so that we can ensure consistency structurally and in the message conveyed.

IRC

Many Platform UI committers hang out on IRC, on both #eclipse-dev and #eclipse-e4. Feel free to ask questions there, or join into development discussions.

Meetings

There are currently no calls scheduled. They can be arranged upon request. For call in details and minutes see E4/Meeting_Minutes.

Back to the top