Skip to main content
Jump to: navigation, search

Difference between revisions of "GEF/Contributor Guide"

< GEF
(Install e(fx)clipse: Fix typo)
 
(91 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Prepare your IDE ==
+
The [[GEF/Contributor Guide| GEF Contributor Guide]] has been migrated to [https://github.com/eclipse/gef/blob/master/CONTRIBUTING.md GEF@github.com] and [https://github.com/eclipse/gef-legacy/blob/master/CONTRIBUTING.md GEF-Legacy@github.com].
 
+
=== Install e(fx)clipse ===
+
When developing against GEF4 components that are dependent on JavaFX, e(fx)clipse should be installed. While only the OSGi integration is actually needed, it may come handy to install the overall e(fx)clipse IDE feature, either 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 and Java 7) or [http://download.eclipse.org/efxclipse/updates-nightly/site http://download.eclipse.org/efxclipse/updates-nightly/site] (for Luna and Java 8).
+
 
+
When launching a runtime workbench, add <code>-Dosgi.framework.extensions=org.eclipse.fx.osgi</code> to the ''VM arguments'' in the ''Arguments'' tab.
+
 
+
=== 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 | 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].
+
 
+
=== 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. ''JUNO_4_2.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'').
+
 
+
===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 Compiler Preferences (Discouraged access errors/warnings caused by provisional API)===
+
As all GEF4 API is released as being '''provisional''', all GEF4 API packages are released with the ''x-internal'' directive (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=438900 bug #438900] 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 compiler preferences to get rid of them. To do so, 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.
+
 
+
== 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 install'. 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.
+
 
+
== 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]).
+
 
+
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.
+
 
+
=== 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.
+
  
 
[[Category:GEF]]
 
[[Category:GEF]]

Latest revision as of 12:16, 13 August 2016

The GEF Contributor Guide has been migrated to GEF@github.com and GEF-Legacy@github.com.

Back to the top