Skip to main content
Jump to: navigation, search

Difference between revisions of "PDT/Contributing"

< PDT
m (Categorize required plugins)
Line 61: Line 61:
 
== Preparing and sending patches ==
 
== Preparing and sending patches ==
  
When you decide to send us your new amazing patch, you'll need:
+
When you decide to send us your new patch, you'll need:
  
 
# an Eclipse account (you can create it [https://accounts.eclipse.org/user/register here])
 
# an Eclipse account (you can create it [https://accounts.eclipse.org/user/register here])
 
# to sign the [https://www.eclipse.org/contribute/cla Eclipse Contributor Agreement]
 
# to sign the [https://www.eclipse.org/contribute/cla Eclipse Contributor Agreement]
# a public/private SSH RSA key pair (you can generate them with ssh-keygen on Linux and Mac, and PuTTYgen on Windows)
 
# add the public key to https://git.eclipse.org/r/#/settings/ssh-keys
 
# add your private key to Eclipse (''Window'' → ''Preferences'' menu item, then ''General'' → ''Network Connections'' → ''SSH2'')
 
  
Patches must be sent to Gerrit (a review system that can compile PDT and run tests).
+
Patches must be sent via GitHub pull requests: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
 
+
In order to create a Gerrit patch from inside Eclipse, switch to the Git perspective (''Window'' → ''Perspective'' → ''Open Perspective'' → ''Git'').
+
 
+
In the ''Git Repositories'' view, you should have ''org.eclipse.pdt'': expand the ''Remotes'' node and right click ''origin'' → ''Gerrit Configuration''.
+
 
+
If your Eclipse username is ''myusername'', specify that
+
* the push URI uses the SSH protocol
+
* the push URI is ssh://myusername@git.eclipse.org:29418/pdt/org.eclipse.pdt.git
+
  
 
Before sending patches, you should file a bug report at https://bugs.eclipse.org: every bug report will be assigned an unique ID (let's say it's 1234)
 
Before sending patches, you should file a bug report at https://bugs.eclipse.org: every bug report will be assigned an unique ID (let's say it's 1234)
 
To send the patch to Gerrit, in the Git perspective of Eclipse, right click the org.eclipse.pdt node in the Git Repositories view, then Commit…
 
  
 
The commit message must be like this:
 
The commit message must be like this:
Line 89: Line 76:
 
   Notes
 
   Notes
 
    
 
    
  Change-Id: I0000000000000000000000000000000000000000
 
 
   Signed-off-by: Your Name <your-email@example.com>
 
   Signed-off-by: Your Name <your-email@example.com>
  
 
Where:
 
Where:
  
* 1234<br />is the Eclipse bug ID. In case there's no Eclipse bug associates, use ''No bug'' instead of ''Bug 1234''.<br />If your patch is still in progress, to avoid confusion add a ''[WIP]'' prefix (eg: ''[WIP] No bug - This is an example'').
+
* 1234<br />is the GitHub issue
 
* Description<br />is the main title of the patch.
 
* Description<br />is the main title of the patch.
 
* Notes<br />are optional notes about the patch.
 
* Notes<br />are optional notes about the patch.
* Change-Id: I0000000000000000000000000000000000000000<br />This blank Change-Id line must be added as-is in the commit message.<br />After pushing successfully your patch to Gerrit, Gerrit will create a unique and final ''Change-Id'' to identify your patch.<br />If later you need to update the patch, use the gerrit link added to your bug report to retrieve the ''Change-Id'' value and replace the blank identifier ''I0000000000000000000000000000000000000000'' by the ''Change-Id'' affected to your patch.
 
 
* Your Name<br />is your real name.
 
* Your Name<br />is your real name.
 
* your-email@example.com<br />is your email address.
 
* your-email@example.com<br />is your email address.
  
 
PS: the commit author and submitter usually have the same value as the Signed-off-by.
 
PS: the commit author and submitter usually have the same value as the Signed-off-by.
 
