Difference between revisions of "GEF/Contributor Guide"
(Extract adopter guide parts.)
|Line 1:||Line 1:|
This provides all necessary information to enable contributorscommitters(see [https://www.eclipse.org/projects/dev_process/#2_3_Three_Communities ]) to contribute to GEF. Adopters, who want to develop against GEF, should rather consult the [[GEF/Adopter Guide|GEF Adopter Guide]].
== Preparing your development environment ==
== Preparing your development environment ==
Revision as of 02:47, 20 October 2015
This GEF Contributor Guide provides all necessary information to enable contributors/committers (see definitions of three different communities) to contribute to GEF. Adopters, who want to develop against GEF, should rather consult the GEF Adopter Guide.
- 1 Preparing your development environment
- 1.1 Install Java 7 and Java 8 JDK
- 1.2 Download and Start Eclipse IDE
- 1.3 Install required development tools into Eclipse IDE
- 1.4 Check out the code (Committers and Contributors) using EGit
- 1.5 Specify Execution Environment for JavaSE-1.7
- 1.6 Set Target Platform
- 1.7 Define API Baseline
- 1.8 Adjust Java and Plug-in Compiler Preferences (Discouraged access errors/warnings caused by provisional API)
- 1.9 Generate Xtext Artifacts
- 2 Starting an (Eclipse Application) runtime, resolving JavaFX runtime dependencies
- 3 Running a headless build locally
- 4 Creating a Contribution
- 5 Commiting code
- 6 Coding conventions
- 7 Bugzilla conventions
Preparing your development environment
Install Java 7 and Java 8 JDK
If you want to contribute to GEF 3.x, any current Java JDK may be used (the GEF 3.x code base is backwards compatible to J2SE-1.4). If you want to develop against GEF4, you will need to have a Java 7 JDK including JavaFX 2.2 (Oracle JVM > 1.7.0_45) and a Java 8 JDK installed. The GEF4 code base is compatible to JavaSE-1.7, but the required e(fx)clipse PDE integration requires a Java 8 JDK to work properly.
Download and Start Eclipse IDE
In order to contribute to GEF 3.x or GEF4 we recommend to download an 'Eclipse IDE for Eclipse Committers' from Mars and to prepare it as outlined in the following sections.
If you want to contribute to GEF4, the e(fx)clipse JavaFX-PDE-integration tooling that is needed to resolve JavaFX dependencies (see Install e(fx)clipse JavaFX-PDE-integration), requires that you start your eclipse IDE with a Java 8 JVM. If Java 8 is not your system default, follow the instructions given in Specifying the JVM to specify that a Java 8 JVM is used for starting your IDE. Please note that the Java JVM that is used for starting the IDE is unrelated to your actual development target, which might still refer to BREE JavaSE-1.7 and JavaFX 2.2. It is only needed for the e(fx)clipse JavaFX-PDE-integration tooling to work properly.
Install required development tools into Eclipse IDE
In order to contribute to GEF 3.x and GEF4, you should install the development tools listed in the following sections. If you have started with an Eclipse IDE for Eclipse Committers, as described in Download and Start Eclipse IDE, as an alternative to a manual installation (which is described in the following subsections), you can download a .p2f file matching your respective development environment (i.e. Mars.p2f for a Mars Eclipse IDE) and install it via File -> Import... -> Install Software Items from File.
Install e(fx)clipse JavaFX-PDE-integration
When developing those GEF4 components that are dependent on JavaFX, it is required 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. This is needed because JavaFX is not included on any of the default OSGi classpaths, so JavaFX dependencies of the GEF4 bundles will otherwise not be properly resolved (unless you manually add the respective jars to your classpath, which is not recommended). The e(fx)clipse JavaFX-PDE-integration will automatically add additional classpath entries for those bundles that contain classes with javafx.* 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).
Please install e(fx)clipse - IDE - PDE (
org.eclipse.fx.ide.pde.feature.feature.group) in a version matching your development environment. For Mars, it can be installed in version 2.0.0 from http://download.eclipse.org/releases/mars (uncategorized) or the e(fx)clipse 2.0.0 release site (e(fx)clipse - single components category).
Please note that from Mars M7 onwards (or more precisely beginning with gef4-master build #2316, 2015-04-25), development against GEF4 will require e(fx)clipse in at least version 2.0.0 and will not work with earlier versions of e(fx)clipse. This is because GEF4 bundles no longer specify javafx.* package imports, and JavaFX dependencies will thus not be resolved with earlier e(fx)clipse versions. Please note that e(fx)clipse 2.0.0 can also be used in a Luna development environment.
Install Xtext Complete SDK
Parts of the GEF4 DOT code base ('org.eclipse.gef4.dot', 'org.eclipse.gef4.dot.ui') contain sources that are generated by Xtext. These generated sources are not contained in the Git repository and have to be generated locally within the development workspace, either by manually triggering the Xtext artifact generation (see Generate Xtext Artifacts), which requires installation of Xtext Complete SDK into your IDE, or by executing a local Maven build (see Running a headless build locally).
If you want to develop GEF4 DOT, it is recommended that you install the 'Xtext Complete SDK' into your IDE. Please make sure that you install it in a version matching the desired development target (see org.eclipse.gef4.target). That is, for a Mars target, it should be installed in version 2.8.3 from http://download.eclipse.org/releases/mars.
Install API Tools Execution Environment Descriptions
All production code GEF 3.x 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 all GEF4 API is still provisional, this is the only aspect it is used for in GEF4). As API tooling requires execution environment descriptions (see Execution_Environments#Installing Execution Environment Descriptions for details) to perform the respective checks, these need to be made available, as you will see warnings for missing execution environment descriptions otherwise otherwise. Please install API Tools Execution Environment Descriptions in a version matching your development environment. For Mars, they can be installed in version 1.0.1 from http://download.eclipse.org/releases/mars (General Purpose Tools category).
Install Oomph Version Management Tool
In addition to the API Tools, for the GEF 3.x and GEF4 bundles we make use of the Oomph 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 Oomph Version Management in a version matching your development environment. For Mars, it can be installed in version 1.1.0 from http://download.eclipse.org/releases/mars (General Purpose Tools category).
Install Maven Integration (m2e)
In case you want to run a headless build locally in your workspace, the Maven Integration (m2e) is needed, as GEF 3.x and GEF4 builds are based on Maven/Tycho. Please install m2e - Maven Integration for Eclipse (includes Incubating components) in a version matching your development environment. For Mars, it can be installed in version 1.6.0 from http://download.eclipse.org/releases/mars (General Purpose Tools category).
Check out the code (Committers and Contributors) using EGit
The complete source code of the GEF project (with the exception of the web-site) is hosted at http://git.eclipse.org:
- The GEF 3.x code base (Draw2d and GEF (MVC) 3.x as well as Zest 1.x ) can be found in the GEF Git repository
- The GEF4 provisional code base can be found in the GEF4 Git repository.
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.
Specify Execution Environment for JavaSE-1.7
Several GEF4 bundles rely on JavaFX, which is not visible on the OSGi classpath by default (in case of Java 7 this holds for all classes of JavaFX 2.2, in case of Java 8 this holds for the SWT-integration of JavaFX 8). Within your IDE, the e(fx)clipse JavaFX-PDE integration tooling is needed to extend the bundle classpath accordingly (see Install e(fx)clipse JavaFX-PDE-integration for details). In order to have the JavaFX dependencies of bundles with BREE JavaSE-1.7 (JavaFX 2.2) resolve properly by the e(fx)clipse JavaFX-PDE-integration, the Java execution environment for JavaSE-1.7 has to be properly resolved against matching Java JVM. Note that it is required to properly resolve JavaSE-1.7 to a matching Java 7 JVM even if you want to use a Java 8 JVM for launching a runtime or for later deployment.
As all GEF4 bundles with JavaFX dependencies are compatible to JavaFX 2.2 (or higher) and thus specify a JavaSE-1.7 BREE (bundle required execution environment), you will thus have to ensure that a Java 7 JVM, which provides JavaFX 2.2 (e.g. an Oracle JVM), is used to resolve the JavaSE-1.7 execution environment in your IDE. The e(fx)clipse JavaFX-PDE integration will only be able to resolve all JavaFX dependencies (of a bundle with JavaSE-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, against which the JavaSE-1.7 execution environment is resolved. 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 JavaSE-1.7 BREE) by the e(fx)clipse JavaFX-PDE-integration automatically. To ensure that the respective JVM is used to resolve the JavaSE-1.7 execution environment, go to "Windows -> Preferences -> Java -> Installed JREs -> Execution Environments" and select it there.
Set 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.
Define API Baseline
All production code GEF 3.x and GEF4 bundles (i.e. excluding doc and test bundles) are configured to have PDE API tooling enabled. It is used to ensure compliance of sources to the specified execution environments, as well as for proper handling of version numbering due to API changes (not in case of GEF4, where all API is still provisional). As PDE API tooling requires the definition of an API baseline you will see errors after having checked out the code ('An API baseline has not been set for the current workspace.').
For GEF 3.x, 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).
For GEF4, there are no API baselines defined yet, because all API is still provisional (and PDE API tooling does not consider provisional API). You will nevertheless see above mentioned errors after having checked out the code. They can be removed by going to Preferences -> Plug-in Development -> API Baselines and choosing Warning or Ignore as severity for the Missing API baseline option.
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.
Generate Xtext Artifacts
Parts of the GEF4 DOT code base (
org.eclipse.gef4.dot.ui) contain sources that are generated by Xtext. These generated sources are not contained in the Git repository and have to be generated locally within the development workspace.
If you have installed Xtext in your IDE (see Install Xtext), you can manually trigger the Xtext artifact generation by selecting
org.eclipse.gef4.internal.dot.parser package in the Package Explorer, and by choosing Run As -> Generate Xtext Artifacts from the context menu.
Alternatively you may execute a local Maven build (see Running a headless build locally). Make sure to refresh the org.eclipse.gef4.dot and org.eclipse.gef4.dot.ui projects in your workspace after having executed the local build (Refresh from context menu on respective projects, or F5), and make sure to clean your workspace afterwards (Project -> Clean -> Clean all projects).
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.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. 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.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.
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).
As a result of the build, an update-site will be created in the
target sub-folder of the
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 Contributing a Patch), 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 complies to the Eclipse Foundation Certificate of Origin (see Eclipse Foundation Certificate of Origin) and/or you have properly signed-off your GitHub Git commit.
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.:
For details, see Development_Resources/Handling_Git_Contributions.
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> )?
 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 .
- 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.
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.
When working with bugzillas, the following guidelines should be regarded.
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:
- [TVT] - Translation Verification Tests
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.