Skip to main content
Jump to: navigation, search

Difference between revisions of "Recommenders/ContributorGuide"

m (Reporting Bugs)
Line 64: Line 64:
= Reporting Bugs  =
= Reporting Bugs  =
Code Recommenders' Bugzilla is accessible via
Code Recommenders' Bugzilla is accessible via
= Contributing Code =
= Contributing Code =

Revision as of 06:23, 28 May 2011

Development Environment

Building and testing Code Recommenders on your machine requires the following tools to be installed:

  1. Eclipse 3.6
  2. Java 6
  3. Maven 3+
  4. Git 1.7+

Obtaining Sources

Code Recommenders is hosted in Git. To browse the repositories use Gitweb. To checkout sources from command line use:

 git clone git:// recommenders

Building From Sources

Code Recommenders uses Maven Tycho to build its plug-ins. Look out for the pom.xml files in the repositories. The typical command to build Code Recommenders from command line is:

mvn clean install

That's it.

If this fails on your machine send a mail to the developer mailing list and report this issue.

Note: Code Recommenders MUST be build once with Maven.
The recommender models are not hosted in the repository but on an external website. In order to run code completion, these models need to be downloaded once. This happens automatically during the first maven build.

Compiling From Eclipse

After you have successfully (i) cloned the repository and (ii) run the first maven build, you are ready to import all required plug-ins, features, and update-sites from ${git-repository.basedir} into Eclipse.

It's recommended to use a fresh Eclipse workspace since we work with target platforms to build Code Recommenders in Eclipse. If you are new to target platforms please check out this Eclipse Help page for details.

After import you will see quite a lot compile errors due to missing 3rd-party plug-ins not available in your current Eclipse installation. To fix that you need to set the target platform of the workspace. This is done by:

  1. Opening the target platform definition file under /org.recommenders.releng/
  2. Waiting until Eclipse resolved and downloaded all plug-ins (check the progress monitor). This may take a while for the first time.
  3. Click on Set as Target Platform on the upper right corner of the editor.
  4. Now. a workspace full build is started by Eclipse. Wait until the build is finished.
  5. Check that all compile errors are gone now - except for org.eclipse.recommenders.*fixture* projects. They don't compile per construction.
  6. If not:
    1. refresh the complete workspace and trigger a second full rebuild manually.
    2. If still errors show up, please report this to the developer mailing list.
  7. Finally, ensure that the file /org.eclipse.recommenders.rcp.codecompletion.calls/data/ actually exists in your workspace.

Now you are ready to start a new Eclipse Runtime with Code Recommenders.

Get in Contact


Code Recommenders user forum is here: If you want to report an issue, request new features, or just get in contact with the development team, this is the preferred way.

Mailing List

Code Recommenders also maintains a developer mailing list. The list is used for announcements like committer election or notifying committers about build changes etc. Subscription is required to post messages to the list which can be done here:

Reporting Bugs

Code Recommenders' Bugzilla is accessible via

Contributing Code

Shamelessly stolen and adopted from here.

There are just a few things to follow that make contributing simple and fast.

  1. Create a local feature branches.
  2. Make separate commits for logically separate changes.
  3. Generate your patch using git tools out of your commits.
  4. Check the license.
  5. Review the Eclipse Due Diligence Process.
  6. Sending your patches.

Each step is described in detail below. If some detail in unclear, let us know.

Create a local feature branches

Whenever you create a patch or new feature, just create a new branch as follows:

git branch -b patch-<name>

This creates a new feature branch you can easily work on, synchronize and create patches from later.

Make separate commits for logically separate changes.

  • Unless your patch is really trivial, you should not be sending out a patch that was generated between your working tree and your commit head. Instead, always make a commit with complete commit

message and generate a series of patches from your repository. It is a good discipline.

  • In each commit message, describe the technical detail of the change(s).
  • If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces.
  • Committers in general are very picky about formatting. Make sure your final version of every file was formatted using the Eclipse code formatter

using the project specific settings (Properties->Java Code Style->Formatter->"Java Conventions [built-in]").

Generate your patch using git tools out of your commits.

  • Git based diff tools (git, and StGIT included) generate unidiff, which is the only acceptable format.
  • You do not have to be afraid to use -M option to "git diff" or "git format-patch", if your patch involves file renames. The receiving end can handle them just fine.
  • Please make sure your patch does not include any extra files which do not belong in a patch submission.
  • Make sure to review your patch after generating it, to ensure accuracy.
  • Before sending out, please make sure it cleanly applies to the "master" branch head (i.e., rebase your feature branch with master).

Check the license.

  • Code Recommenders is licensed under the Eclipse Public License (EPL).
  • Under this licensing model *every* file within the project *must* list which license covers it in the header of the file. Any new contributions to an existing file *must* be submitted under

the current license of that file. Any new files *must* clearly indicate which license they are provided under in the file header.

  • Please verify that all newly created files have appropriate license header.
  • Please verify that you are legally allowed and willing to submit your changes under the license covering each file *prior* to submitting your patch. It is virtually impossible to remove a patch once it

has been applied and pushed out.

Review the Eclipse Due Diligence Process.

Sending your patches.

  • "git format-patch" command follows the best current practice to format a commit as a reviewable text message.
  • At the beginning of the patch should come your commit message, a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch

from somebody else, optionally, at the beginning of the e-mail message just before the commit message starts, you can put a "From: " line to name that person.

  • You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" material between the three dash lines and the diffstat, or please

place it in the bug description itself.

  • If you don't have to add any additional information, this command may be all you need:
 git format-patch -M master --stdout > <your-feature-name>.patch
  • Then, open a new bug on the Eclipse bug tracker on the EGit project:
  • Attach the mailbox file(s) created by "git format-patch" to the bug.

  • From here follow the conversation that happens in Bugzilla. You might be asked several times to revise your code, to add tests etc. before you patch finally gets submitted.

Back to the top