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.

+

This page is a starting point for where to begin when wanting to contribute to the project. Contribution means not only contributing code but also reporting bugs, triaging bugs, answering questions on newsgroups, documentation, and even spreading the word by blogging or giving a talk on your local Eclipse DemoCamp. The goal of this wiki page is to educate and to be as up front as possible with expectations so that the process can be as efficient as possible.

−

== Bugs==

+

== Reporting Bugs==

If you find a bug, log it on the [https://bugs.eclipse.org/bugs Eclipse bugzilla] to Eclipse > JDT > UI. See the 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 on the [https://bugs.eclipse.org/bugs Eclipse bugzilla] to Eclipse > JDT > UI. See the 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 JDT UI there are a few ways:

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

−

* Via email. If you want to receive email when a bug is logged you can watch the '''jdt-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 JDT UI bugs.

+

* Via e-mail. If you want to receive e-mail when a bug is logged you can watch the '''jdt-ui-inbox@eclipse.org''' user. You will receive e-mail 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 e-mail you for all incoming JDT UI bugs.

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

== Contributing Code==

== Contributing Code==

Whether you're wanting to fix a typo in javadoc or to implement the next whiz bang feature for JDT 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 JDT UI you'll need to know a few things before you contribute code.

−

−

JDT UI has switched to git as its SCM.

=== Getting the code into your workspace ===

=== Getting the code into your workspace ===

−

+

Our code is now contained in the [http://git.eclipse.org/c/jdt/eclipse.jdt.ui.git/ Git repo] at

−

Our code is now contained in the git repo at

+

git://git.eclipse.org/gitroot/jdt/eclipse.jdt.ui.git

git://git.eclipse.org/gitroot/jdt/eclipse.jdt.ui.git

−

Use git or [[EGit]] to clone this repo.

+

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

−

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

+

* You may not need to import all projects in the repo to your workspace. The important JDT UI plug-ins are listed [http://www.eclipse.org/jdt/ui/dev.php#plugins here].

+

* To satisfy dependencies on test projects you need to clone the following git repositories

* If you are a frequent contributor, it is also recommended to clone the JDT/Core repo and have 'org.eclipse.jdt.core' project in your workspace

+

git://git.eclipse.org/gitroot/jdt/eclipse.jdt.core.git

Our current branches:

Our current branches:

−

* master - development towards Juno - 4.2/3.8

+

* master - development towards Kepler - 4.3

−

* R3_7_maintenance - fixes for 3.7.2/Indigo SR2

+

* R3_8_maintenance - fixes for 3.8.1/Juno SR1

+

+

The doc projects can be found in

+

git://git.eclipse.org/gitroot/platform/eclipse.platform.common.git

+

+

=== Configuring the workspace ===

+

Getting the code is the first and the biggest step, but there are a few more steps

+

+

* JDT UI uses project-specific settings for compiler warnings/errors, code formatting etc, which you will automatically get when you clone the Git repository. So you do not have to worry about configuring these.

+

+

* However we have the following '''Save Actions''' enabled in our workspaces:

+

** Format edited lines

+

** Organize imports

+

** Remove trailing white spaces on non-empty lines

+

+

* For development in the master branch, the '''target platform''' should be the latest 3.8 M-build. By default, the Eclipse SDK will use the Running Platform as the target platform. However you may want to use a different Eclipse version for development, for example some committers use Eclipse 4.x for development. In such a case you should still download the latest 3.8 M-build and use that as the target platform.

+

+

* Enable '''API tooling''', and specify an [[Version_Numbering#API_Baseline_in_API_Tools|appropriate API baseline]]. For example, for 4.3 development the baseline should be 3.8.

+

+

* You also need Java SE 5 or later to successfully compile the code.

=== Creating a patch ===

=== Creating a patch ===

Line 40:

Line 64:

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:

−

*Most tests are included in org.eclipse.jdt.ui.tests and org.eclipse.jdt.ui.tests.refactoring, but you will need the other test plug-ins as well to satisfy dependencies.

+

*Most tests are included in '''org.eclipse.jdt.ui.tests''' and '''org.eclipse.jdt.ui.tests.refactoring''', but you will need the other test plug-ins as well to satisfy dependencies.

*The main test suite for org.eclipse.jdt.ui.tests is '''org.eclipse.jdt.ui.tests.AutomatedSuite''', and the main test suite for org.eclipse.jdt.ui.tests.refactoring is '''org.eclipse.jdt.ui.tests.refactoring.all.AllAllRefactoringTests'''.

*The main test suite for org.eclipse.jdt.ui.tests is '''org.eclipse.jdt.ui.tests.AutomatedSuite''', and the main test suite for org.eclipse.jdt.ui.tests.refactoring is '''org.eclipse.jdt.ui.tests.refactoring.all.AllAllRefactoringTests'''.

*If you create a new TestCase make sure to add it to the correct test suite.

*If you create a new TestCase make sure to add it to the correct test suite.

Line 47:

Line 71:

=== Coding Conventions ===

=== Coding Conventions ===

* Follow the Eclipse Platform's [http://dev.eclipse.org/conventions.html Standards, Conventions and Guidelines], and the [http://www.eclipse.org/jdt/ui/dev.php#documents additional rules used in JDT UI].

* Follow the Eclipse Platform's [http://dev.eclipse.org/conventions.html Standards, Conventions and Guidelines], and the [http://www.eclipse.org/jdt/ui/dev.php#documents additional rules used in JDT UI].

−

* Also go through the document on [http://www.eclipse.org/jdt/ui/contributions.txt things to remember when contributing code to JDT UI]

+

* The copyright header goes before the package declaration, starting in the very first line.

−

* JDT UI uses project-specific settings for compiler warnings/errors, code formatting etc, which you will automatically get when you clone the Git repository.

+

** For new files, list yourself "and others" instead of "IBM and others" in the first line.

−

* In addition we have the following '''Save Actions''' enabled in our workspaces.

+

** For each changed file update the copyright year (if required), and fill out this template and add it to the header comment:

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

−

** Remove trailing white spaces on non empty lines

+

−

* 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 each changed file, fill out this template and add it to the header comment:

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

* 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&egrave;res to understand what it means to maintain an API.

* 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&egrave;res to understand what it means to maintain an API.

+

* It might also be useful to read the detailed document on [http://www.eclipse.org/jdt/ui/contributions.txt things to remember when contributing code to JDT UI]

=== Before You Check In ===

=== Before You Check In ===

Line 63:

Line 84:

* 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: &quot;Fixed bug xxx: &lt;title of bug&gt;&quot;. The &quot;bug xxxx&quot; part is really important as this is what is used to relate code changes to bugs.

* 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: &quot;Fixed bug xxx: &lt;title of bug&gt;&quot;. The &quot;bug xxxx&quot; part is really important as this is what is used to relate code changes to bugs.

* Before committing changes, catch up to all changes made by others, and then run the tests.

* 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, or when there are test failures.

+

* Don't commit your changes if this will cause compile errors or API errors for others, or when there are test failures.

=== The Build===

=== The Build===

−

We commit a change only when the tests are green, hence build failures should not occur normally. Even so things can go wrong, hence 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.

+

We commit a change only when the tests are green, hence build failures should not occur normally. Even so things can go wrong, hence sign up for the [https://dev.eclipse.org/mailman/listinfo/platform-releng-dev platform-releng-dev mailing list]. You'll receive e-mails 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==

+

== Newsgroup/Forum ==

−

We try to be prompt and responsive on the [http://www.eclipse.org/forums/index.php/f/13/ 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/index.php/f/13/ newsgroup] but there's always room for improvement. If you know the answer to a query feel free to respond. It is also helpful to answer questions on stackoverflow which are tagged 'jdt' or 'eclipse-jdt'.

== 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 [[../How_to_Contribute#Bugs|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 you plan to contribute a significant amount of information or create a new article, we request that you [[../How_to_Contribute#Reporting_Bugs|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:How to Contribute]]

[[Category:How to Contribute]]

Revision as of 05:10, 14 November 2012

This page is a starting point for where to begin when wanting to contribute to the project. Contribution means not only contributing code but also reporting bugs, triaging bugs, answering questions on newsgroups, documentation, and even spreading the word by blogging or giving a talk on your local Eclipse DemoCamp. The goal of this wiki page is to educate and to be as up front as possible with expectations so that the process can be as efficient as possible.

Reporting Bugs

If you find a bug, log it on the Eclipse bugzilla to Eclipse > JDT > UI. See the 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 JDT UI there are a few ways:

Via e-mail. If you want to receive e-mail when a bug is logged you can watch the jdt-ui-inbox@eclipse.org user. You will receive e-mail 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 e-mail you for all incoming JDT UI bugs.

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 JDT UI you'll need to know a few things before you contribute code.

Configuring the workspace

Getting the code is the first and the biggest step, but there are a few more steps

JDT UI uses project-specific settings for compiler warnings/errors, code formatting etc, which you will automatically get when you clone the Git repository. So you do not have to worry about configuring these.

However we have the following Save Actions enabled in our workspaces:

Format edited lines

Organize imports

Remove trailing white spaces on non-empty lines

For development in the master branch, the target platform should be the latest 3.8 M-build. By default, the Eclipse SDK will use the Running Platform as the target platform. However you may want to use a different Eclipse version for development, for example some committers use Eclipse 4.x for development. In such a case you should still download the latest 3.8 M-build and use that as the target platform.

Enable API tooling, and specify an appropriate API baseline. For example, for 4.3 development the baseline should be 3.8.

You also need Java SE 5 or later to successfully compile the code.

Creating a patch

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 JDT 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:

Most tests are included in org.eclipse.jdt.ui.tests and org.eclipse.jdt.ui.tests.refactoring, but you will need the other test plug-ins as well to satisfy dependencies.

The main test suite for org.eclipse.jdt.ui.tests is org.eclipse.jdt.ui.tests.AutomatedSuite, and the main test suite for org.eclipse.jdt.ui.tests.refactoring is org.eclipse.jdt.ui.tests.refactoring.all.AllAllRefactoringTests.

If you create a new TestCase make sure to add it to the correct test suite.

If you want to make a good impression, write tests. This goes for any project, of course.

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: "Fixed bug xxx: <title of bug>". The "bug xxxx" part is really important as this is what is used to relate code changes to bugs.

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 or API errors for others, or when there are test failures.

The Build

We commit a change only when the tests are green, hence build failures should not occur normally. Even so things can go wrong, hence sign up for the platform-releng-dev mailing list. You'll receive e-mails 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 newsgroup but there's always room for improvement. If you know the answer to a query feel free to respond. It is also helpful to answer questions on stackoverflow which are tagged 'jdt' or 'eclipse-jdt'.

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