Jump to: navigation, search

Difference between revisions of "GEF/Contributor Guide"

< GEF
(Checking out the code (Committers and Contributors))
Line 8: Line 8:
 
''PLEASE NOTE: Up to now, the code base of the Zest2 provisional component is not hosted within the [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/ GEF4 Git repository], but in its own [http://git.eclipse.org/c/gef/org.eclipse.zest.git/ Zest Git repository]. It is planned to migrate the code base into the GEF4 Git repository after the Juno release, when the two provisional components are unified (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=372365 Bug #372365] for details).''
 
''PLEASE NOTE: Up to now, the code base of the Zest2 provisional component is not hosted within the [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/ GEF4 Git repository], but in its own [http://git.eclipse.org/c/gef/org.eclipse.zest.git/ Zest Git repository]. It is planned to migrate the code base into the GEF4 Git repository after the Juno release, when the two provisional components are unified (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=372365 Bug #372365] for details).''
  
=== Checking out the code (Committers and Contributors)===
+
=== Checking out the code (Committers and Contributors) using EGit===
  
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.
+
# Copy the URI of the Git repository you want to clone (incl. the protocol), which is:
 +
#*GEF: <code>git://git.eclipse.org/gitroot/gef/org.eclipse.gef.git</code> (for contributors) or <code>ssh://git.eclipse.org/gitroot/gef/org.eclipse.gef.git</code> (for committers)
 +
#*GEF4: <code>git://git.eclipse.org/gitroot/gef/org.eclipse.gef4.git</code> or <code>ssh://git.eclipse.org/gitroot/gef/org.eclipse.gef4.git</code> (up to the unification of GEF4 and Zest2, the Zest 2.x code base will be obtainable via <code>git://git.eclipse.org/gitroot/gef/org.eclipse.zest.git</code> or <code>ssh://git.eclipse.org/gitroot/gef/org.eclipse.zest.git</code>)
 +
# 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 ==
 
== Setting up the workspace ==

Revision as of 13:51, 5 March 2012

Obtaining GEF Source Code

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

PLEASE NOTE: Up to now, the code base of the Zest2 provisional component is not hosted within the GEF4 Git repository, but in its own Zest Git repository. It is planned to migrate the code base into the GEF4 Git repository after the Juno release, when the two provisional components are unified (see Bug #372365 for details).

Checking out the code (Committers and Contributors) using EGit

  1. Copy the URI of the Git repository you want to clone (incl. the protocol), which is:
  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

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)

Comments

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

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

Example: [213359] master 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), 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.

Handling of Bugs

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

Classifying Bugs

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]

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.