Difference between revisions of "JSDT/Development"

Revision as of 15:49, 5 March 2016

JSDT is a subproject of WTP providing JavaScript editing features based on JDT; JSON and other editors based on SSE; Nodejs and JS debugging support based on ChromeDevTools and much more.
Visit the project pages below to see who is involved, and then click to the developer resources to get the list of Git and Gerrit repositories:

• JSDT: JavaScript Development Tools
• WTP: WebTools Platform, parent project since WTP3.0
• SSE: Structured Source Editing, for editors like XML, CSS, JSON
• JDT: Java Development Tools, extended by the JavaScript Editor

Contributing to JSDT

The JSDT is driven by a small and dedicated development team with limited resources. ANY serious developers or contributors will be enthusiastically welcomed. For more information on how to become a Committer, read how we nominate and elect new committers according the standard Eclipse process.

To contribute to JSDT you can report bugs, resolve bugs and write documents or create media contents to spread your knowledge.

Getting in touch with the Community

For more information about contributing to JSDT or for questions about its internals you have few options:

• contact wtp-dev@eclipse.org after you subscribed to the wtp-dev mailing list.
• chat via IRC on the #eclipse or #eclipse-dev channel
• get in touch on the Eclipse mattermost webtools channel
• ask the WebTools Project forum
• check the JSDT Confcalls

Reporting Bugs

Report a bug through Eclipse Bugzilla under WebTools category, JSDT component.

Here is a list of open JSDT bugs. We're working through them as fast as we can!

You can receive notifications of incoming bugs by monitoring account jsdt.javascript-inbox@eclipse.org in https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email

Development Environment Setup

There are several ways to setup the development environment. Here are two good ones:

• Work on an Eclipse IDE and keep a separate Eclipse installation as a Target Platform. This separation IDE vs. TP leads to an easy setup and good flexibility.
• Work on a Full Stack Eclipse = Eclipse IDE + all plugins needed in Target Platform. With a single installation, you need to know the full list of needed plug-ins in advance, and it shouldn't be faster than the previous method.

Eclipse IDE + Target Platform aside

For this setup you will be using an Eclipse installation for development (IDE) and an Eclipse installation as Target Platform (TP). As a gentle introduction, you can watch this 12 minutes video: setup JSDT development environment (Mars.1).

Start downloading two Eclipse installations

• IDE (dev tools) : Eclipse for RCP and RAP developers (Mars.2)
• TP (target) : Eclipse IDE for Java EE Developers (Mars.2)

This document explain the first kind of setup