By pushing the commit, you'll create - or update - a new Gerrit patch depending on the ''Change-Id'' value of your commit message.
 
The link to view it should be automatically added to your bug report (the link will look like https://git.eclipse.org/r/#/c/112773)
 
 
 
== EGerrit ==
 
 
To easily work with changes submitted by other contributors (visible [https://git.eclipse.org/r/q/project:pdt%252Forg.eclipse.pdt here]), you can use EGerrit.
 
 
You can install it from the marketplace (''Help'' menu → ''Eclipse Marketplace...'').
 
 
To configure it, first open the ''Gerrit Dashboard (EGerrit)'' view (from ''Window'' menu → ''Show View'' → ''Other...'').
 
In the EGerrit view, click ''Gerrit Server'' and add a server with these parameters:
 
* URL: https://git.eclipse.org/r
 
* User: your email address
 
* Password: your Eclipse password
 
 
From the EGerrit view you can see all the changes, and you can easily checkout them.
 
 
  
 
== Compiling PDT outside Eclipse ==
 
== Compiling PDT outside Eclipse ==
Line 128: Line 94:
 
First of all, you need to clone the PDT git repository:
 
First of all, you need to clone the PDT git repository:
  
   git clone http://git.eclipse.org/gitroot/pdt/org.eclipse.pdt.git
+
   git clone https://github.com/eclipse/pdt
  
 
If you are an Eclipse user and/or a PDT committer:
 
If you are an Eclipse user and/or a PDT committer:
  
   git clone ssh://committerid@git.eclipse.org:29418/pdt/org.eclipse.pdt.git
+
   git clone git@github.com:eclipse/pdt.git
  
 
To build PDT, you need Maven, and launch these commands:
 
To build PDT, you need Maven, and launch these commands:
Line 158: Line 124:
  
 
Sonar is used in order to track Code Quality:
 
Sonar is used in order to track Code Quality:
# Sonar dashboard: https://dev.eclipse.org/sonar/project/index/org.eclipse.php:org.eclipse.pdt.releng
+
# Sonar dashboard: https://sonarcloud.io/dashboard?id=eclipse-tools.pdt.main
# Reports are ganerated based on dedicated build: https://ci.eclipse.org/pdt/job/pdt-sonar
+
# Reports are ganerated based on dedicated build: https://ci.eclipse.org/pdt/job/pdt-sonarcloud
  
 
== Developer Resources ==
 
== Developer Resources ==

Revision as of 14:06, 12 May 2020


Working with PDT source code in Eclipse

Which Eclipse version?

To comfortably edit PDT source code and execute it, you can use Eclipse IDE for Eclipse Committers, which contains some required plugins (Java Development Tools, Plug-in Development Environment, Git Integration, …). You can download it from here.

Required plugins

In addition to the plugins bundled with Eclipse, PDT requires other plugins that can be installed via the HelpInstall New Software… menu item.

You'll need to add the following software site (you can add them by clicking the Manage button in the Install dialog):

Once you defined the above update sites, you should install these plugins:

  • Category "All Orbit Bundles"
    • Apache Commons Exec Plug-in
  • Category "Business Intelligence, Reporting and Charting"
    • BIRT Framework
  • Category "Dynamic Languages Toolkit (DLTK)"
    • Dynamic Languages Toolkit - Core Frameworks SDK
    • Dynamic Languages Toolkit - Core Lucene Index Frameworks SDK
    • Dynamic Languages Toolkit - Mylyn Integration
  • Category "Dynamic Languages Toolkit (DLTK) Tests"
    • DLTK Core Tests
  • Category "General Purpose Tools"
    • Parallel Tools Platform
    • TM Terminal
  • Category "Modeling"
    • Zest SDK
  • Category "Web, XML, Java EE and OSGi Enterprise Development"
    • Eclipse Web Developer Tools

Importing the PDT projects

To import and prepare the PDT projects in Eclipse:

  • Choose the FileImport… menu item, then choose TeamTeam Project Set, and specify to import from the URL https://git.eclipse.org/c/pdt/org.eclipse.pdt.git/plain/dev/psf/pdt-dev.psf
  • Select current Target Platform (WindowPreferences menu item, then Plug-in DevelopmentTarget Platform, then select org.eclipse.php.target.current and choose Apply and Close)
  • (Optional) Disable API Baselines errors (WindowPreferences menu item, then Plug-in DevelopmentAPI Baselines, then choose Missing API baselineIgnore)

Running and debugging PDT

In order to run (and debug) PDT, you can choose the RunDebug Configurations… menu item, and add a new Eclipse Application. Alternatively, PDT can be run/debug just by selecting one of PDT projects and choose Run AsEclipse Application from the context menu.

NOTE: Currently because of bug 534370 MANIFEST.MF in org.eclipse.php.core plugin can indicate errors, you can ignore them.

You can keep the default settings, but it's very handy to go to the Common tab, and check Debug and Run in the Display in favorites menu checklist (so that you'll be able to launch the debug environment by clicking the Debug or Run icons in the toolbar).

When launching the debug application, a new Eclipse instance will be executed: you can create a new PHP project, and you can place breakpoints and analyze the execution in the Eclipse instance containing the PDT project.

PS: when executing PDT, you may see some validation warnings: you can safely ignore them.


Preparing and sending patches

When you decide to send us your new patch, you'll need:

  1. an Eclipse account (you can create it here)
  2. to sign the Eclipse Contributor Agreement

Patches must be sent via GitHub pull requests: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests

Before sending patches, you should file a bug report at https://bugs.eclipse.org: every bug report will be assigned an unique ID (let's say it's 1234)

The commit message must be like this:

 Bug 1234 - Description
 
 Notes
 
 Signed-off-by: Your Name <your-email@example.com>

Where:

  • 1234
    is the GitHub issue
  • Description
    is the main title of the patch.
  • Notes
    are optional notes about the patch.
  • Your Name
    is your real name.
  • your-email@example.com
    is your email address.

PS: the commit author and submitter usually have the same value as the Signed-off-by.

Compiling PDT outside Eclipse

You can compile the PDT source code outside Eclipse.

First of all, you need to clone the PDT git repository:

 git clone https://github.com/eclipse/pdt

If you are an Eclipse user and/or a PDT committer:

 git clone git@github.com:eclipse/pdt.git

To build PDT, you need Maven, and launch these commands:

 # project root dir
 cd org.eclipse.pdt
 # build and run all tests
 mvn clean install
 # build and ignore all tests
 mvn clean install -DskipTests
 # build and skip performance tests only (recommend)
 mvn clean install -DskipPdtPerformanceTests

To build the PDT release:

 # project root dir
 cd org.elipse.pdt
 # this will produce normalized, signed and packed release, inside eclipse.org infrastructure
 mvn clean install -Prelease
 #this will produce normalized and packed release
 mvn clean install -Prelease -DskipSign


Sonar

Sonar is used in order to track Code Quality:

  1. Sonar dashboard: https://sonarcloud.io/dashboard?id=eclipse-tools.pdt.main
  2. Reports are ganerated based on dedicated build: https://ci.eclipse.org/pdt/job/pdt-sonarcloud

Developer Resources

After setting up PDT source code please have a look at a set of docs we have for our developers on the PDT#Developer_Resources page.


Update help pages

All help pages sitting under plugins/org.eclipse.php.help/docs/source/ in *.md format.

While make install, our build system converting it to *.html files in exactly same structure and also:

  1. Remove ###- part from each *.md file, and fix all internal links.
  2. Regenerate IPHPHelpContextIds interface
  3. Build helpContexts.xml file
  4. Build toc.xml file

Which editor should I use?

You can work with any markdown editor, but because our build system use Mylyn Wikitext, you should install wikitext editor from https://eclipse.org/mylyn/downloads/ to be sure that everything is ok.

Howto register new help context id?

Add this code to markdown file:

 <!--context:your_context_id-->

Back to the top