Difference between revisions of "GEF/Contributor Guide"

From Eclipsepedia

< GEF
Jump to: navigation, search
(Running a headless build locally)
Line 1: Line 1:
 
==Development Environment (Committers and Contributors)==
 
==Development Environment (Committers and Contributors)==
  
===Java Version===
+
==Checking out the code (Committers and Contributors)==
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]).
+
 
 +
The GEF source code (i.e. Draw3d and GEF (MVC) 3.x as well as Zest 1.x) is located in the [http://git.eclipse.org/c/gef/org.eclipse.gef.git/ GEF Git repository]. TODO: document how to clone the repository using Git/EGit here. Further describe master, maintenance branch structure. you may check out all plug-ins located in the root folder.
 +
 
 +
The source code of the GEF4 and Zest2 provisional components is located in their respective own Git repositories ([http://git.eclipse.org/c/gef/org.eclipse.gef4.git/ GEF4] and [http://git.eclipse.org/c/gef/org.eclipse.zest.git/ Zest2]).
 +
 
 +
== Setting up the workspace ==
  
 
===Eclipse Target Platform===
 
===Eclipse Target Platform===
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.
+
Target definition files are provided by the <code>org.eclipse.gef.target</code> project, which includes a respective Eclipse SDK.
  
 
===API Tooling ===
 
===API Tooling ===
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.
+
GEF 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).
  
 
===Code Style (Formatting)===
 
===Code Style (Formatting)===
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]).
+
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.
 
+
==Checking out the code (Committers and Contributors)==
+
 
+
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.
+
 
+
===Using Team Project Set File (PSF)===
+
* 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.
+
* 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".
+
* Select the Team Project Set (psf) file you saved on your disk.
+
* 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.
+
  
 
== Running a headless build locally ==
 
== Running a headless build locally ==
  
 
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'. 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> project.
 
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'. 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> project.
 +
 +
== Producing a patch ==
 +
TODO
  
 
==Committing code (Committers Only)==
 
==Committing code (Committers Only)==

Revision as of 18:17, 16 February 2012

Contents

Development Environment (Committers and Contributors)

Checking out the code (Committers and Contributors)

The GEF source code (i.e. Draw3d and GEF (MVC) 3.x as well as Zest 1.x) is located in the GEF Git repository. TODO: document how to clone the repository using Git/EGit here. Further describe master, maintenance branch structure. you may check out all plug-ins located in the root folder.

The source code of the GEF4 and Zest2 provisional components is located in their respective own Git repositories (GEF4 and Zest2).

Setting up the workspace

Eclipse Target Platform

Target definition files are provided by the org.eclipse.gef.target project, which includes a respective Eclipse SDK.

API Tooling

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

Code Style (Formatting)

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.

Running a headless build locally

Beginning with GEF 3.8.0M5, GEF has adopted a Maven/Tycho-based build infrastructure (see bug #363394 for details). With the Maven Integration installed, the headless build that is executed by a 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 pom.xml file located within the org.eclipse.gef.releng project, and selecting 'Run As -> Maven install'. As a result of the build, an update-site will be created in the target sub-folder of the org.eclipse.gef.repository project.

Producing a patch

TODO

Committing code (Committers Only)

CVS Comments

The GEF development team uses the following format for commit comments:

Format: [<bug-id>] <affected-branch> <contributor> <commit-date> <bug-summary>

Example: [213359] gef-head crevells 071221 Make GEF's snapping and tools extensible to allow moving shapes with arrow keys

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.

Bug Handling Policy

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

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.

Categorization Policy

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
    • [TVT] - Translation Verification Tests
  • Draw2d
    • [GraphLayout]
    • [Geometry]
    • [Text]
  • GEF
    • [Command]
    • [DnD]
    • [EditPart]
    • [EditPolicy]
    • [Palette]
    • [Print]
    • [Tool]