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"

m (Bugs)
m ([4] Prepare API tooling: Correcting typo)
(157 intermediate revisions by 33 users not shown)
Line 1: Line 1:
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.
+
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.
 
{{Platform UI}}
 
{{Platform UI}}
 
== Bugs==
 
== Bugs==
If you find a bug, log it. Therefore, log into [https://bugs.eclipse.org/bugs/ Eclipse Bugzilla], create a new bug report for the project, and a description of how a [http://borisoneclipse.blogspot.com/2005/10/great-bug-report.html 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 you find a bug, log it. See the FAQ entry [[../FAQ#How_do_I_report_a_bug.3F|"How to Report a Bug"]], and a description of how a [http://borisoneclipse.blogspot.com/2005/10/great-bug-report.html 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:
 
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; you can employ the same technique for watching incoming IDE bugs, the Bugzilla user for that is called "Platform-IDE-Inbox@eclipse.org".  Depending upon your needs this might and might not be what you're looking for.
+
* 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.
+
* 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 [https://accounts.eclipse.org/mailing-list/platform-dev platform-dev@eclipse.org 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 for code contributions ==
 +
 
 +
There are two main ways to prepare your IDE to contribute to the Eclipse Platform.
 +
 
 +
* Manual SDK setup: The classic way. Mostly used by committers with custom IDEs.
 +
* Oomph automated setup: Good for occasional contributors. It makes it easy to contribute to multiple Platform projects.
 +
 
 +
If you are interested in contributing with Oomph, read: [https://wiki.eclipse.org/Platform_UI/How_to_Contribute/Oomph How to Contribute to Eclipse Platform using Oomph] or [https://wiki.eclipse.org/Eclipse_Platform_SDK_Provisioning Eclipse Platform SDK Provisioning].
 +
 
 +
The rest of this section explains the manual setup.
 +
 
 +
First, you need to set up your environment. You need to:
 +
 
 +
# Get an Eclipse SDK
 +
# Install the tools we use during development
 +
# Get the code for Platform UI
 +
# Use the correct target platform
 +
 
 +
 
 +
Active branches
 +
 
 +
Our currently active branches:
 +
 
 +
* master - development towards the next release
 +
 
 +
=== [1] Get an Eclipse SDK ===
 +
 
 +
To get the required updates from other subprojects it is recommended to use a recent I-Build for the Eclipse SDK for contributions. See http://download.eclipse.org/eclipse/downloads/ for the latest download.
 +
 
 +
=== [2] Install the development tools ===
 +
 
 +
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''.
 +
 
 +
=== [3] Get the code for Platform UI ===
 +
 
 +
Use one of the following two steps.
 +
 
 +
==== [3.1] Use Gerrit for clone/push ====
 +
To import the Platform UI projects into your workspace, select in Eclipse ''File>Import...>Team>Team Project Set''. Use  http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiProjectsGerrit.psf as input. After all projects are imported, you should see some repositories in "Gir Repository" perspective. In order for EGit to display Gerrit related options, you have to first configure Gerrit for each repository. Do this by selecting Remotes>orgin for a repository and selecting "Gerrit configuration..." from the context menu. Enter your username as it is displayed on the Settings page of your https://git.eclipse.org/ account.
 +
 
 +
'''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 [https://git.eclipse.org/r/#/settings/http-password ''Settings->HTTP Password''].
 +
 
 +
==== [3.2] Use ssh for clone/push ====
 +
 
 +
To import the Platform UI projects into your workspace, select in Eclipse ''File>Import...>Team>Team Project Set''. Use http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiProjects.psf as input.
 +
 
 +
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 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...
 +
* 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 [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 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] Prepare API tooling ===
 +
 
 +
Eclipse provides rich set of API's.
 +
Read about what an API is and how API's are evolving here:
 +
* https://wiki.eclipse.org/Evolving_Java-based_APIs
 +
* https://wiki.eclipse.org/Evolving_Java-based_APIs_2
 +
 
 +
API changes need to be properly reflected in bundle versions.
 +
Read about this here:
 +
* https://wiki.eclipse.org/Version_Numbering
 +
 
 +
If we contribute code to Eclipse, we always should make sure that our changes do not break API and do not violate version rules!
 +
 
 +
If the commit you want to merge contains an API change, '''before''' merge you should '''always''' load the patch into the IDE and run a clean build on related project.
 +
 
 +
Before doing so you should also make sure API tooling is properly configured. To achieve this you have to have the following preferences set under Window>Preferences:
 +
 
 +
* Plug in Development: tick [x] "Workspace Plug-Ins override target platform plug-ins with the same id"
 +
* Plug in Development: untick [ ] "Disable API analysis builder"
 +
* Plug in Development>Target Platform: This must bet set to "Running Platform" and you are using a recent nightly SDK build.
 +
* Plug in Development>API Baselines: The latest release must be ticked. This must be created manually and point to plain SDK installation of the last official SDK release.
 +
 
 +
If after that you see API errors in the workspace, please consider to read the proposed solution, compare that with the information you can get at [1], [2] and [3] and apply appropriated fix (or "-1" on the Gerrit patch).
 +
 
 +
There can be multiple possible API error fixes proposed by PDE, but only one can be the right one - unfortunately we still require the power of human brain to apply the '''right''' fix.
 +
 
 +
Basic rule is: during a development cycle (e.g. 4.12) we only increment one version segment '''one time''' according to the rules [1], [2] and [3]. Only in case of human errors we have to bump the same version segment
 +
twice (once the wrong version is built and '''published''' we can't simply revert it so we must increase again...).
 +
'''Note''': We never decrement versions if they were already published via official SDK build.
 +
 
 +
Decision about '''which''' bundle version segment to change should be always based on [1], [2] and [3], not just on PDE "quick fix" proposals. In doubt - ask on the [https://accounts.eclipse.org/mailing-list/platform-dev platform-dev mailing list].
 +
 
 +
[1] https://wiki.eclipse.org/Version_Numbering
 +
 
 +
[2] https://wiki.eclipse.org/Evolving_Java-based_APIs
 +
 
 +
[3] https://wiki.eclipse.org/Evolving_Java-based_APIs_2
 +
 
 +
=== [5] Tweaks for after your environment is set up ===
 +
 
 +
'''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
  
 
== Contributing Code==
 
== 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.
 
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.
  
=== Checking out the Plug-ins===
+
Platform UI is using Git as version control system.
There are three kinds of plug-ins, the actual code, test plug-ins, and example plug-ins. Using the CVS Repository at :pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse, they are listed under HEAD/platform-ui, HEAD/platform-ui-examples, and HEAD/platform-ui-tests.
+
  
We recommend using a recent integration build from the [http://download.eclipse.org/eclipse/downloads/ Eclipse Project download page] to avoid compile errors due to older versions of SWT or one of the runtime bundles that we depend upon.
+
=== More information about getting the code into your workspace ===
  
To check out everything from within Eclipse, do the following:
+
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.
# Type Ctrl+3 followed by 'npfc' to narrow down to "New Projects from CVS".
+
# Hit Enter to open the wizard dialog, then select "Create new repository location", and click Next.
+
# Copy the following string without the quotes into the "Host" field: ":pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse".
+
# Click Next, select "Use existing module", scroll all the way down and multi-select platform-ui, platform-ui-examples, and platform-ui-tests.
+
# Click Finish to import all of our plug-ins into your workspace. A dialog asking to replace "org.eclipse.jface.databinding.examples" is expected (it appears in the tests and the examples module), just click "Yes" or "No", it doesn't really matter.
+
  
<b>New in 3.6:</b>If you know the plugins you are working with, you can use File > Import... >Plug-in Development>Plug-ins and fragments wizard to import plugins directly from the repository. See [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/import_wizards/import_plugins.htm Plug-in Import].
 
  
To check out individual parts such as only data binding, or JFace, use [http://www.eclipse.org/eclipse/platform-ui/psf/ Project Set Files]. You can import the file into Eclipse via Ctrl+3, 'tpsi'. This will check out the necessary projects into your workspaceWe provide Project Sets for committers and contributors and for HEAD and maintenance branches. Please file a bug if you would like to have other kinds of project set files added to that page.
+
Our code is now contained in the git repo at
 +
git://git.eclipse.org/gitroot/platform/eclipse.platform.ui.git
 +
https://&lt;userid&gt;@git.eclipse.org/r/platform/eclipse.platform.ui
 +
  ssh://&lt;userid&gt;@git.eclipse.org:29418/platform/eclipse.platform.ui
  
=== Creating a Patch===
+
The Dependency Injection and runtime Eclipse Context code is in
To contribute a patch, open the Synchronize view, and set it up to synchronize your complete workspace with the CVS repository. Double-check your changes by looking at them using the compare editor (double-click on changed files in the Synchronize view). The changes should be minimal and without extraneous whitespace changes. Select the changed files and create a patch using the "Create Patch..." wizard from the context menu. Save the patch to a file called patch-<bugid>.txt and use the default settings (diff output format: unified, patch root: workspace). Then, attach this file to the bug. Added bonus points for also providing unit tests, which should be put into the same patch file - see the next section on unit tests.
+
git://git.eclipse.org/gitroot/platform/eclipse.platform.runtime.git
 +
https://&lt;userid&gt;@git.eclipse.org/r/platform/eclipse.platform.runtime
 +
ssh://&lt;userid&gt;@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://&lt;userid&gt;@git.eclipse.org/r/e4/org.eclipse.e4.tools
 +
ssh://&lt;userid&gt;@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://&lt;userid&gt;@git.eclipse.org/r/platform/eclipse.platform.ua
 +
ssh://&lt;userid&gt;@git.eclipse.org:29418/platform/eclipse.platform.ua
 +
 
 +
 
 +
=== Experimenting with a fork ===
 +
 
 +
While you're still in experimentation phase and your code is not ready to be proposed as a contribution, we recommend you to work with a '''fork''' of the Git repository and to work with your '''branches on this fork'''. This process will make it easier for you to turn your experiment into a proposal as a Gerrit patch proposal (see below) when ready.
 +
 
 +
You can then reference your branches on the related bugs or discussions to share your progress with other contributors.
 +
 
 +
Several services do offer Git repository hosting. If you choose GitHub, you can start by forking the [https://github.com/eclipse?utf8=%E2%9C%93&q=platform&type=&language= GitHub mirror] of your choice and work with branches on your forked repo; '''do NOT use pull-requests against mirrors''' (those are ignored)! If you'd like to already take advantage of the Eclipse Fondation governance offer as you're experimenting, please consider getting in touch with the [https://dev.eclipse.org/mhonarc/lists/e4-dev/ e4 project] which can offer you either a sandbox repo, or a fork of a Platform repo to work with at Eclipse.org.
 +
 
 +
=== 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 [https://wiki.eclipse.org/Platform_UI/How_to_Contribute#Commit_Message_Conventions correct commit format], this is done automatically by the Eclipse infrastructure.
 +
 
 +
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===
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.
+
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:
 
There are a couple of things that you should know about our testing process:
Line 38: Line 189:
 
* 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.
 
* 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 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.
+
* If you want to make a good impression, write tests. This goes for any project, of course.
  
 
=== Coding Conventions ===
 
=== Coding Conventions ===
* Follow the Eclipse Platform's [http://dev.eclipse.org/conventions.html Standards, Conventions and Guidelines].
+
* Follow the Eclipse Platform's [[Development Conventions and Guidelines]].
* 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.
+
* 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:
 +
{{codeblock|/*******************************************************************************
 +
* Copyright (c) 2015, 2016 [Your Company or your name] and others.
 +
*
 +
* This program and the accompanying materials
 +
* are made available under the terms of the Eclipse Public License 2.0
 +
* which accompanies this distribution, and is available at
 +
* https://www.eclipse.org/legal/epl-2.0/
 +
*
 +
* SPDX-License-Identifier: EPL-2.0
 +
*
 +
* 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 &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).
* Don't put CVS headers in the files (with revision information etc.)
+
* It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them.
* 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.
+
* 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
* It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them, they can crop up due to compiler changes occassionally.
+
* Use unix line delimiters (In Eclipse select Window-> Properties -> Workspace and set the file delimiter to Unix
* Non-externalized strings are considered errors, do not ship non-externalized strings.
+
* 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.
 +
 +
 +
=== Optional: Update the copyright header for existing files ===
 +
For changed files, you can optionally 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:
 +
{{codeblock|/*******************************************************************************
 +
* Copyright (c) 2008, 2016 IBM Corporation and others.
 +
*
 +
* This program and the accompanying materials
 +
* are made available under the terms of the Eclipse Public License 2.0
 +
* which accompanies this distribution, and is available at
 +
* https://www.eclipse.org/legal/epl-2.0/
 +
*
 +
* SPDX-License-Identifier: EPL-2.0
 +
*
 +
* Contributors:
 +
*    IBM Corporation - initial API and implementation
 +
*    John Doe <John.Doe@eclipse.org> - Bug 429728
 +
*******************************************************************************/}}
 +
 +
=== Commit Message Conventions ===
 +
 +
* Trivial, clean-ups and non-controversial changes (like typos) can be committed without a bug. Clean-up patches are patches which improve the code structure, remove deprecations, code warnings and the like. If clean-up patches are very invasive or big consider also creating a bug for them, to allow easier tracking.
 +
* Commits with functional changes or bug fixes require a [https://bugs.eclipse.org/bugs/ bug] entry.
 +
* 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 ===
  
* 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: &quot;Fixed bug xxx: &lt;title of bug&gt;&quot;. The &quot;bug xxxx&quot; 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).
+
* 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: &quot;Fixed bug xxx: &lt;title of bug&gt;&quot;. The &quot;bug xxxx&quot; 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.
 
* 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.
 
* Don't commit your changes if this will cause compile errors for others.
  
 
=== The Build===
 
=== 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 [http://dev.eclipse.org/mhonarc/lists/platform-releng-dev/msg09764.html clown nose] if it was really bad). If you do one thing it should be to sign up for the [https://dev.eclipse.org/mailman/listinfo/platform-releng-dev 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.
+
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 [http://dev.eclipse.org/mhonarc/lists/platform-releng-dev/msg09764.html clown nose] if it was really bad). If you do one thing it should be to sign up for the [https://dev.eclipse.org/mailman/listinfo/platform-releng-dev 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.
  
== Newsgroup==
+
===Adding a Note and Noteworthy entry===
We try to be prompt and responsive on the [http://www.eclipse.org/newsportal/thread.php?group=eclipse.platform newsgroup] but there's always room for improvement. If you know the answer to a query feel free to respond.
+
 
 +
To add to the N&N clone the repo listed here: https://git.eclipse.org/r/#/admin/projects/www.eclipse.org/eclipse/news
 +
Check existing entries for how to describe new entries.
 +
 
 +
The plug-in is "platform news" and it contains instructions.html. Frequently the following rules are missed:
 +
 
 +
* The image should be no more than 720 pixels wide and in png format
 +
* Use the [http://validator.w3.org/#validate_by_input Markup Validation Service] to check your document's markup submitting.
 +
 
 +
=== Contributing to maintenance release branches ===
 +
 
 +
In order to push commit to R4_XX_maintenance branch, one must follow RC2 criteria, which are:
 +
 +
"All fixes submitted must have a project lead or PMC vote on the bug report, and the fix must be reviewed by an additional committer (any committer other than the one who made the fix). A positive review from a project lead or PMC member means implicit approval and no vote is needed on the bug report."
 +
 +
So the algorithm to follow is:
 +
 +
# On gerrit with backported patch ask for the "+1" review from or from PL/PMC or from a committer that was not the original patch owner. The committer who backports the patch but is not the owner of the original patch, is also allowed to vote with "+1".
 +
# If the "+1" reviewer on gerrit is not PL/PMC, ask them in a comment on original bug for an explicit "+1" for backporting.
 +
# If 1) and 2) are successfully done, and tests are OK, gerrit can be merged.
 +
# API changes or new features backported require additionally explicit PMC approval.
 +
 +
See also https://www.eclipse.org/lists/platform-releng-dev/msg36074.html and https://www.eclipse.org/eclipse/development/plans/freeze_plan_4_15.php
 +
 
 +
== Forum ==
 +
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.
 +
 
 +
== Suggested information sources ==
 +
Being well informed is a must for an active community member. Following information sources can be useful:
 +
* One can watch the following mailing lists in Bugzilla (https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email):
 +
cross-project.inbox@eclipse.org, eclipse.org-architecture-council@eclipse.org, equinox.compendium-inbox@eclipse.org, equinox.components-inbox@eclipse.org,equinox.framework-inbox@eclipse.org, equinox.launcher-inbox@eclipse.org, equinox.p2-inbox@eclipse.org, equinox.security-inbox@eclipse.org, jdt-core-inbox@eclipse.org, jdt-debug-inbox@eclipse.org, jdt-text-inbox@eclipse.org, jdt-ui-inbox@eclipse.org, pde-apitools-inbox@eclipse.org, pde-core-inbox@eclipse.org, pde-ui-inbox@eclipse.org, platform-ant-inbox@eclipse.org, platform-compare-inbox@eclipse.org, platform-debug-inbox@eclipse.org, platform-releng-inbox@eclipse.org, platform-resources-inbox@eclipse.org, platform-runtime-inbox@eclipse.org, platform-search-inbox@eclipse.org, platform-swt-inbox@eclipse.org, platform-team-inbox@eclipse.org, platform-text-inbox@eclipse.org, Platform-UI-Inbox@eclipse.org, platform-ui-triaged@eclipse.org, swt-triaged@eclipse.org
 +
* One can add projects of interest in Gerrit (https://git.eclipse.org/r/#/settings/projects).
 +
* One can subscribe to the following mailing lists:
 +
[1] https://accounts.eclipse.org/mailing-list/eclipse-dev
 +
 
 +
[2] https://accounts.eclipse.org/mailing-list/ide-dev
 +
 
 +
[3] https://accounts.eclipse.org/mailing-list/pde-dev
 +
 
 +
[4] https://accounts.eclipse.org/mailing-list/platform-dev
 +
 
 +
[5] https://accounts.eclipse.org/mailing-list/cross-project-issues-dev
 +
 
 +
[6] https://accounts.eclipse.org/mailing-list/platform-releng-dev (5 mails a day)
 +
 
 +
== 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.
  
 
[[Category:Platform UI]][[Category:How to Contribute]]
 
[[Category:Platform UI]][[Category:How to Contribute]]
 +
 +
== Meetings ==
 +
 +
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:54, 28 December 2020

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-dev@eclipse.org 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

There are two main ways to prepare your IDE to contribute to the Eclipse Platform.

  • Manual SDK setup: The classic way. Mostly used by committers with custom IDEs.
  • Oomph automated setup: Good for occasional contributors. It makes it easy to contribute to multiple Platform projects.

If you are interested in contributing with Oomph, read: How to Contribute to Eclipse Platform using Oomph or Eclipse Platform SDK Provisioning.

The rest of this section explains the manual setup.

First, you need to set up your environment. You need to:

  1. Get an Eclipse SDK
  2. Install the tools we use during development
  3. Get the code for Platform UI
  4. Use the correct target platform


Active branches

Our currently active branches:

  • master - development towards the next release

[1] Get an Eclipse SDK

To get the required updates from other subprojects it is recommended to use a recent I-Build for the Eclipse SDK for contributions. See http://download.eclipse.org/eclipse/downloads/ for the latest download.

[2] Install the development tools

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.

[3] Get the code for Platform UI

Use one of the following two steps.

[3.1] Use Gerrit for clone/push

To import the Platform UI projects into your workspace, select in Eclipse File>Import...>Team>Team Project Set. Use http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiProjectsGerrit.psf as input. After all projects are imported, you should see some repositories in "Gir Repository" perspective. In order for EGit to display Gerrit related options, you have to first configure Gerrit for each repository. Do this by selecting Remotes>orgin for a repository and selecting "Gerrit configuration..." from the context menu. Enter your username as it is displayed on the Settings page of your https://git.eclipse.org/ account.

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.

[3.2] Use ssh for clone/push

To import the Platform UI projects into your workspace, select in Eclipse File>Import...>Team>Team Project Set. Use http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiProjects.psf as input.

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:

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] Prepare API tooling

Eclipse provides rich set of API's. Read about what an API is and how API's are evolving here:

API changes need to be properly reflected in bundle versions. Read about this here:

If we contribute code to Eclipse, we always should make sure that our changes do not break API and do not violate version rules!

If the commit you want to merge contains an API change, before merge you should always load the patch into the IDE and run a clean build on related project.

Before doing so you should also make sure API tooling is properly configured. To achieve this you have to have the following preferences set under Window>Preferences:

  • Plug in Development: tick [x] "Workspace Plug-Ins override target platform plug-ins with the same id"
  • Plug in Development: untick [ ] "Disable API analysis builder"
  • Plug in Development>Target Platform: This must bet set to "Running Platform" and you are using a recent nightly SDK build.
  • Plug in Development>API Baselines: The latest release must be ticked. This must be created manually and point to plain SDK installation of the last official SDK release.

If after that you see API errors in the workspace, please consider to read the proposed solution, compare that with the information you can get at [1], [2] and [3] and apply appropriated fix (or "-1" on the Gerrit patch).

There can be multiple possible API error fixes proposed by PDE, but only one can be the right one - unfortunately we still require the power of human brain to apply the right fix.

Basic rule is: during a development cycle (e.g. 4.12) we only increment one version segment one time according to the rules [1], [2] and [3]. Only in case of human errors we have to bump the same version segment twice (once the wrong version is built and published we can't simply revert it so we must increase again...). Note: We never decrement versions if they were already published via official SDK build.

Decision about which bundle version segment to change should be always based on [1], [2] and [3], not just on PDE "quick fix" proposals. In doubt - ask on the platform-dev mailing list.

[1] https://wiki.eclipse.org/Version_Numbering

[2] https://wiki.eclipse.org/Evolving_Java-based_APIs

[3] https://wiki.eclipse.org/Evolving_Java-based_APIs_2

[5] Tweaks for after your environment is set up

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

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


Experimenting with a fork

While you're still in experimentation phase and your code is not ready to be proposed as a contribution, we recommend you to work with a fork of the Git repository and to work with your branches on this fork. This process will make it easier for you to turn your experiment into a proposal as a Gerrit patch proposal (see below) when ready.

You can then reference your branches on the related bugs or discussions to share your progress with other contributors.

Several services do offer Git repository hosting. If you choose GitHub, you can start by forking the GitHub mirror of your choice and work with branches on your forked repo; do NOT use pull-requests against mirrors (those are ignored)! If you'd like to already take advantage of the Eclipse Fondation governance offer as you're experimenting, please consider getting in touch with the e4 project which can offer you either a sandbox repo, or a fork of a Platform repo to work with at Eclipse.org.

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.
* 
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
* 
* 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 optionally 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.
* 
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
* 
* Contributors:
*     IBM Corporation - initial API and implementation
*     John Doe <John.Doe@eclipse.org> - Bug 429728
*******************************************************************************/

Commit Message Conventions

  • Trivial, clean-ups and non-controversial changes (like typos) can be committed without a bug. Clean-up patches are patches which improve the code structure, remove deprecations, code warnings and the like. If clean-up patches are very invasive or big consider also creating a bug for them, to allow easier tracking.
  • Commits with functional changes or bug fixes require a bug entry.
  • 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.

Adding a Note and Noteworthy entry

To add to the N&N clone the repo listed here: https://git.eclipse.org/r/#/admin/projects/www.eclipse.org/eclipse/news Check existing entries for how to describe new entries.

The plug-in is "platform news" and it contains instructions.html. Frequently the following rules are missed:

  • The image should be no more than 720 pixels wide and in png format
  • Use the Markup Validation Service to check your document's markup submitting.

Contributing to maintenance release branches

In order to push commit to R4_XX_maintenance branch, one must follow RC2 criteria, which are:

"All fixes submitted must have a project lead or PMC vote on the bug report, and the fix must be reviewed by an additional committer (any committer other than the one who made the fix). A positive review from a project lead or PMC member means implicit approval and no vote is needed on the bug report."

So the algorithm to follow is:

  1. On gerrit with backported patch ask for the "+1" review from or from PL/PMC or from a committer that was not the original patch owner. The committer who backports the patch but is not the owner of the original patch, is also allowed to vote with "+1".
  2. If the "+1" reviewer on gerrit is not PL/PMC, ask them in a comment on original bug for an explicit "+1" for backporting.
  3. If 1) and 2) are successfully done, and tests are OK, gerrit can be merged.
  4. API changes or new features backported require additionally explicit PMC approval.

See also https://www.eclipse.org/lists/platform-releng-dev/msg36074.html and https://www.eclipse.org/eclipse/development/plans/freeze_plan_4_15.php

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.

Suggested information sources

Being well informed is a must for an active community member. Following information sources can be useful:

cross-project.inbox@eclipse.org, eclipse.org-architecture-council@eclipse.org, equinox.compendium-inbox@eclipse.org, equinox.components-inbox@eclipse.org,equinox.framework-inbox@eclipse.org, equinox.launcher-inbox@eclipse.org, equinox.p2-inbox@eclipse.org, equinox.security-inbox@eclipse.org, jdt-core-inbox@eclipse.org, jdt-debug-inbox@eclipse.org, jdt-text-inbox@eclipse.org, jdt-ui-inbox@eclipse.org, pde-apitools-inbox@eclipse.org, pde-core-inbox@eclipse.org, pde-ui-inbox@eclipse.org, platform-ant-inbox@eclipse.org, platform-compare-inbox@eclipse.org, platform-debug-inbox@eclipse.org, platform-releng-inbox@eclipse.org, platform-resources-inbox@eclipse.org, platform-runtime-inbox@eclipse.org, platform-search-inbox@eclipse.org, platform-swt-inbox@eclipse.org, platform-team-inbox@eclipse.org, platform-text-inbox@eclipse.org, Platform-UI-Inbox@eclipse.org, platform-ui-triaged@eclipse.org, swt-triaged@eclipse.org

[1] https://accounts.eclipse.org/mailing-list/eclipse-dev

[2] https://accounts.eclipse.org/mailing-list/ide-dev

[3] https://accounts.eclipse.org/mailing-list/pde-dev

[4] https://accounts.eclipse.org/mailing-list/platform-dev

[5] https://accounts.eclipse.org/mailing-list/cross-project-issues-dev

[6] https://accounts.eclipse.org/mailing-list/platform-releng-dev (5 mails a day)

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