Jump to: navigation, search

Difference between revisions of "GEF/Contributor Guide"

< GEF
(Categorization Policy)
(28 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Development Environment (Committers and Contributors)==
+
==Obtaining Source Code ==
  
===Java Version===
+
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]:
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]).
+
  
===Eclipse Target Platform===
+
* 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]
A given version of GEF requires the exact same version of the Eclipse Platform SDK as target. For example, GEF 3.6.0M6 is built against Eclipse Platform SDK 3.6.0M6. The GEF EDiagram example furthermore relies on a compatible EMF version.
+
* 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].  
  
===API Tooling ===
+
=== Check out the code (Committers and Contributors) using EGit===
The GEF development team uses the preceding Eclipse Platform SDK and GEF SDK release version as an API baseline to maintain API compatibility, i.e. for the 3.6 development, the API baseline is formed by Eclipse Platform SDK 3.5.2 and GEF ALL 3.5.2. Checks for API breakages and evolutions are set per project and committed alongside them.
+
  
===Code Style (Formatting)===
+
To check out the code within your local workspace, perform the following steps:
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]).
+
# 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.
  
==Checking out the code (Committers and Contributors)==
+
== Setting up the workspace ==
  
===Using Team Project Set File (PSF)===
+
===Set up the Target Platform===
* Download the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.gef/org.eclipse.gef.releng/psf/gef.psf?root=Tools_Project&view=markup Team Project Set (.psf) file] and save it on your computer.
+
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'').
* 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.
+
  
==Committing code (Committers Only)==
+
===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).
  
===CVS Comments===
+
== Running a headless build locally ==
The GEF development team uses the following format for commit comments:
+
  
Format: ''[<bug-id>] <affected-branch> <contributor> <commit-date> <bug-summary>''
+
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 a [https://hudson.eclipse.org/hudson/job/gef-master/ 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.
  
Example: ''[213359] gef-head crevells 071221 Make GEF's snapping and tools extensible to allow moving shapes with arrow keys''
+
== Creating a Contribution  ==
  
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.
+
You can contribute to GEF either by producing a patch, or via GitHub. In both cases, please include a note in the 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]) stating that you developed your contribution yourself from scratch, without referencing any third-party libraries, and that you are authorized to contribute it under the EPL. Please indicate if that is not the case, so we can initiate the required process for these cases (multiple contributors, third-party libraries, larger contributions that exceed 250 lines).
  
== Bug Handling Policy ==
+
===Produce a Patch===
When working with bugzillas, the following guidelines should be regarded.
+
  
=== Resolving Policy ===
+
To contribute a patch, create a branch in your local Git repository for working on your changes, e.g. a fix for {{bug|321775}}:
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.
+
 
 +
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 of Bugs ==
 +
When working with bugzillas, the following guidelines should be regarded.
  
=== Categorization Policy ===
+
=== 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:
 
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:
  
Line 59: Line 99:
 
** [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 14:04, 17 December 2012

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

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

Creating a Contribution

You can contribute to GEF either by producing a patch, or via GitHub. In both cases, please include a note in the corresponding Bugzilla entry (you can search for existing bugs, or file a new one) stating that you developed your contribution yourself from scratch, without referencing any third-party libraries, and that you are authorized to contribute it under the EPL. Please indicate if that is not the case, so we can initiate the required process for these cases (multiple contributors, third-party libraries, larger contributions that exceed 250 lines).

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