Difference between revisions of "Platform UI/How to Contribute"

From Eclipsepedia

Jump to: navigation, search
(New page: This page is a starting point for where to begin when wanting to contribute to the project. The goal is educate and to be as up front as possible with expectations so that the process can...)
 
m (Getting the code into your workspace)
(32 intermediate revisions by 9 users not shown)
Line 1: Line 1:
This page is a starting point for where to begin when wanting to contribute to the project.  The goal is educate and to be as up front as possible with expectations so that the process can be as efficient as possible.
+
This page is a starting point for where to begin when wanting to contribute to the project.  The goal is to educate and to be as up front as possible with expectations so that the process can be as efficient as possible.
 
{{Platform UI}}
 
{{Platform UI}}
 
== Bugs==
 
== Bugs==
If you find a bug log it.  See the FAQ entry [[../FAQ#How_do_I_report_a_bug.3F|"How to Report a Bug"]], and a description of how a [http://borisoneclipse.blogspot.com/2005/10/great-bug-report.html|great bug report] looks like.  If you find a bug that you think is a duplicate, is not a bug, etc. feel free to comment saying so.   
+
If you find a bug, log it.  See the FAQ entry [[../FAQ#How_do_I_report_a_bug.3F|"How to Report a Bug"]], and a description of how a [http://borisoneclipse.blogspot.com/2005/10/great-bug-report.html great bug report] looks like.  If you find a bug that you think is a duplicate, is not a bug, etc. feel free to comment saying so.   
  
 
If wanting to track bug changes in Platform UI there are a few ways:
 
If wanting to track bug changes in Platform UI there are a few ways:
* Via email.  If you want to receive email when a bug is logged you can watch the "Platform-UI-Inbox@eclipse.org" user.  You will receive email anytime a new bug if logged to this user or an update is made while assigned to this user.  To set this up see Preferences -> Email Preferences -> User Watching.  This will email you for all incoming Platform UI bugs; you can employ the same technique for watching incoming IDE bugs, the Bugzilla user for that is called "Platform-IDE-Inbox@eclipse.org".  Depending upon your needs this might and might not be what you're looking for.
+
* Via email.  If you want to receive email when a bug is logged you can watch the '''Platform-UI-Inbox@eclipse.org''' user.  You will receive email anytime a new bug is logged to this user or an update is made while assigned to this user.  To set this up see Preferences -> Email Preferences -> User Watching.  This will email you for all incoming Platform UI bugs; to follow all changes for Platform UI and IDE for bugs that an individual has not yet taken, watch '''platform-ui-triaged@eclipse.org''' as well.
 
* Via Atom.  You can convert any query in bugzilla to a feed that will update when a matched bug changes.  To convert a search to a feed perform a search and select "Feed" at the bottom of the search results.
 
* Via Atom.  You can convert any query in bugzilla to a feed that will update when a matched bug changes.  To convert a search to a feed perform a search and select "Feed" at the bottom of the search results.
  
Line 11: Line 11:
 
Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature for Platform UI you'll need to know a few things before you contribute code.
 
Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature for Platform UI you'll need to know a few things before you contribute code.
  
=== Checking out the Plug-ins===
+
Platform UI has switched to git as its SCM. For the old CVS instructions, check out [[Platform UI/How to Contribute/CVS]].
There are three kinds of plug-ins, the actual code, test plug-ins, and example plug-ins. Using the CVS Repository at :pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse, they are listed under HEAD/platform-ui, HEAD/platform-ui-examples, and HEAD/platform-ui-tests.
+
  
We recommend using a recent integration build from the [http://download.eclipse.org/eclipse/downloads/|Eclipse Project download page].
+
=== Getting the code into your workspace ===
  
To check out everything from within Eclipse, do the following:
+
See [[Platform-releng/Git_Workflows#Gerrit_workflow_for_a_committer]]. Even if you are a contributor, the workflows should give you an idea of how to get set up.
# Type Ctrl+3 followed by 'npfc' to narrow down to "New Projects from CVS".
+
# Hit Enter to open the wizard dialog, then select "Create new repository location", and click Next.
+
# Copy the following string without the quotes into the "Host" field: ":pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse".
+
# Click Next, select "Use existing module", scroll all the way down and multi-select platform-ui, platform-ui-examples, and platform-ui-tests.
+
# Click Finish to import all of our plug-ins into your workspace. A dialog asking to replace "org.eclipse.jface.databinding.examples" is expected (it appears in the tests and the examples module), just click "Yes" or "No", it doesn't really matter.
+
  
To check out individual parts such as only data binding, or JFace, use [http://www.eclipse.org/eclipse/platform-ui/psf/ Project Set Files]You can import the file into Eclipse via Ctrl+3, 'tpsi'This will check out the necessary projects into your workspaceWe provide Project Sets for committers and contributors and for HEAD and maintenance branches. Please file a bug if you would like to have other kinds of project set files added to that page.
+
 
 +
Our code is now contained in the git repo at
 +
git://git.eclipse.org/gitroot/platform/eclipse.platform.ui.git
 +
https://<userid>@git.eclipse.org/r/platform/eclipse.platform.ui
 +
  ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.ui
 +
 
 +
The Dependency Injection and runtime Eclipse Context code is in
 +
git://git.eclipse.org/gitroot/platform/eclipse.platform.runtime.git
 +
  https://<userid>@git.eclipse.org/r/platform/eclipse.platform.runtime
 +
  ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.runtime
 +
 
 +
 
 +
Use git or [[EGit]] to clone this repo.  See the instructions on setting up your repo for Gerrit for both EGit and/or the command line [[Gerrit#Doing Code Reviews with Gerrit]].
 +
 
 +
If using EGit, see [[Platform-releng/Git Workflows#Clone a repo]] on suggestions on how to clone a repo and set up a branch.
 +
 
 +
Our current branches:
 +
 
 +
* master - development towards Kepler/4.3
 +
* R4_2_maintenance - fixes for 4.2.x/Juno service releases
 +
* R3_8_maintenance - fixes for 3.8.x/Juno service releases
 +
 
 +
For more information on our development, see [[Platform UI/Git#Development in Juno]]
 +
 
 +
Note: we also maintain some E4-specific tools, hosted in the e4 incubator at (supports Gerrit):
 +
  git://git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git
 +
 
 +
And we support User Assistance (Help) contributions at:
 +
git://git.eclipse.org/gitroot/platform/eclipse.platform.ua.git
 +
https://<userid>@git.eclipse.org/r/platform/eclipse.platform.ua
 +
ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.ua
 +
 
 +
=== Creating a patch ===
 +
 
 +
Once a Gerrit change set is created, the change set should be posted on the bugzilla it came from so it can be reviewed.
 +
 
 +
The preferred method of contributions is now [[Gerrit]] but we can accept patches on [https://bugs.eclipse.org/bugs bugzilla] or from public git repos as well.  Please see [[Platform-releng/Git Workflows#Create a patch]] for more information on the Eclipse Foundation IP process as it relates to both bugzilla and git repos.
  
 
=== Unit Testing===
 
=== Unit Testing===
Testing is imperative to the health of the project.  We have a significant amount of tests.  The quantity of tests will keep growing as more functionality is added to Platform UI.  If you are contributing a fix or writing an enhancement it's a requirement that tests are written.  If you don't write them a committer will have to and that could slow down the contribution process.   
+
Testing is imperative to the health of the project.  We have a significant amount of tests.  The quantity of tests will keep growing as more functionality is added to Platform UI.  If you are contributing a fix or writing an enhancement, it is a requirement that tests are written.  If you don't write them a committer will have to and that could slow down the contribution process.   
  
 
There are a couple of things that you should know about our testing process:
 
There are a couple of things that you should know about our testing process:
Line 33: Line 63:
 
* To run tests, open the Run Configurations dialog (Ctrl+3, 'run...') and expand the "JUnit Plug-in Test" category to see the launch configurations we use to run the tests.
 
* To run tests, open the Run Configurations dialog (Ctrl+3, 'run...') and expand the "JUnit Plug-in Test" category to see the launch configurations we use to run the tests.
 
* If you create a new TestCase make sure to add it to the correct test suite. The test suite class can be found by looking at the launch configuration on the "Test" tab under "Test class". For example, the test suite for JFace is called org.eclipse.jface.tests.AllTests; the main UI test suite is org.eclipse.ui.tests.UiTestSuite.
 
* If you create a new TestCase make sure to add it to the correct test suite. The test suite class can be found by looking at the launch configuration on the "Test" tab under "Test class". For example, the test suite for JFace is called org.eclipse.jface.tests.AllTests; the main UI test suite is org.eclipse.ui.tests.UiTestSuite.
* If you want to make a good impression write tests.  This goes for any project of course.
+
* If you want to make a good impression, write tests.  This goes for any project, of course.
 +
 
 +
=== Coding Conventions ===
 +
* Follow the Eclipse Platform's [http://dev.eclipse.org/conventions.html Standards, Conventions and Guidelines].
 +
* UI will need you to use project-specific settings for compiler warnings/errors, code formatting etc. that are copied from the other UI plug-ins' settings.
 +
* Use "organize imports" (Ctrl-Shift-O) to clean up the imports (we do not use org.eclipse.* type notation).
 +
* Don't put CVS headers in the files (with revision information etc.)
 +
* The copyright header goes before the package declaration, starting in the very first line. For new files, list yourself "and others" instead of "IBM and others" in the first line. For changed files, add a contribution comment in the copyright header with your name and affiliation, and a bug id.
 +
* It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them, they can crop up due to compiler changes occassionally.
 +
* Non-externalized strings are considered errors, do not ship non-externalized strings.
 +
* Write/update Javadoc for all API you introduce/change. See [http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs Evolving Java-based APIs] by Jim des Rivières to understand what it means to maintain an API.
 +
 
 +
=== Before You Check In ===
 +
 
 +
* Commit comments are required for all code commits, bugs should be logged to track work and the bug number and a description is then used in the commit comment to describe the change. For example when fixing a bug, use exactly: "Fixed bug xxx: <title of bug>".  The "bug xxxx" part is really important as this is what is used to relate the bugs to the build submissions, so it must be formatted exactly that way (uppercase or lowercase bug should work). 
 +
* Before committing changes, catch up to all changes made by others, and then run the tests.
 +
* Don't commit your changes if this will cause compile errors for others.
 +
 
 
=== The Build===
 
=== The Build===
The Eclipse build is a bit of a mystery to newcomers.  But rest assured that if you break something everyone will know about it and we will laugh at you (not really but we might tease you, or send you a [http://dev.eclipse.org/mhonarc/lists/platform-releng-dev/msg09764.html|clown nose] if it was really bad).  If you do one thing it should be to sign up for the [https://dev.eclipse.org/mailman/listinfo/platform-releng-dev platform-releng-dev mailing list].  You'll receive emails when builds complete and when build and test failures occur.  It's always good to pay extra special attention on the mornings after you make a commit or someone makes a commit on your behalf.  The normal reaction to "breaking the build" is to log a bug, notify the platform-releng-dev list about it so that others can gauge the quality of the build, and then fix the bug.
+
The Eclipse build is a bit of a mystery to newcomers.  But rest assured that if you break something everyone will know about it and we will laugh at you (not really but we might tease you, or send you a [http://dev.eclipse.org/mhonarc/lists/platform-releng-dev/msg09764.html clown nose] if it was really bad).  If you do one thing it should be to sign up for the [https://dev.eclipse.org/mailman/listinfo/platform-releng-dev platform-releng-dev mailing list].  You'll receive emails when builds complete and when build and test failures occur.  It's always good to pay extra special attention on the mornings after you make a commit or someone makes a commit on your behalf.  The normal reaction to "breaking the build" is to log a bug, notify the platform-releng-dev list about it so that others can gauge the quality of the build, and then fix the bug.
  
== Newsgroup==
+
== Forum ==
We try to be prompt and responsive on the [http://www.eclipse.org/newsportal/thread.php?group=eclipse.platform newsgroup] but there's always room for improvement.  If you know the answer to a query feel free to respond.
+
We try to be prompt and responsive on the [http://www.eclipse.org/forums/?group=eclipse.platform forum] (newsgroup) but there's always room for improvement.  If you know the answer to a query feel free to respond.
  
 
== Wiki==
 
== Wiki==
 
The wiki is open and can be edited by all.  If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it.  If wanting to contribute a significant amount of information or create a new article we request that you [[../FAQ#How_do_I_report_a_bug.3F|log a bug]] so that we're aware of what you're contributing.  This is so that we can ensure consistency structurally and in the message conveyed.
 
The wiki is open and can be edited by all.  If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it.  If wanting to contribute a significant amount of information or create a new article we request that you [[../FAQ#How_do_I_report_a_bug.3F|log a bug]] so that we're aware of what you're contributing.  This is so that we can ensure consistency structurally and in the message conveyed.
  
[[Category:Platform UI]]
+
== IRC ==
 +
 
 +
Many Platform UI committers hang out on [[IRC]], on both #eclipse-dev and #eclipse-e4. Feel free to ask questions there, or join into development discussions.
 +
 
 +
[[Category:Platform UI]][[Category:How to Contribute]]
 +
 
 +
== Meetings ==
 +
 
 +
The team has bi-weekly phone calls for development discussions and planning. Anyone is welcome to join in. For call in details and minutes see [[E4/Meeting_Minutes]].

Revision as of 09:29, 15 March 2013

This page is a starting point for where to begin when wanting to contribute to the project. The goal is to educate and to be as up front as possible with expectations so that the process can be as efficient as possible.

Contents

Bugs

If you find a bug, log it. See the FAQ entry "How to Report a Bug", and a description of how a great bug report looks like. If you find a bug that you think is a duplicate, is not a bug, etc. feel free to comment saying so.

If wanting to track bug changes in Platform UI there are a few ways:

  • Via email. If you want to receive email when a bug is logged you can watch the Platform-UI-Inbox@eclipse.org user. You will receive email anytime a new bug is logged to this user or an update is made while assigned to this user. To set this up see Preferences -> Email Preferences -> User Watching. This will email you for all incoming Platform UI bugs; to follow all changes for Platform UI and IDE for bugs that an individual has not yet taken, watch platform-ui-triaged@eclipse.org as well.
  • Via Atom. You can convert any query in bugzilla to a feed that will update when a matched bug changes. To convert a search to a feed perform a search and select "Feed" at the bottom of the search results.

Contributing Code

Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature for Platform UI you'll need to know a few things before you contribute code.

Platform UI has switched to git as its SCM. For the old CVS instructions, check out Platform UI/How to Contribute/CVS.

Getting the code into your workspace

See Platform-releng/Git_Workflows#Gerrit_workflow_for_a_committer. Even if you are a contributor, the workflows should give you an idea of how to get set up.


Our code is now contained in the git repo at

git://git.eclipse.org/gitroot/platform/eclipse.platform.ui.git
https://<userid>@git.eclipse.org/r/platform/eclipse.platform.ui
ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.ui

The Dependency Injection and runtime Eclipse Context code is in

git://git.eclipse.org/gitroot/platform/eclipse.platform.runtime.git
https://<userid>@git.eclipse.org/r/platform/eclipse.platform.runtime
ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.runtime


Use git or EGit to clone this repo. See the instructions on setting up your repo for Gerrit for both EGit and/or the command line Gerrit#Doing Code Reviews with Gerrit.

If using EGit, see Platform-releng/Git Workflows#Clone a repo on suggestions on how to clone a repo and set up a branch.

Our current branches:

  • master - development towards Kepler/4.3
  • R4_2_maintenance - fixes for 4.2.x/Juno service releases
  • R3_8_maintenance - fixes for 3.8.x/Juno service releases

For more information on our development, see Platform UI/Git#Development in Juno

Note: we also maintain some E4-specific tools, hosted in the e4 incubator at (supports Gerrit):

 git://git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git

And we support User Assistance (Help) contributions at:

git://git.eclipse.org/gitroot/platform/eclipse.platform.ua.git
https://<userid>@git.eclipse.org/r/platform/eclipse.platform.ua
ssh://<userid>@git.eclipse.org:29418/platform/eclipse.platform.ua

Creating a patch

Once a Gerrit change set is created, the change set should be posted on the bugzilla it came from so it can be reviewed.

The preferred method of contributions is now Gerrit but we can accept patches on bugzilla or from public git repos as well. Please see Platform-releng/Git Workflows#Create a patch for more information on the Eclipse Foundation IP process as it relates to both bugzilla and git repos.

Unit Testing

Testing is imperative to the health of the project. We have a significant amount of tests. The quantity of tests will keep growing as more functionality is added to Platform UI. If you are contributing a fix or writing an enhancement, it is a requirement that tests are written. If you don't write them a committer will have to and that could slow down the contribution process.

There are a couple of things that you should know about our testing process:

  • The most tests are included in org.eclipse.ui.tests, but you will need the other test plug-ins as well to avoid missing dependencies.
  • If looking for tests for a specific class look for a class named {THECLASS}Test.java (e.g. UpdateStrategy.java -> UpdateStrategyTest.java).
  • To run tests, open the Run Configurations dialog (Ctrl+3, 'run...') and expand the "JUnit Plug-in Test" category to see the launch configurations we use to run the tests.
  • If you create a new TestCase make sure to add it to the correct test suite. The test suite class can be found by looking at the launch configuration on the "Test" tab under "Test class". For example, the test suite for JFace is called org.eclipse.jface.tests.AllTests; the main UI test suite is org.eclipse.ui.tests.UiTestSuite.
  • If you want to make a good impression, write tests. This goes for any project, of course.

Coding Conventions

  • Follow the Eclipse Platform's Standards, Conventions and Guidelines.
  • UI will need you to use project-specific settings for compiler warnings/errors, code formatting etc. that are copied from the other UI plug-ins' settings.
  • Use "organize imports" (Ctrl-Shift-O) to clean up the imports (we do not use org.eclipse.* type notation).
  • Don't put CVS headers in the files (with revision information etc.)
  • The copyright header goes before the package declaration, starting in the very first line. For new files, list yourself "and others" instead of "IBM and others" in the first line. For changed files, add a contribution comment in the copyright header with your name and affiliation, and a bug id.
  • It is considered good practice to write code that does not have warnings. If possible, fix warnings existing whenever you see them, they can crop up due to compiler changes occassionally.
  • Non-externalized strings are considered errors, do not ship non-externalized strings.
  • Write/update Javadoc for all API you introduce/change. See Evolving Java-based APIs by Jim des Rivières to understand what it means to maintain an API.

Before You Check In

  • Commit comments are required for all code commits, bugs should be logged to track work and the bug number and a description is then used in the commit comment to describe the change. For example when fixing a bug, use exactly: "Fixed bug xxx: <title of bug>". The "bug xxxx" part is really important as this is what is used to relate the bugs to the build submissions, so it must be formatted exactly that way (uppercase or lowercase bug should work).
  • Before committing changes, catch up to all changes made by others, and then run the tests.
  • Don't commit your changes if this will cause compile errors for others.

The Build

The Eclipse build is a bit of a mystery to newcomers. But rest assured that if you break something everyone will know about it and we will laugh at you (not really but we might tease you, or send you a clown nose if it was really bad). If you do one thing it should be to sign up for the platform-releng-dev mailing list. You'll receive emails when builds complete and when build and test failures occur. It's always good to pay extra special attention on the mornings after you make a commit or someone makes a commit on your behalf. The normal reaction to "breaking the build" is to log a bug, notify the platform-releng-dev list about it so that others can gauge the quality of the build, and then fix the bug.

Forum

We try to be prompt and responsive on the forum (newsgroup) but there's always room for improvement. If you know the answer to a query feel free to respond.

Wiki

The wiki is open and can be edited by all. If you find a typo, a broken link, or anything that you view as a small issue feel free to fix it. If wanting to contribute a significant amount of information or create a new article we request that you log a bug so that we're aware of what you're contributing. This is so that we can ensure consistency structurally and in the message conveyed.

IRC

Many Platform UI committers hang out on IRC, on both #eclipse-dev and #eclipse-e4. Feel free to ask questions there, or join into development discussions.

Meetings

The team has bi-weekly phone calls for development discussions and planning. Anyone is welcome to join in. For call in details and minutes see E4/Meeting_Minutes.