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.

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 has switched to git as its SCM. For the old CVS instructions, check out [[Platform UI/How to Contribute/CVS]].

+

Platform UI is using Git as version control system.

+

=== Setting up your SDK ===

=== Setting up your SDK ===

Line 20:

Line 21:

# Get the code for Platform UI

# Get the code for Platform UI

# Use the correct target platform

# Use the correct target platform

+

+

Our current branches:

+

+

* master - development towards Luna/4.4

+

* 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 ====

==== Get an Eclipse SDK ====

Line 27:

Line 35:

==== Install the development tools ====

==== Install the development tools ====

−

You can install the development tools by using ''File>Import...>Install>Install Software Items from File''. Use http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiTools.p2f

+

The Eclipse SDK development requires that certain plug-ins are installed in your IDE. The Eclipse platform team provides a file from which these plug-ins can be installed. Download the following file onto your computer: http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiTools.p2f

+

+

You can install the plug-ins described by this file by using ''File>Import...>Install>Install Software Items from File''.

+

+

In case you plan to work on Kepler SR2, use the version from the R4_3_maintenance branch in Git.

==== Get the code for Platform UI ====

==== Get the code for Platform UI ====

−

First go to ''Preferences>Team>Git'' and update your ''Default Repository Folder'' so it points somewhere useful. Then 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

+

* 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).

−

==== Use the correct Target Platform ====

+

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:

* Modify the URL to point to the ''https'' version of the Gerrit repo location, https://gerritUserid@git...

+

* 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).

−

The code import should have included a org.eclipse.ui.releng project with a .target file in it. You can go to ''Preferences>Plug-in Development>Target Platform'' and choose platformUiTarget.target. That will download the correct target platform for Platform UI somewhere local.

+

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 ====

==== Tweaks for after your environment is set up ====

−

'''API Baseline Errors''': You can either unzip a version of Kepler (4.3.0) 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.

+

'''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.

'''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.

−

'''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 default to 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:

+

'''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:

* 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 changed files, 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.

* 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 etc. that are copied from the other UI plug-ins' settings.

* 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).

Line 143:

Line 163:

== 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.

+

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.

== Wiki==

== Wiki==

Revision as of 03:20, 14 May 2014

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.

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.

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.

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).

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.

Tweaks for after your environment is set up

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.

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:

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:

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

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. 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, 2014 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
*******************************************************************************/

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.

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

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.

Use the following format for your commit message:

Bug XXXX - bug title
<space>
Short description of what the fix contains, or the direction of the fix
<space>
Signed-off-by: email-with-CLA

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

We try to be prompt and responsive on the forum (newsgroup) but there's always room for improvement. If you know the answer to a query feel free to respond. 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

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.