Jump to: navigation, search

Difference between revisions of "PDE/Contributor Guide"

< PDE
(Update to working with Git and Gerrit, not CVS. Still needs some work on cleaning up/amending .psf mentions and IP.)
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{PDE}}
+
{{PDE}}
 +
 
 +
{{:DocumentationGuidelines/DraftHeader}}  
  
 
== Project Structure  ==
 
== Project Structure  ==
Line 27: Line 29:
 
=== Incubator  ===
 
=== Incubator  ===
  
Incubator components vary in maturity level and are supported by the respective component leads.
+
Incubator components vary in maturity level and are supported by the respective component leads.  
  
 
== Getting Started  ==
 
== Getting Started  ==
Line 33: Line 35:
 
The PDE project places a very high value on community contributions.  
 
The PDE project places a very high value on community contributions.  
  
This document is intended to help those interested contribute to PDE. It communicates our conventions and discusses ways to get your contributions prioritized. There are many ways that you as a member of the community can get involved and contribute to the PDE Project.
+
This document is intended to help those interested contribute to PDE. It communicates our conventions and discusses ways to get your contributions prioritized. There are many ways that you as a member of the community can get involved and contribute to the PDE Project.  
  
 
The first step is to let us know you are out there, check out the different ways we communicate and chat with us about your problems and interests.  
 
The first step is to let us know you are out there, check out the different ways we communicate and chat with us about your problems and interests.  
  