Then unzip both on local disk; launch the IDE (the one you'll use for development) and click away the welcome window. and setup IDE Properties and TP+Baseline as follows.

Target Platform and API Baseline

Set the Target Platform and the API Baseline pointing to the Target Platform, which in our case is the Eclipse IDE for Java EE.

From Windows > Preferences choose

• Plug-in Development > API Baseline and point to the Target Platform installation
• Plug-in Development > Target Platform and point to the Target Platform installation.

IDE Properties Setup

As an expert developer you might have your own setup, but below there is a recommended setup for all the other relevant IDE properties, in line with the Platform UI guidelines .

From Windows > Preferences select:

• Preferences > General > Workspace, set text file delimiters to Unix line delimiters
• Preferences > Java > Editor > Save Actions, enable the “Perform the selected actions ..” and set:
  • Format Source Code > Format Edited Lines: to avoid formatting the whole file, but limit the changes to edited lines.
  • Additional Actions > Remove Trailing Whitespaces: to avoid adding trailing whitespaces
• Preferences > Java > Installed JREs add the needed JREs. Usually I add Java8, 7 and 6.

Get the Source Code

Download the projectSet defining all the needed JSDT projects along with their repositories:

wst.jsdt_.allProjects_20160209.psf

Then import all projects via:

• Import > Team > Team Project Set then choose the project set file

Git / Gerrit Repositories

As an expert user, you might want to clone from Git repositories before importing the project set. In this case, you can use the Gerrit URLs below.

https://git.eclipse.org/r/p/jsdt/webtools.jsdt
https://git.eclipse.org/r/p/sourceediting/webtools.sourceediting
http://git.eclipse.org/gitroot/www.eclipse.org/webtools.git
https://git.eclipse.org/r/platform/eclipse.platform.runtime

Note: for a direct clone + setup Gerrit credentials, edit the above URLs adding your username as follows https://<YOUR-USERNAME>@git.eclipse.org/..., and at the first clone, provide the Gerrit password as you can see in Gerrit https settings

You can find the Git Repositories: webtools.jsdt.git. See also JSDT/Developer Resources

JSDT Sources

Git Repositories: http://git.eclipse.org/c/jsdt/webtools.jsdt.git/ webtools.jsdt.git Developer resources https://projects.eclipse.org/projects/webtools.jsdt/developer Detailed repository contents: http://wiki.eclipse.org/WTP_Git_Migration_Checklist

Building and testing JSDT locally

Simply run mvn clean verify -Pbuild-individual-bundles -DskipTests=false. This command will run the Unit-tests. After the build, you can install your JSDT snapshot in an Eclipse IDE or other RCP application using the p2 repository in location site/target/repository

JSDT Functional Testing

Testing Scenarios

Gerrit Reviews

Pushing a new patch for review

You can use Gerrit (mandatory reading, important to set up hooks, SSH keys, CLA & other) to push Git commits on JSDT repositories. The repo URL for JSDT@Gerrit is ssh://user@git.eclipse.org:29418/jsdt/webtools.jsdt. Once logged into Gerrit, you can see more details about the URL at https://git.eclipse.org/r/#/admin/projects/jsdt/webtools.jsdt .

Assuming you named this repo gerrit, you can push a commit to one of this repository with

$ git push gerrit HEAD:refs/for/master

This will give you the URL of the Gerrit review where you can interact with project committers to get your commit merged.

In case you need to push another version of the patch, don't forget to copy the Change-Id from the Gerrit review if you didn't set up the git hook. Providing another version of the patch doesn't require a new commit, simply amend the one you already pushed, and push it again:

$ git log -1 #Shows the commit. Message should contain Sign-Off-By and Change-Id
$ git add file/to/change
$ git commit --amend # add --signoff if Sign-Off-By is missing, and copy Change-Id from Gerrit review if missing
$ git push gerrit HEAD:refs/for/master # will create another version of the patch, on the same review.

Reviewing a patch

Incoming patch automatically triggers a build and will receive an automated vote according to whether patch breaks the build/tests or not. The CI job providing this vote is https://hudson.eclipse.org/webtools/job/jsdt-gerrit.

• Anytime Hudson votes with -1, it generally means that something is wrong with the patch: it breaks build or make a test failing, so the patch shouldn't be merged. The build log should be inspected by submitter and reviewers to understand the cause of the bug and submit (or assist in submitting) a better patch.
• Hudson voting +1 means that the test didn't introduce any regression visible by build or automated tests.

Anyone is free to add comments and vote on a review. Committers have the final power to decide whether or not a patch can be merged.

List reviews and be notified

You can see the list of open Gerrit reviews at https://git.eclipse.org/r/#/q/status:open+project:jsdt/webtools.jsdt,n,z .

Regular contributors and committers should really subscribe to notifications of proposed patches. You can set up notifications for proposed incoming changes at https://git.eclipse.org/r/#/settings/projects

Static analysis with SonarQube

JSDT uses SonarQube to get reports about static analysis. Those can show potential bugs, performance traps, or just bad practices. Here is the status of JSDT on these topics: https://dev.eclipse.org/sonar/dashboard/index/org.eclipse.webtools.jsdt:jsdt-parent . Any help to clean up warnings is welcome!