|Mailing List • Forums • IRC • mattermost|
|Open • Help Wanted • Bug Day|
- WTP: WebTools Platform, parent project since WTP3.0
- SSE: Structured Source Editing, for editors like XML, CSS, JSON
- 1 Contributing to JSDT
- 2 Setup the Development Environment
- 3 Testing
- 4 Gerrit Reviews
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 firstname.lastname@example.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
Bugzilla for JSDT Bugs
Here is a list of open JSDT bugs. We're working through them as fast as we can!
Don't forget to subscribe to Bugzilla notifications for JSDT. Here is an "how-to" reminder:
- Go to https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email
- Add email@example.com to the watch list, at the end of the page.
As Contributor, you can fix JSDT bugs and send code contributions via Gerrit:
- To start you need to sign the CLA and to [setup the development environment]
- Then pick an open JSDT Bug, if not assigned to any team member, assign it to yourself.
- Solve the bug and test the solution, so you can commit and push your change with Gerrit.
- Now wait for a committer who has to review and approve (+1) before your changes are committed.
Below you can read how to setup the development environment, get the source code, edit the source, run the application, perform tests, and commit the changes via Gerrit.
Setup the Development Environment
To setup the development environment you can either use a Full Stack Eclipse IDE loaded with the Target Platform Plug-ins, or use an Eclipse IDE for coding and keep a separate installation as a Target Platform.
Separating your development IDE from Target Platform makes your IDE lighter, more stable when adding development plug-ins and more flexible for development against different versions.
If you're new to this setup, watch once this video to see a full setup for JSDT development environment: https://www.youtube.com/watch?v=SFxfuudlau8 (for Mars.1).
Eclipse IDE + Target Platform aside
Download recent builds of Eclipse IDE and Target Platform from the eclipse download page: https://www.eclipse.org/downloads/
As an example, for Mars.2, you need to download:
After the downloads, unzip both installations. Launch the IDE, and remember you should never launch or update the Target Platform.
Target Platform, API Baseline and Other Preferences
For the development you'll need to edit Preferences, and set the Target Platform, API Baselines and other recommended values.
To set the Target Platform and the API Baseline open Windows > Preferences from menu and then select:
- Plug-in Development > API Baseline Click "Add Baseline" and point to the Target Platform installation
- Plug-in Development > Target Platform Click "Add.." and point to the Target Platform installation.
To set the other recommended preferences in line with the Platform_UI/How_to_Contribute guidelines open Windows > Preferences from menu and then 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
Note: If you already have local Git repositories with JSDT projects, you can switch to Git perspective, and import them in the Git Repository View, via the "Add an existing local repository" Link. So doing, the download of projects from the project set will re-use those imported repositories, instead of doing a full download.
JSDT Source Repositories
To edit JSDT code, you will need to fetch code from four project repositories. Below you can see the Gerrit URLs.
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
If you already provided Eclipse your Gerrit https password, you can clone and setup quickly by prepending your username to the URL as
The JSDT ProjectSet defines all the project needed to develop on JSDT, along with the needed repositories.
Then import all projects via:
- Import > Team > Team Project Set and choose the project set file
Please Note: Sometimes the ProjectSet could be not in sync with latest developments. If so, you can fix by adding missing projects, and looking in the \bundles\ folder of JSDT repositories.
JSDT Git 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
Here you can find information on JSDT testing by launching an inner eclipse, by building and testing locally and about functional testing scenarios.
Launch the Target Platform from IDE
Launching an inner eclipse with target platform plugins onboard, added by the plugins of which you are editing the source code:
- Create a new launch configuration, based on plugins contained in the target platform
- Then Run the launch configuration. You will see a new Inner Eclipse popping up.
- If needed you can debug this Eclipse instance you’re going to develop against.
You can check the video starting 9'44" to see how to choose plug-ins and run the application.
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
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://firstname.lastname@example.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!