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 "GEF/Contributor Guide"

< GEF
m
(70 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==Development Environment (Committers and Contributors)==
+
== Prepare your IDE ==
  
===Java Version===
+
=== Specify Execution Environment for J2SE-1.7 (and optionally J2SE-1.8) ===  
Currently GEF is built against Java 1.4. It is possible that future versions of GEF will migrate to Java 1.5 or higher versions (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=204605 Bug #204605]).
+
All GEF4 bundles with JavaFX dependencies are compatible to JavaFX 2.2 (or higher) and thus specify a J2SE-1.7 BREE (bundle required execution environment). In order to resolve the JavaFX dependencies, you will have to ensure that a Java 7 JVM, which provides JavaFX 2.2 (e.g. an Oracle JVM), is used to resolve the J2SE-1.7 execution environment. This is important, because the e(fx)clipse JavaFX-PDE integration (which we recommend to resolve JavaFX dependencies; JavaFX will not be visible on the OSGi classpath by default) will only be able to resolve JavaFX dependencies (of a bundle with J2SE-1.7 BREE), if the respective <code>jfxrt.jar</code> (which bundles the JavaFX 2.2 classes) can be located in the installation location of the JVM that is used to resolve the J2SE-1.7 execution environment.
  
===Eclipse Target Platform===
+
In order to ensure that this is the case, go to "Windows -> Preferences -> Java -> Installed JREs" and ensure a compatible Java SE 7, which provides JavaFX 2.2, is installed. Eclipse will automatically detect the jar libraries provided by the JVM and add it to the registration. Note that the <code>jfxrt.jar</code> will actually not be added to the JVM definition, and that it does not have to be manually added to it either, because the contained JavaFX classes will be added to the classpath of all bundles with javafx.* package imports (and J2SE-1.7 BREE) by the e(fx)clipse JavaFX-PDE-integration automatically (see below). To ensure that the respective JVM is used to resolve the J2SE-1.7 execution environment, go to "Windows -> Preferences -> Java -> Installed JREs -> Execution Environments" and select it there.  
A given version of GEF requires the exact same version of the Eclipse SDK as target, i.e. GEF 3.6 is for example built against Eclipse SDK 3.6. Target definition files are provided by the <code>org.eclipse.gef.target</code> project, which is located in the <code>dev</code> cvs sub-module. The GEF EDiagram example furthermore relies on a compatible EMF version; as the example is no longer maintained, this is not included in the target definition files.
+
  
===API Tooling ===
+
While all GEF4 bundles are compatible with JavaFX 2.2 and Java 7, you may decide to use JavaFX 8.0 and Java 8 in your client code. In this case, you will have to ensure that in addition to the Java SE 7 JVM, a compatible Java SE 8 JVM, which bundles JavaFX 8.0, is registered as installed JRE and specified to resolve the J2SE-1.8 execution environment. Note that here, the <code>jfxrt.jar</code> will be automatically added to the JRE definition when registering the Java 8 JVM. However, the <code>jfxswt.jar</code> will not be added (it contains the javax.embed.swt.* classes), and it also does not have to be manually added to the JVM definition as well, as it will be added to the classpath of all bundles with javafx.* package imports (and J2SE-1.8 BREE) by the e(fx)clipse JavaFX-PDE-integration.
The GEF development team uses the preceding GEF ALL SDK release version as a baseline to maintain API compatibility, i.e. for the 3.5.2 development, the API baseline is formed by GEF ALL 3.5.1, while for the 3.6.0 development, it is 3.5.0 respectively. API-baselines are provided by the <code>org.eclipse.gef.baseline</code> project, which is located in the <code>dev</code> cvs submodule. Checks for API breakages and evolutions are set per project and committed alongside them.
+
  
===Code Style (Formatting)===
+
=== Install e(fx)clipse JavaFX-PDE-integration ===
The GEF project uses the default built-in Eclipse formatter. Java-Editor Save-Actions are defined for each Java-nature plug-in of the GEF project to preserve formatting as well as organization of imports upon code changes. This was adopted in GEF 3.6.0RC2 (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=308372 Bug #308372]).
+
When developing against those GEF4 components that are dependent on JavaFX, it is recommended to install the e(fx)clipse JavaFX-PDE-Integration (<code>org.eclipse.fx.ide.pde.feature</code>) into your Eclipse development environment to properly resolve JavaFX dependencies within your workspace. It is needed because JavaFX is not included on any of the default OSGi classpaths, so JavaFX dependencies (specified as package imports) of the GEF4 bundles will otherwise not be properly resolved (unless you manually add the respective jars to your classpath, which is not recommended).
  
==Checking out the code (Committers and Contributors)==
+
While it is actually only necessary to install the <code>org.eclipse.fx.ide.pde.java7</code> bundle (which is bundled by the ''e(fx)clipse - IDE - PDE feature'' (<code>org.eclipse.fx.ide.pde.feature</code>) and (IMPORTANT!) also handles the JavaFX-integration for Java 8), it may come handy to install additional e(fx)clipse IDE features as well. All can either be installed from [http://download.eclipse.org/efxclipse/updates-released/0.9.0/site http://download.eclipse.org/efxclipse/updates-released/0.9.0/site] (for Kepler), [http://download.eclipse.org/efxclipse/updates-released/1.0.0/site http://download.eclipse.org/efxclipse/updates-released/1.0.0/site] (for Luna), or [http://download.eclipse.org/efxclipse/updates-nightly/site http://download.eclipse.org/efxclipse/updates-nightly/site] (for Mars).
  
All GEF source code is located in the Tools repository. Information about how to check out sources from there can be found in the [http://wiki.eclipse.org/CVS_Howto CVS Howto]. Most, easily you may use the Team Project Set File provided below.
+
Having installed the e(fx)clipse JavaFX-PDE-integration in your development environment, it will automatically add additional classpath entries for those bundles that specify javafx.* package imports. It requires that a JVM, which provides JavaFX, is registered as an installed JRE and is used to resolve the execution environment matching that of the respective bundle (as outlined above).
  
===Using Team Project Set File (PSF)===
+
=== Install API Tools Execution Environment Descriptions ===
* Download the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.gef/dev/gef_all.psf?root=Tools_Project&view=markup Team Project Set (.psf) file] and save it on your computer.
+
All production code GEF and GEF4 bundles (i.e. excluding doc and test bundles) are configured to have API tooling enabled. The API checks, which are configured on a project-specific basis, include checks for references that do not exist in the specified execution environment. As API tooling requires execution environment descriptions to perform the respective checks, these should be installed (you will see warnings for missing execution environment descriptions otherwise otherwise), as outline under [[Execution_Environments#Installing Execution Environment Descriptions]].
* Open Eclipse and switch to the Java perspective.
+
 
* Through the File menu, select File => Import and in the Import popup, select Team => Team Project Set and hit "Next".
+
=== Install CDO Version Management Tool ===
* Select the Team Project Set (psf) file you saved on your disk.
+
In addition to the API Tools, for the GEF bundles (currently not for GEF4 as there all API is yet provisional) we make use of the [[CDO/Version_Management_Tool | CDO Version Management Tool]] to ensure service revision increments are performed as needed (the tool will provide indications of which bundle and feature versions to update when performing changes on the service level). Please install it from the [http://download.eclipse.org/modeling/emf/cdo/updates/integration CDO integration update site].  
* Eclipse might prompt you to create the CVS repository. Do so by either choosing a pserver connection with "anonymous" as your user name and a blank password, or extssh connection with your respective credentials in case you are a commiter.
+
 
* Each plugin of the GEF project will now be checked out in your workspace.
+
=== Install Maven Integration (m2e) ===
 +
In case you want to run a headless build locally in your workspace, you should install the [http://eclipse.org/m2e/ Maven Integration (m2e)], as GEF and GEF4 builds are based on Maven/Tycho.
 +
 
 +
==Obtaining Source Code ==
 +
 
 +
The complete source code of the GEF project (with the exception of the web-site) is hosted at [http://git.eclipse.org/c/?ofs=50 http://git.eclipse.org]:
 +
 
 +
* The GEF proper code base (Draw2d and GEF (MVC) 3.x as well as Zest 1.x ) can be found in the [http://git.eclipse.org/c/gef/org.eclipse.gef.git/ GEF Git repository]
 +
* The [[GEF/GEF4 | GEF4]] provisional code base can be found in the [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/ GEF4 Git repository].
 +
 
 +
=== Check out the code (Committers and Contributors) using EGit===
 +
 
 +
To check out the code within your local workspace, perform the following steps:
 +
# Copy the URI of the repository you want to clone (following the links provided above, the URIs are listed under the ''Clone'' section). Note that committers will have to use the ''ssh'' protocol URI, whereas consumers and contributors are encouraged to use the ''git'' protocol URI.
 +
# Clone the Git repository
 +
## Open the ''Git Repository Exploring Perspective'' (provided by EGit) within Eclipse, and from the toolbar of the ''Git Repositories Browser'' view select to ''Clone a Git Repository and add the clone to this view''.  
 +
## If the repository URL was copied to clipboard before, the upcoming ''Clone Git Repository'' dialog should already provide the necessary entries for ''URI'', ''Host'', and ''Repository path'', so you may simple forward by pressing ''Next >''.
 +
## Select the branches you want to clone from remote. The ''master'' branch is the one used for the current development stream. Development in maintenance releases is performed in respective maintenance branches. After having selected all branches of interest, press ''Next >'' to continue.
 +
## Choose a local directory to store the cloned repository (the default will be located under your home directory) and select the ''Initial branch'' to check out.
 +
# Checkout the projects
 +
## Right-click the ''Working directory'' entry, located under the ''org.eclipse.gef'' (resp. ''org.eclipse.gef4'') repository within the ''Git Repositories Browser'' view and from the context menu select to ''Import Projects...''.
 +
## In the upcoming ''Import Projects from Git Repository'' dialog, select to ''Import existing projects'' and press ''Next >''.
 +
## Choose the projects you want to import (by default all are selected) and press ''Finish'' to conclude.
 +
 
 +
== Setting up the workspace ==
 +
 
 +
===Set up the Target Platform===
 +
A target definition file is provided by the <code>org.eclipse.gef.target</code> (as well as the <code>org.eclipse.gef4.target</code>) project. To specify the target platform, simply open the respective target definition (e.g. ''MARS.target'') within the ''Target Editor'', let is fully resolve (i.e. wait until the ''Resolving Target Definition'' background task has finished and the installable units are listed under the respective ''Locations''), then choose to "Set as Target Platform'').
 +
 
 +
In case the target editor does not properly resolve the target definition, an invalid target cache may be the cause. In such cases, opening the target definition file with a text editor and incrementing the sequence number manually, will invalidate the cache when reopening it with the target editor again. After the cache has been invalidated, the sequence number can be restored.
 +
 
 +
===Set up API Tooling ===
 +
GEF (proper) uses PDE API tooling to guarantee proper handling of version numbering as well as API compatibility, so without definition of an API baseline you will see compile problems after having checked out the code. API-baselines are provided by the <code>org.eclipse.gef.baseline</code> project. You may define them by going to ''Preferences -> Plug-in Development -> API Baselines'', then choose to select "Add Baseline..." and point to the <code>plugins</code> sub-folder of an API baseline located in the baselines project (note that the dialog browses the file system instead of the workspace, so you will have to point into the respective folder in your local Git repository).
 +
 
 +
===Adjust Java and Plug-in Compiler Preferences (Discouraged access errors/warnings caused by provisional API)===
 +
As all GEF4 API is currently released as '''provisional''', all GEF4 API package exports are guarded with the ''x-internal'' directive (see [[#Marking stable, provisional, and non-API | Marking stable, provisional, and non-API]] for details). Dependent on your workspace settings, this may lead to a lot of Java compiler warnings/errors, which result from discouraged API access. You may want to adjust your workspace-wide Java and Plug-in compiler preferences to get rid of them.  
 +
* Go to "Preferences -> Java -> Compiler -> Warnings/Errors", then select the respective severity ("Warning", "Ignore") for the "Deprecated and restricted API -> Discouraged reference (access rule)" entry.
 +
* Go to "Preferences -> Plug-in Development -> Compilers", then select the respective severity ("Warning", "Ignore") for the "References ->References to discouraged classes" entry.
 +
 
 +
== Coding conventions ==
 +
 
 +
=== Marking stable, provisional, and non-API ===
 +
 
 +
According to the Eclipse [https://wiki.eclipse.org/Provisional_API_Guidelines Provisional API Guidelines] and the [https://wiki.eclipse.org/index.php/Naming_Conventions Naming Conventions], the following conventions are followed to differentiate between stable, provisional, and non-API (see also [https://bugs.eclipse.org/bugs/show_bug.cgi?id=438900 bug #438900]):
 +
 
 +
* Stable API: All stable API packages do not contain 'internal' in their package names and are exposed via 'Export-Package' in the plug-in MANIFEST.MF, unguarded by 'x-friends' or 'x-internal' directives.
 +
* Provisional API: All provisional API packages do not contain 'internal' in their package names and are exposed via 'Export-Package' in the plug-in MANIFEST.MF, guarded by an 'x-internal' directive.
 +
* Non-API: All non-API packages contain 'internal' in their package names , e.g. <code>org.eclipse.gef4.internal.geometry.utils</code>. These packages should only be exposed via 'Expose-Package' in the plug-in MANIFEST.MF, if this is guarded by an 'x-friends' directive.
 +
 
 +
Please note that for the Mars release, all of the GEF4 API will still be provisional (i.e. all API packages are provisional API packages). This will cause a lot of warnings/errors in your workspace, unless you follow the guidance given [[#Adjust Java and Plug-in Compiler Preferences (Discouraged access errors/warnings caused by provisional API)| Adjust Java and Plug-in Compiler Preferences]].
 +
 
 +
== Starting an (Eclipse Application) runtime, resolving JavaFX runtime dependencies ==
 +
When launching an Eclipse runtime that contains GEF4 bundles with JavaFX dependencies, the e(fx)clipse <code>org.eclipse.fx.javafx</code> bundle <code>org.eclipse.fx.osgi</code> fragment have to be included in the runtime configuration (they are already included in the GEF4 target). Also, <code>-Dosgi.framework.extensions=org.eclipse.fx.osgi</code> has to be added to the ''VM arguments'' in the runtime configuration's ''Arguments'' tab. If you are having problems with the e(fx)clipse runtime resolution you can add <code>-Defxclipse.osgi.hook.debug=true</code> to the ''VM arguments'' to enable debugging output. We noticed that e(fx)clipse does not seem to work correctly when running SWT on GTK 3 on older GTK versions. In this case, you can enforce SWT to use GTK 2 by setting the environment variable <code>SWT_GTK3=0</code> or adding <code>--launcher.GTK_version 2</code> to your eclipse.ini.
  
 
== Running a headless build locally ==
 
== Running a headless build locally ==
 +
GEF (as well as [[GEF/GEF4 | GEF4]]) uses a Maven/Tycho-based build infrastructure. With the [http://eclipse.org/m2e/ Maven Integration] installed, the headless build that is executed by the [https://hudson.eclipse.org/hudson/job/gef-master/ gef-master] and [https://hudson.eclipse.org/hudson/job/gef4-master/ gef4-master] Hudson build jobs can also be executed in the local workspace. Make sure you have checked out all projects of a respective git repository (GEF and GEF4 are independent). Then easily run the build by right-clicking the <code>pom.xml</code> file located within the <code>org.eclipse.gef.releng</code> or <code>org.eclipse.gef4.releng</code> project respectively, and selecting 'Run As -> Maven build...'.
  
Beginning with GEF 3.8.0M5, GEF has adopted a Maven/Tycho-based build infrastructure (see bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=363394 #363394] for details). With the [http://eclipse.org/m2e/ Maven Integration] installed, the headless build that is executed by a [https://hudson.eclipse.org/hudson/job/gef-nightly-tycho/ Hudson job] can also be executed in the local workspace. Make sure you have checked out all projects listed within the Team Project Set provided above. Then easily run the build by right-clicking the <code>pom.xml</code> file located within the <code>org.eclipse.gef.releng</code> project, and selecting 'Run As -> Maven install'.
+
In the configuration wizard you have to specify the goals ("clean verify") and the profiles ("Mars.target") for the build. Note that without setting the target profile the build will not run successfully.
  
==Committing code (Committers Only)==
+
[[Image:GEF-ContributorGuide-Build-Locally-Main.png]]
  
===CVS Comments===
+
You should select a Java-8 JVM in the "JRE" tab, to ensure that you run with a configuration comparable to that of the CI-server (hudson.eclipse.org). Otherwise your local build might behave differently compared to the continuous CI build. For example, javadoc errors are will not lead to a build failure when running with Java-7, while the build will fail if using Java-8 (as done in the CI server build jobs).
The GEF development team uses the following format for commit comments:
+
  
Format: ''[<bug-id>] <affected-branch> <contributor> <commit-date> <bug-summary>''
+
[[Image:GEF-ContributorGuide-Build-Locally-JRE.png]]
  
Example: ''[213359] gef-head crevells 071221 Make GEF's snapping and tools extensible to allow moving shapes with arrow keys''
+
As a result of the build, an update-site will be created in the <code>target</code> sub-folder of the <code>org.eclipse.gef.repository</code> respectively <code>org.eclipse.gef4.repository</code> project. Please note that you need to have a JDK installed (and used by Tycho) rather than a JRE, because the Tycho builds rely on the availability of a javadoc executable for the generation of API documentation in the doc bundles.
  
While the branch the code was committed to, the originator of the contribution and the commit date may possibly be redundant (since we are duplicating the information in CVS and they are already in the history), but it has been found useful to easily figure out what the actual change was. Note that in case of a third-party contribution (patch) the name of the contributor and not the committer name will be included in the comment.
+
== Creating a Contribution  ==
 +
You can contribute to GEF either by producing a patch, or via GitHub. In either case, your contribution should be related to a corresponding Bugzilla entry (you can search for [http://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;product=GEF existing bugs], or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=GEF file a new one]).  
  
== Bug Handling Policy ==
+
We can easily consume your contribution (compare [http://eclipse.org/legal/EclipseLegalProcessPoster.pdf Eclipse Legal Process]), if:
 +
* you have signed the Eclipse Contributor License Agreement (see [https://www.eclipse.org/legal/CLA.php Eclipse Foundation Contributor License Agreement]), and
 +
* you have stated (in the corresponding Bugzilla entry) that the contribution was developed from scratch, without incorporating content from elsewhere, and that you are authorized to contribute it under the EPL.
 +
 
 +
If your contribution does not exceed the contribution limit (currently 1000 LOC) this will allow us to simply consume it. If your contribution was not developed from scratch or contains content from other authors, please indicate this on the related Bugzilla entry. As in cases where the contribution exceeds the limit, we will have to open a contribution questionnaire (and may have to ask for additional information via the related Bugzilla) to handle such cases (see [http://eclipse.org/legal/EclipseLegalProcessPoster.pdf Eclipse Legal Process]).
 +
 
 +
===Produce a Patch===
 +
To contribute a patch, create a branch in your local Git repository for working on your changes, e.g. a fix for {{bug|321775}}:
 +
 
 +
git checkout -b fix-321775
 +
 
 +
Test, fix, and commit until you're done. Run the Maven build to make sure everything works. Then create a patch including all commits on your branch against master, like this:
 +
 
 +
git format-patch master --stdout > fix-321775.patch
 +
 
 +
Finally, attach your patch to the corresponding bug, in this case bug 321775.
 +
 
 +
===Fork via GitHub===
 +
To contribute via GitHub, fork the GitHub repository you'd like to contribute to from [https://github.com/eclipse https://github.com/eclipse] (i.e. the [https://github.com/eclipse/gef GEF] or [https://github.com/eclipse/gef4 GEF4]. Commit, test, and push your contribution to your fork. When you're done, add a link to the Github commit you want to contribute to a comment in the corresponding bugzilla entry, e.g.:
 +
 
 +
  https://github.com/ujhelyiz/zest/commit/c1a69026477f0852727a2132233e9e61c14b4d8d
 +
 
 +
For details, see [[Development_Resources/Handling_Git_Contributions]].
 +
 
 +
==Commiting  code==
 +
 
 +
===Comments===
 +
When committing code, the following format should be used:
 +
 
 +
  '[' ( <bug-id> | 'NONE' ) ']' <one-line-summary-or-single-line-commit-message> (  '(' 'CQ' <cq-number> ')' )?
 +
 
 +
  ( <wrapped-detailed-commit-message> )?
 +
 
 +
Examples:
 +
 
 +
  [355997] Add support for calculating bezier curve intersections. (CQ 5976)
 +
 
 +
  [NONE] Update target definition to Eclipse SDK 4.2.0.I20120222-0915.
 +
 
 +
Furthermore, the following constraints should be regarded:
 +
* The bug id of the bug, which is used to track the changes should always be provided, or NONE to indicate that the changes are made without any directly related bug.
 +
* The commit message should be specified using present tense, declaring why the changes were made.
 +
* If a commit message is longer than one short line, it should be formatted to have a short, one-line summary, a blank line, and a wrapped longer description (see [http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html].
 +
* If the committer is not the contributor of the changes, the Git author field should be used to specify the full name of the contributor (see [[Development_Resources/Handling_Git_Contributions]]). In case the changes were approved by means of a contribution questionnaire, the CQ number should be specified in round brackets after the one line summary.
 +
 
 +
== Handling Bugs ==
 
When working with bugzillas, the following guidelines should be regarded.
 
When working with bugzillas, the following guidelines should be regarded.
  
=== Resolving Policy ===
+
=== Classifying Bugs ===
When resolving bugzillas, it should be stated how the bug is verified. Preferably this is a JUnit test. Alternatively, the bugzilla will say that the defect can be reproduced in the Logic example and you can demonstrate the fix working in the logic example (or other examples using GEF). If the bug is trivial or obvious and does not require a test, we can just state this in the Bugzilla too.
+
For GEF4, components are pretty fine-grained, so selection of a bugzilla component is usually sufficient to identify the part of the API that is concerned.
  
=== Categorization Policy ===
+
For Draw2d/GEF (MVC) 3.x this may not be sufficient. We thus use categories for this issue, which will be stated as a [<category_name>] prefix within the bugzilla's summary. The list of currently used categories is:
Despite selecting a component, a bugzilla may be classified to more precisely specify, what part of the GEF API is concerned. We use categories for this issue, which will be stated as a [<category_name>] prefix within the bugzilla's summary. The list of currently used categories is:
+
  
 
* General
 
* General
Line 65: Line 160:
 
** [Print]
 
** [Print]
 
** [Tool]
 
** [Tool]
 +
 +
=== Resolving Policy ===
 +
When resolving bugzillas, it should be stated how the bug is verified. Preferably this is a JUnit test. Alternatively, the bugzilla will say that the defect can be reproduced in the Logic example and you can demonstrate the fix working in the logic example (or other examples using GEF). If the bug is trivial or obvious and does not require a test, we can just state this in the Bugzilla too.
  
 
[[Category:GEF]]
 
[[Category:GEF]]

Revision as of 06:32, 4 December 2014

Prepare your IDE

Specify Execution Environment for J2SE-1.7 (and optionally J2SE-1.8)

All GEF4 bundles with JavaFX dependencies are compatible to JavaFX 2.2 (or higher) and thus specify a J2SE-1.7 BREE (bundle required execution environment). In order to resolve the JavaFX dependencies, you will have to ensure that a Java 7 JVM, which provides JavaFX 2.2 (e.g. an Oracle JVM), is used to resolve the J2SE-1.7 execution environment. This is important, because the e(fx)clipse JavaFX-PDE integration (which we recommend to resolve JavaFX dependencies; JavaFX will not be visible on the OSGi classpath by default) will only be able to resolve JavaFX dependencies (of a bundle with J2SE-1.7 BREE), if the respective jfxrt.jar (which bundles the JavaFX 2.2 classes) can be located in the installation location of the JVM that is used to resolve the J2SE-1.7 execution environment.

In order to ensure that this is the case, go to "Windows -> Preferences -> Java -> Installed JREs" and ensure a compatible Java SE 7, which provides JavaFX 2.2, is installed. Eclipse will automatically detect the jar libraries provided by the JVM and add it to the registration. Note that the jfxrt.jar will actually not be added to the JVM definition, and that it does not have to be manually added to it either, because the contained JavaFX classes will be added to the classpath of all bundles with javafx.* package imports (and J2SE-1.7 BREE) by the e(fx)clipse JavaFX-PDE-integration automatically (see below). To ensure that the respective JVM is used to resolve the J2SE-1.7 execution environment, go to "Windows -> Preferences -> Java -> Installed JREs -> Execution Environments" and select it there.

While all GEF4 bundles are compatible with JavaFX 2.2 and Java 7, you may decide to use JavaFX 8.0 and Java 8 in your client code. In this case, you will have to ensure that in addition to the Java SE 7 JVM, a compatible Java SE 8 JVM, which bundles JavaFX 8.0, is registered as installed JRE and specified to resolve the J2SE-1.8 execution environment. Note that here, the jfxrt.jar will be automatically added to the JRE definition when registering the Java 8 JVM. However, the jfxswt.jar will not be added (it contains the javax.embed.swt.* classes), and it also does not have to be manually added to the JVM definition as well, as it will be added to the classpath of all bundles with javafx.* package imports (and J2SE-1.8 BREE) by the e(fx)clipse JavaFX-PDE-integration.

Install e(fx)clipse JavaFX-PDE-integration

When developing against those GEF4 components that are dependent on JavaFX, it is recommended to install the e(fx)clipse JavaFX-PDE-Integration (org.eclipse.fx.ide.pde.feature) into your Eclipse development environment to properly resolve JavaFX dependencies within your workspace. It is needed because JavaFX is not included on any of the default OSGi classpaths, so JavaFX dependencies (specified as package imports) of the GEF4 bundles will otherwise not be properly resolved (unless you manually add the respective jars to your classpath, which is not recommended).

While it is actually only necessary to install the org.eclipse.fx.ide.pde.java7 bundle (which is bundled by the e(fx)clipse - IDE - PDE feature (org.eclipse.fx.ide.pde.feature) and (IMPORTANT!) also handles the JavaFX-integration for Java 8), it may come handy to install additional e(fx)clipse IDE features as well. All can either be installed from http://download.eclipse.org/efxclipse/updates-released/0.9.0/site (for Kepler), http://download.eclipse.org/efxclipse/updates-released/1.0.0/site (for Luna), or http://download.eclipse.org/efxclipse/updates-nightly/site (for Mars).

Having installed the e(fx)clipse JavaFX-PDE-integration in your development environment, it will automatically add additional classpath entries for those bundles that specify javafx.* package imports. It requires that a JVM, which provides JavaFX, is registered as an installed JRE and is used to resolve the execution environment matching that of the respective bundle (as outlined above).

Install API Tools Execution Environment Descriptions

All production code GEF and GEF4 bundles (i.e. excluding doc and test bundles) are configured to have API tooling enabled. The API checks, which are configured on a project-specific basis, include checks for references that do not exist in the specified execution environment. As API tooling requires execution environment descriptions to perform the respective checks, these should be installed (you will see warnings for missing execution environment descriptions otherwise otherwise), as outline under Execution_Environments#Installing Execution Environment Descriptions.

Install CDO Version Management Tool

In addition to the API Tools, for the GEF bundles (currently not for GEF4 as there all API is yet provisional) we make use of the CDO Version Management Tool to ensure service revision increments are performed as needed (the tool will provide indications of which bundle and feature versions to update when performing changes on the service level). Please install it from the CDO integration update site.

Install Maven Integration (m2e)

In case you want to run a headless build locally in your workspace, you should install the Maven Integration (m2e), as GEF and GEF4 builds are based on Maven/Tycho.

Obtaining Source Code

The complete source code of the GEF project (with the exception of the web-site) is hosted at http://git.eclipse.org:

Check out the code (Committers and Contributors) using EGit

To check out the code within your local workspace, perform the following steps:

  1. Copy the URI of the repository you want to clone (following the links provided above, the URIs are listed under the Clone section). Note that committers will have to use the ssh protocol URI, whereas consumers and contributors are encouraged to use the git protocol URI.
  2. Clone the Git repository
    1. Open the Git Repository Exploring Perspective (provided by EGit) within Eclipse, and from the toolbar of the Git Repositories Browser view select to Clone a Git Repository and add the clone to this view.
    2. If the repository URL was copied to clipboard before, the upcoming Clone Git Repository dialog should already provide the necessary entries for URI, Host, and Repository path, so you may simple forward by pressing Next >.
    3. Select the branches you want to clone from remote. The master branch is the one used for the current development stream. Development in maintenance releases is performed in respective maintenance branches. After having selected all branches of interest, press Next > to continue.
    4. Choose a local directory to store the cloned repository (the default will be located under your home directory) and select the Initial branch to check out.
  3. Checkout the projects
    1. Right-click the Working directory entry, located under the org.eclipse.gef (resp. org.eclipse.gef4) repository within the Git Repositories Browser view and from the context menu select to Import Projects....
    2. In the upcoming Import Projects from Git Repository dialog, select to Import existing projects and press Next >.
    3. Choose the projects you want to import (by default all are selected) and press Finish to conclude.

Setting up the workspace

Set up the Target Platform

A target definition file is provided by the org.eclipse.gef.target (as well as the org.eclipse.gef4.target) project. To specify the target platform, simply open the respective target definition (e.g. MARS.target) within the Target Editor, let is fully resolve (i.e. wait until the Resolving Target Definition background task has finished and the installable units are listed under the respective Locations), then choose to "Set as Target Platform).

In case the target editor does not properly resolve the target definition, an invalid target cache may be the cause. In such cases, opening the target definition file with a text editor and incrementing the sequence number manually, will invalidate the cache when reopening it with the target editor again. After the cache has been invalidated, the sequence number can be restored.

Set up API Tooling

GEF (proper) uses PDE API tooling to guarantee proper handling of version numbering as well as API compatibility, so without definition of an API baseline you will see compile problems after having checked out the code. API-baselines are provided by the org.eclipse.gef.baseline project. You may define them by going to Preferences -> Plug-in Development -> API Baselines, then choose to select "Add Baseline..." and point to the plugins sub-folder of an API baseline located in the baselines project (note that the dialog browses the file system instead of the workspace, so you will have to point into the respective folder in your local Git repository).

Adjust Java and Plug-in Compiler Preferences (Discouraged access errors/warnings caused by provisional API)

As all GEF4 API is currently released as provisional, all GEF4 API package exports are guarded with the x-internal directive (see Marking stable, provisional, and non-API for details). Dependent on your workspace settings, this may lead to a lot of Java compiler warnings/errors, which result from discouraged API access. You may want to adjust your workspace-wide Java and Plug-in compiler preferences to get rid of them.

  • Go to "Preferences -> Java -> Compiler -> Warnings/Errors", then select the respective severity ("Warning", "Ignore") for the "Deprecated and restricted API -> Discouraged reference (access rule)" entry.
  • Go to "Preferences -> Plug-in Development -> Compilers", then select the respective severity ("Warning", "Ignore") for the "References ->References to discouraged classes" entry.

Coding conventions

Marking stable, provisional, and non-API

According to the Eclipse Provisional API Guidelines and the Naming Conventions, the following conventions are followed to differentiate between stable, provisional, and non-API (see also bug #438900):

  • Stable API: All stable API packages do not contain 'internal' in their package names and are exposed via 'Export-Package' in the plug-in MANIFEST.MF, unguarded by 'x-friends' or 'x-internal' directives.
  • Provisional API: All provisional API packages do not contain 'internal' in their package names and are exposed via 'Export-Package' in the plug-in MANIFEST.MF, guarded by an 'x-internal' directive.
  • Non-API: All non-API packages contain 'internal' in their package names , e.g. org.eclipse.gef4.internal.geometry.utils. These packages should only be exposed via 'Expose-Package' in the plug-in MANIFEST.MF, if this is guarded by an 'x-friends' directive.

Please note that for the Mars release, all of the GEF4 API will still be provisional (i.e. all API packages are provisional API packages). This will cause a lot of warnings/errors in your workspace, unless you follow the guidance given Adjust Java and Plug-in Compiler Preferences.

Starting an (Eclipse Application) runtime, resolving JavaFX runtime dependencies

When launching an Eclipse runtime that contains GEF4 bundles with JavaFX dependencies, the e(fx)clipse org.eclipse.fx.javafx bundle org.eclipse.fx.osgi fragment have to be included in the runtime configuration (they are already included in the GEF4 target). Also, -Dosgi.framework.extensions=org.eclipse.fx.osgi has to be added to the VM arguments in the runtime configuration's Arguments tab. If you are having problems with the e(fx)clipse runtime resolution you can add -Defxclipse.osgi.hook.debug=true to the VM arguments to enable debugging output. We noticed that e(fx)clipse does not seem to work correctly when running SWT on GTK 3 on older GTK versions. In this case, you can enforce SWT to use GTK 2 by setting the environment variable SWT_GTK3=0 or adding --launcher.GTK_version 2 to your eclipse.ini.

Running a headless build locally

GEF (as well as GEF4) uses a Maven/Tycho-based build infrastructure. With the Maven Integration installed, the headless build that is executed by the gef-master and gef4-master Hudson build jobs can also be executed in the local workspace. Make sure you have checked out all projects of a respective git repository (GEF and GEF4 are independent). Then easily run the build by right-clicking the pom.xml file located within the org.eclipse.gef.releng or org.eclipse.gef4.releng project respectively, and selecting 'Run As -> Maven build...'.

In the configuration wizard you have to specify the goals ("clean verify") and the profiles ("Mars.target") for the build. Note that without setting the target profile the build will not run successfully.

GEF-ContributorGuide-Build-Locally-Main.png

You should select a Java-8 JVM in the "JRE" tab, to ensure that you run with a configuration comparable to that of the CI-server (hudson.eclipse.org). Otherwise your local build might behave differently compared to the continuous CI build. For example, javadoc errors are will not lead to a build failure when running with Java-7, while the build will fail if using Java-8 (as done in the CI server build jobs).

GEF-ContributorGuide-Build-Locally-JRE.png

As a result of the build, an update-site will be created in the target sub-folder of the org.eclipse.gef.repository respectively org.eclipse.gef4.repository project. Please note that you need to have a JDK installed (and used by Tycho) rather than a JRE, because the Tycho builds rely on the availability of a javadoc executable for the generation of API documentation in the doc bundles.

Creating a Contribution

You can contribute to GEF either by producing a patch, or via GitHub. In either case, your contribution should be related to a corresponding Bugzilla entry (you can search for existing bugs, or file a new one).

We can easily consume your contribution (compare Eclipse Legal Process), if:

  • you have signed the Eclipse Contributor License Agreement (see Eclipse Foundation Contributor License Agreement), and
  • you have stated (in the corresponding Bugzilla entry) that the contribution was developed from scratch, without incorporating content from elsewhere, and that you are authorized to contribute it under the EPL.

If your contribution does not exceed the contribution limit (currently 1000 LOC) this will allow us to simply consume it. If your contribution was not developed from scratch or contains content from other authors, please indicate this on the related Bugzilla entry. As in cases where the contribution exceeds the limit, we will have to open a contribution questionnaire (and may have to ask for additional information via the related Bugzilla) to handle such cases (see Eclipse Legal Process).

Produce a Patch

To contribute a patch, create a branch in your local Git repository for working on your changes, e.g. a fix for bug 321775:

git checkout -b fix-321775

Test, fix, and commit until you're done. Run the Maven build to make sure everything works. Then create a patch including all commits on your branch against master, like this:

git format-patch master --stdout > fix-321775.patch

Finally, attach your patch to the corresponding bug, in this case bug 321775.

Fork via GitHub

To contribute via GitHub, fork the GitHub repository you'd like to contribute to from https://github.com/eclipse (i.e. the GEF or GEF4. Commit, test, and push your contribution to your fork. When you're done, add a link to the Github commit you want to contribute to a comment in the corresponding bugzilla entry, e.g.:

 https://github.com/ujhelyiz/zest/commit/c1a69026477f0852727a2132233e9e61c14b4d8d

For details, see Development_Resources/Handling_Git_Contributions.

Commiting code

Comments

When committing code, the following format should be used:

 '[' ( <bug-id> | 'NONE' ) ']' <one-line-summary-or-single-line-commit-message> (  '(' 'CQ' <cq-number> ')' )?
 
 ( <wrapped-detailed-commit-message> )?

Examples:

 [355997] Add support for calculating bezier curve intersections. (CQ 5976)
 [NONE] Update target definition to Eclipse SDK 4.2.0.I20120222-0915.

Furthermore, the following constraints should be regarded:

  • The bug id of the bug, which is used to track the changes should always be provided, or NONE to indicate that the changes are made without any directly related bug.
  • The commit message should be specified using present tense, declaring why the changes were made.
  • If a commit message is longer than one short line, it should be formatted to have a short, one-line summary, a blank line, and a wrapped longer description (see [1].
  • If the committer is not the contributor of the changes, the Git author field should be used to specify the full name of the contributor (see Development_Resources/Handling_Git_Contributions). In case the changes were approved by means of a contribution questionnaire, the CQ number should be specified in round brackets after the one line summary.

Handling Bugs

When working with bugzillas, the following guidelines should be regarded.

Classifying Bugs

For GEF4, components are pretty fine-grained, so selection of a bugzilla component is usually sufficient to identify the part of the API that is concerned.

For Draw2d/GEF (MVC) 3.x this may not be sufficient. We thus use categories for this issue, which will be stated as a [<category_name>] prefix within the bugzilla's summary. The list of currently used categories is:

  • General
    • [TVT] - Translation Verification Tests
  • Draw2d
    • [GraphLayout]
    • [Geometry]
    • [Text]
  • GEF
    • [Command]
    • [DnD]
    • [EditPart]
    • [EditPolicy]
    • [Palette]
    • [Print]
    • [Tool]

Resolving Policy

When resolving bugzillas, it should be stated how the bug is verified. Preferably this is a JUnit test. Alternatively, the bugzilla will say that the defect can be reproduced in the Logic example and you can demonstrate the fix working in the logic example (or other examples using GEF). If the bug is trivial or obvious and does not require a test, we can just state this in the Bugzilla too.

Back to the top