You should also sign up for a [http://bugs.eclipse.org Bugzilla account] and add pde-ui-inbox@eclipse.org to your watch list.
+
You should also sign up for a [http://bugs.eclipse.org Bugzilla account] and add pde-ui-inbox@eclipse.org to your watch list.  
  
=== Individual Contributors  ===
+
<br>
  
TODO
+
=== Creating Bug Reports  ===
  
=== Creating Bug Reports ===
+
If you encounter a bug while working with Eclipse (whether it be with PDE or elsewhere), file a report in bugzilla. However, keep some things in mind:
  
If you encounter a bug while working with Eclipse (whether it be with PDE or elsewhere), file a report in bugzilla. However, keep some things in mind:
+
*Search bugzilla for existing bugs like yours BEFORE you file it. Resolving duplicates is time consuming.
 +
*Try to have reproducible steps. An entry in the log file may not be enough. Some log entries are NOT bugs, and can be caused by incorrect workspace configuration, etc.
 +
*Bugzilla is not a forum. Do not ask questions on bugzilla.
 +
*New feature requests should be marked with a severity of '''enhancement'''. Try to give a realistic severity to bugs, a bug with a straightforward workaround is not '''critical''' or '''blocker'''
 +
*Bugs have a lifecycle you should be aware of:
 +
**NEW - All newly filed bugs start out in the NEW state.
 +
**DUPLICATE/INVALID/WORKSFORME/WONTFIX - If a bug is a duplicate of another bug or if a committer decides that no code changes will be made for the bug, the bug is resolved immediately with an explanation. Unless the bug is REOPENED for some reason, this is the end of the road.
 +
**ASSIGNED - If an individual wants to take ownership of a bug (committer or contributor willing to work on it), the bug is reassigned to them, removing it from the inbox. If there is an expected timeframe for the bug to be fixed in, set the target milestone.
 +
**RESOLVED-FIXED - Bugs are marked as RESOLVED-FIXED once code that solves the issue has been pushed to Git. If a patch was provided by a non-committer it must be marked with the IP Log flag by the committer that pushed the code to Git. Proving a brief explanation of the fix/a list of affected files is recommended.
 +
**VERIFIED - PDE does not explicitly verify bugs. However, if the original reporter or a second committer confirms that a fix does in fact fix the original problem, the bug may be marked as verified.
  
* Search bugzilla for existing bugs like yours BEFORE you file it. Resolving duplicates is time consuming.
+
=== Contributing Fixes  ===
* Try to have reproducible steps. An entry in the log file may not be enough. Some log entries are NOT bugs, and can be caused by incorrect workspace configuration, etc.
+
* Bugzilla is not a forum. Do not ask questions on bugzilla.
+
* New feature requests should be marked with a severity of '''enhancement'''. Try to give a realistic severity to bugs, a bug with a straightforward workaround is not '''critical''' or '''blocker'''
+
* Bugs have a lifecycle you should be aware of:
+
** NEW - All newly filed bugs start out in the NEW state.
+
** DUPLICATE/INVALID/WORKSFORME/WONTFIX - If a bug is a duplicate of another bug or if a committer decides that no code changes will be made for the bug, the bug is resolved immediately with an explanation. Unless the bug is REOPENED for some reason, this is the end of the road.
+
** ASSIGNED - If an individual wants to take ownership of a bug (committer or contributor willing to work on it), the bug is reassigned to them, removing it from the inbox. If there is an expected timeframe for the bug to be fixed in, set the target milestone.
+
** RESOLVED-FIXED - Bugs are marked as RESOLVED-FIXED once code that solves the issue has been checked into CVS. If a patch was provided by a non-committer it must be marked with the IP Log flag by the committer that committed the code to CVs. Proving a brief explanation of the fix/a list of affected files is recommended.
+
** VERIFIED - PDE does not explicitly verify bugs. However, if the original reporter or a second committer confirms that a fix does in fact fix the original problem, the bug may be marked as verified.
+
  
=== Contributing Fixes ===
+
In general we follow the standard Eclipse [http://wiki.eclipse.org/index.php/Development_Conventions_and_Guidelines coding style], some things such as indentation, brackets, imports, etc. are enforced by pde project preferences, so your file will be updated when you save. Try to make your code easily readable adding comments where necessary. Add javadoc (Alt-Shift-J) to public methods and classes, even if they are not API. Once you have created a fix and tested it, you will need it pushed to Git. To do so you must either create a patch and attach it to the bug report, or create a Git commit and push it to Gerrit. A committer will review and commit the fix.
  
In general we follow the standard Eclipse [http://wiki.eclipse.org/index.php/Development_Conventions_and_Guidelines coding style], some things such as indentation, brackets, imports, etc. are enforced by pde project preferences, so your file will be updated when you save.
+
To create a patch, select all of the changed projects in the Package Explorer view. Right click and go to Team &gt; Synchronize, this should open up the Synchronize View. In the Synchronize View, make sure there are no conflicting changes and that all of your changes follow the coding guidelines. Then select your outgoing changes, right click and go to Create Patch... In the dialog, select a destination for the patch (it is best to include the bug number in the file name and use the extension .patch), double check all your changes are included, then hit OK. Attach the created patch to the bug report.  
  
Try to make your code easily readable adding comments where necessary. Add javadoc (Alt-Shift-J) to public methods and classes, even if they are not API.
+
To create a commit and push it to Gerrit, use [http://www.eclipse.org/egit/ EGit] or the Git command line to clone a PDE repository, create a new branch, make your changes and commit them to your local repository. A PDE commit message should look like this:
 +
<pre>Bug 123456: A one-line description of the change
  
Once you have created a fix and tested it, you will need it committed to CVS. To do so you must create a patch and attach it to the bug report. A committer will review and commit the fix.
+
A relatively brief description of the commit. For longer discussions, use the bug report.
  
To create a patch, select all of the changed projects in the Package Explorer view. Right click and go to Team > Synchronize, this should open up the Synchronize View. In the Synchronize View, make sure there are no conflicting changes and that all of your changes follow the coding guidelines. Then select your outgoing changes, right click and go to Create Patch... In the dialog, select a destination for the patch (it is best to include the bug number in the file name and use the extension .patch), double check all your changes are included, then hit OK. Attach the created patch to the bug report.
+
Bug: 123456
 +
Change-Id: I0123456789abcdef0123456789abcdef01234567
 +
Signed-off-by: Committer Name &lt;committer@email.address&gt;
 +
</pre>  
 +
Note that EGit can automatically append Change-Id and Signed-off-by. If others have assisted with a commit, use Also-by. For more information on all the checks and balances, see [http://wiki.eclipse.org/Development_Resources/Handling_Git_Contributions].  
  
We must follow the [http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php Eclipse IP Process]. Small contributions will be reviewed and marked with the IP Log flag. Larger contributions will require additional steps.
+
Configure [http://wiki.eclipse.org/Gerrit Gerrit] to point to the Eclipse Gerrit system, and use 'Push to Gerrit...' to make the push. The review URL will be returned as part of the response.  
  
=== Communication ===
+
We must follow the [http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php Eclipse IP Process]. Small contributions will be reviewed and marked with the IP Log flag. Larger contributions will require additional steps.
  
* There is one [https://dev.eclipse.org/mailman/listinfo/pde-dev mailing list] that is used for developer discussions.
+
=== Communication  ===
* We are active on IRC channels [irc://irc.freenode.net/#eclipse #eclipse] and [irc://irc.freenode.net/#eclipse-dev #eclipse-dev]
+
 
* PDE has a [news://news.eclipse.org/eclipse.platform newsgroup] where users can ask for help
+
*There is one [https://dev.eclipse.org/mailman/listinfo/pde-dev mailing list] that is used for developer discussions.  
 +
*We are active on IRC channels [irc://irc.freenode.net/#eclipse #eclipse] and [irc://irc.freenode.net/#eclipse-dev #eclipse-dev]  
 +
*PDE has a [news://news.eclipse.org/eclipse.platform newsgroup] where users can ask for help
  
 
=== Contributor Links  ===
 
=== Contributor Links  ===
Line 85: Line 94:
 
== Workspace  ==
 
== Workspace  ==
  
The recommended way to work with PDE is by checking them out of CVS. Doing this makes it easy to try the latest changes and work with patches and ensures that you can easily browse the source code and documentation.  
+
The recommended way to work with PDE is by checking them out of Git. Doing this makes it easy to try the latest changes and work with patches and ensures that you can easily browse the source code and documentation.  
  
 
=== Setup  ===
 
=== Setup  ===
  
'''We eat our own dogfood''' so we try to use a recent Eclipse build so that we are testing as we work. Updating to the most recent i-build each week is preferred. You can use update sites to update your current build or download a [http://download.eclipse.org/eclipse/downloads/ recent build].
+
'''We eat our own dogfood''' so we try to use a recent Eclipse build so that we are testing as we work. Updating to the most recent i-build each week is preferred. You can use update sites to update your current build or download a [http://download.eclipse.org/eclipse/downloads/ recent build].  
  
Consider installing and using [http://www.eclipse.org/mylyn Mylyn]. It can make it easier to switch between tasks. It connects well with Eclipse, PDE and bugzilla.
+
Consider installing and using [http://www.eclipse.org/mylyn Mylyn]. It can make it easier to switch between tasks. It connects well with Eclipse, PDE and bugzilla.  
  
Eclipse code is written, edited and tested within Eclipse. This is called self-hosting. Here are the basic steps to self host:
+
Eclipse code is written, edited and tested within Eclipse. This is called self-hosting. Here are the basic steps to self host:  
  
# Setup the CVS repository: Go to the CVS Repository Exploring Perspective. In the CVS Repositories view you can add the repo by pasting the following (or creating a new connection and filling in the fields in the wizard).
+
#Setup the Git repositories: Go to the Git Repository Exploring Perspective. In the Git Repositories view, add a repository by pasting one of the following repository URIs (or clicking 'Clone a Git repository and add it to this view'):
<pre>:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse</pre>
+
<pre>git://git.eclipse.org/gitroot/pde/eclipse.pde.git
#Look in HEAD for the 'pde' folder. Inside that folder is a project called 'org.eclipse.pde.releng'. Right click and go to Check Out to copy the project to your workspace.
+
git://git.eclipse.org/gitroot/pde/eclipse.pde.ui.git
# Switch back to the Java perspective, inside the releng project there are a number of .psf files. These project set files can be used to quickly check out the projects you are interested in working on. The pde-ui-basic.psf is where most contributors should start. Simply right click on the file and go to import team project set. A dialog may pop up requiring you to choose a repository to use, as committers must use different settings then contributors.
+
git://git.eclipse.org/gitroot/pde/eclipse.pde.build.git</pre>
# You can now edit the code in your workspace. To test your code you must create an Eclipse Launch Configuration. The easiest way to do so is to right click on your project, go to Debug As (or Run As) > Run-time Workbench. Your initial Eclipse instance that you edited your code in is called the '''host'''. The Eclipse you just launched is called the '''target'''. Any changes you make in your host will be reflected in the target.
+
Alternatively, you can use the Github mirrors:
 +
<pre>https://github.com/eclipse/eclipse.pde.git
 +
https://github.com/eclipse/eclipse.pde.ui.git
 +
https://github.com/eclipse/eclipse.pde.build.git</pre>
 +
#Select the '''master''' branch from the repository, or another if required. This branch follows the latest development on as-yet-unreleased PDE.
 +
#Look in HEAD for the 'pde' folder. Inside that folder is a project called 'org.eclipse.pde.releng'. Right click and go to Check Out to copy the project to your workspace.  
 +
#Switch back to the Java perspective, inside the releng project there are a number of .psf files. These project set files can be used to quickly check out the projects you are interested in working on. The pde-ui-basic.psf is where most contributors should start. Simply right click on the file and go to import team project set. A dialog may pop up requiring you to choose a repository to use, as committers must use different settings then contributors.  
 +
#You can now edit the code in your workspace. To test your code you must create an Eclipse Launch Configuration. The easiest way to do so is to right click on your project, go to Debug As (or Run As) &gt; Run-time Workbench. Your initial Eclipse instance that you edited your code in is called the '''host'''. The Eclipse you just launched is called the '''target'''. Any changes you make in your host will be reflected in the target.
  
 
=== Tests  ===
 
=== Tests  ===
  
TODO
+
TODO  
 +
 
 +
[[Category:Draft_Documentation]]

Latest revision as of 11:40, 18 September 2013

PDE
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse SourceProject Set File
Warning2.png
Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.


Project Structure

The PDE project is structured into four major components: api tools, build, ui and incubator.

API Tools

API tooling will assist developers in API maintenance by reporting API defects such as binary incompatibilities, incorrect plug-in version numbers, missing or incorrect @since tags, and usage of non-API code between plug-ins. The tooling will be integrated in the Eclipse SDK and will be used in the automated build process. Specifically, the tooling is designed to do the following:

  • Identify binary compatibility issues between two versions of a software component or product.
  • Update version numbers for plug-ins (bundles) based on the Eclipse versioning scheme.
  • Update @since tags for newly added classes, interfaces, methods, etc.
  • Provide new javadoc tags and code assist to annotate types with special restrictions.
  • Leverage existing information (in MANIFEST.MF) to define the visibility of packages between bundles.
  • Identify usage of non-API code between plug-ins.
  • Identity leakage of non-API types into API.

Build

Ant based tools and scripts to automate build processes

UI

Models, builders, editors and more to faciliate bundle development

Incubator

Incubator components vary in maturity level and are supported by the respective component leads.

Getting Started

The PDE project places a very high value on community contributions.

This document is intended to help those interested contribute to PDE. It communicates our conventions and discusses ways to get your contributions prioritized. There are many ways that you as a member of the community can get involved and contribute to the PDE Project.

The first step is to let us know you are out there, check out the different ways we communicate and chat with us about your problems and interests.

You should also sign up for a Bugzilla account and add pde-ui-inbox@eclipse.org to your watch list.


Creating Bug Reports

If you encounter a bug while working with Eclipse (whether it be with PDE or elsewhere), file a report in bugzilla. However, keep some things in mind:

  • Search bugzilla for existing bugs like yours BEFORE you file it. Resolving duplicates is time consuming.
  • Try to have reproducible steps. An entry in the log file may not be enough. Some log entries are NOT bugs, and can be caused by incorrect workspace configuration, etc.
  • Bugzilla is not a forum. Do not ask questions on bugzilla.
  • New feature requests should be marked with a severity of enhancement. Try to give a realistic severity to bugs, a bug with a straightforward workaround is not critical or blocker
  • Bugs have a lifecycle you should be aware of:
    • NEW - All newly filed bugs start out in the NEW state.
    • DUPLICATE/INVALID/WORKSFORME/WONTFIX - If a bug is a duplicate of another bug or if a committer decides that no code changes will be made for the bug, the bug is resolved immediately with an explanation. Unless the bug is REOPENED for some reason, this is the end of the road.
    • ASSIGNED - If an individual wants to take ownership of a bug (committer or contributor willing to work on it), the bug is reassigned to them, removing it from the inbox. If there is an expected timeframe for the bug to be fixed in, set the target milestone.
    • RESOLVED-FIXED - Bugs are marked as RESOLVED-FIXED once code that solves the issue has been pushed to Git. If a patch was provided by a non-committer it must be marked with the IP Log flag by the committer that pushed the code to Git. Proving a brief explanation of the fix/a list of affected files is recommended.
    • VERIFIED - PDE does not explicitly verify bugs. However, if the original reporter or a second committer confirms that a fix does in fact fix the original problem, the bug may be marked as verified.

Contributing Fixes

In general we follow the standard Eclipse coding style, some things such as indentation, brackets, imports, etc. are enforced by pde project preferences, so your file will be updated when you save. Try to make your code easily readable adding comments where necessary. Add javadoc (Alt-Shift-J) to public methods and classes, even if they are not API. Once you have created a fix and tested it, you will need it pushed to Git. To do so you must either create a patch and attach it to the bug report, or create a Git commit and push it to Gerrit. A committer will review and commit the fix.

To create a patch, select all of the changed projects in the Package Explorer view. Right click and go to Team > Synchronize, this should open up the Synchronize View. In the Synchronize View, make sure there are no conflicting changes and that all of your changes follow the coding guidelines. Then select your outgoing changes, right click and go to Create Patch... In the dialog, select a destination for the patch (it is best to include the bug number in the file name and use the extension .patch), double check all your changes are included, then hit OK. Attach the created patch to the bug report.

To create a commit and push it to Gerrit, use EGit or the Git command line to clone a PDE repository, create a new branch, make your changes and commit them to your local repository. A PDE commit message should look like this:

Bug 123456: A one-line description of the change

A relatively brief description of the commit. For longer discussions, use the bug report.

Bug: 123456
Change-Id: I0123456789abcdef0123456789abcdef01234567
Signed-off-by: Committer Name <committer@email.address>

Note that EGit can automatically append Change-Id and Signed-off-by. If others have assisted with a commit, use Also-by. For more information on all the checks and balances, see [1].

Configure Gerrit to point to the Eclipse Gerrit system, and use 'Push to Gerrit...' to make the push. The review URL will be returned as part of the response.

We must follow the Eclipse IP Process. Small contributions will be reviewed and marked with the IP Log flag. Larger contributions will require additional steps.

Communication

Contributor Links

Workspace

The recommended way to work with PDE is by checking them out of Git. Doing this makes it easy to try the latest changes and work with patches and ensures that you can easily browse the source code and documentation.

Setup

We eat our own dogfood so we try to use a recent Eclipse build so that we are testing as we work. Updating to the most recent i-build each week is preferred. You can use update sites to update your current build or download a recent build.

Consider installing and using Mylyn. It can make it easier to switch between tasks. It connects well with Eclipse, PDE and bugzilla.

Eclipse code is written, edited and tested within Eclipse. This is called self-hosting. Here are the basic steps to self host:

  1. Setup the Git repositories: Go to the Git Repository Exploring Perspective. In the Git Repositories view, add a repository by pasting one of the following repository URIs (or clicking 'Clone a Git repository and add it to this view'):
git://git.eclipse.org/gitroot/pde/eclipse.pde.git
git://git.eclipse.org/gitroot/pde/eclipse.pde.ui.git
git://git.eclipse.org/gitroot/pde/eclipse.pde.build.git

Alternatively, you can use the Github mirrors:

https://github.com/eclipse/eclipse.pde.git
https://github.com/eclipse/eclipse.pde.ui.git
https://github.com/eclipse/eclipse.pde.build.git
  1. Select the master branch from the repository, or another if required. This branch follows the latest development on as-yet-unreleased PDE.
  2. Look in HEAD for the 'pde' folder. Inside that folder is a project called 'org.eclipse.pde.releng'. Right click and go to Check Out to copy the project to your workspace.
  3. Switch back to the Java perspective, inside the releng project there are a number of .psf files. These project set files can be used to quickly check out the projects you are interested in working on. The pde-ui-basic.psf is where most contributors should start. Simply right click on the file and go to import team project set. A dialog may pop up requiring you to choose a repository to use, as committers must use different settings then contributors.
  4. You can now edit the code in your workspace. To test your code you must create an Eclipse Launch Configuration. The easiest way to do so is to right click on your project, go to Debug As (or Run As) > Run-time Workbench. Your initial Eclipse instance that you edited your code in is called the host. The Eclipse you just launched is called the target. Any changes you make in your host will be reflected in the target.

Tests

TODO