Skip to content

Contributing to Keshmesh

Jump to bottom Edit New page
Mohsen Vakilian edited this page Nov 27, 2013 · 23 revisions

Setting up the development environment

  1. Install Eclipse Helios (3.6.x).
  2. Get the source code of Keshmesh from [email protected]:reprogrammer/keshmesh.git and check out to the branch you want to contribute to.
  3. Set the default coding style of your Eclipse workspace to Keshmesh Code Style Conventions. The Keshmesh code style conventions file is at [coding-conventions/keshmesh-CodingStyle.xml]((https://github.com/reprogrammer/keshmesh/blob/master/coding-conventions/keshmesh-CodingStyle.xml).

Import the dependencies of Keshmesh

Either check out the dependencies from https://bitbucket.org/reprogrammer/keshmesh-dependencies or follow the instructions below to fetch the dependencies from their original repositories.

  1. Check out the following WALA projects from the trunk or incubator folders of the Subversion repository of WALA to your Eclipse workspace (Note that Keshmesh may not necessarily work with the latest version of WALA. So, please check out the specific revisions of WALA plug-ins that we have used to test Keshmesh).
    1. com.ibm.wala.cast
    2. com.ibm.wala.cast.java
    3. com.ibm.wala.cast.java.jdt
    4. com.ibm.wala.cast.js
    5. com.ibm.wala.cast.js.rhino
    6. com.ibm.wala.core
    7. com.ibm.wala.eclipse
    8. com.ibm.wala.ide
    9. com.ibm.wala.shrike
    10. com.ibm.wala.util
  2. To resolve the problems Project 'com.ibm.wala.cast.js' is missing required library: 'lib/htmlparser-1.3.1.jar' and Project 'com.ibm.wala.cast.js' is missing required library: 'lib/jericho-html-3.2.jar', run the target getJars of the project's ANT file.
  3. To resolve the problem Project 'com.ibm.wala.cast.js.rhino' is missing required library: 'lib/js.jar', run the target getJars of the project's ANT file manually. The ant target fails with an error.
  4. To be able to run the tests, check out the source code of the following Eclipse plugins. Note that we picked these version numbers because these are the latest versions not more recent than the version of org.eclipse.jdt.ui in Eclipse Helios SR1 (3.6.1.r361_v20100825-0800). Also, note that because of the dependencies of the following bundles on Eclipse Helios, you can only run the tests in Eclipse Helios (3.6.x). The source code of these plugins were used to be at :pserver:[email protected]:/cvsroot/eclipse. However, they have been migrated to the following Git repositories and the CVS repositories seem to have been deleted.
    1. org.eclipse.jdt.ui.tests v20100824-0800
    2. org.eclipse.test.performance v20100122
    3. org.eclipse.text.tests v20100824-0800
  5. Check out the following FindBugs plugins from the trunk of the FindBugs Subversion repository (Note that Keshmesh may not necessarily work with the latest version of FindBugs. So, please check out the specific revisions of FindBugs plug-ins that we have used to test Keshmesh).
    1. findbugs
    2. findBugsEclipsePlugin (edu.umd.cs.findbugs.plugin.eclipse)

Patch the dependencies of Keshmesh

  1. Apply the patch at patches/findbugs.patch on the findbugs project.
  2. Apply the patch at patches/findBugsEclipsePlugin.patch on the findBugsEclipsePlugin project.

Follow the instructions below to apply a patch on an Eclipse project:

  1. Right-click on the Eclipse project that you want to patch.
  2. Open the wizard at Team > Apply Patch....
  3. Follow the instructions on the wizard to select and apply the patch file on the selected Eclipse project.

Import Keshmesh projects into Eclipse

  1. Import all of the projects checked out from the Keshmesh git repository into your Eclipse workspace.
  2. At this point, there should not be any errors in your workspace except the following insignificant problem in org.eclipse.jdt.ui.tests and org.eclipse.text.tests:
Build path specifies execution environment J2SE-1.4. There are no JREs installed in the workspace that are strictly compatible with this environment.

Coding conventions

  1. Make sure you put the names of authors on every new class you add to the project.

  2. Do not commit any third party code unless we know that its license is compatible with that of Keshmesh.

  3. Make sure the following license header is the at the beginning of every file you add to the project.

     /**
  * This file is licensed under the University of Illinois/NCSA Open Source License. See LICENSE.TXT for details.
  */

Hint: If you import the code templates for Keshmesh into your Eclipse, Eclipse will be able to automatically generate the license headers for new Java classes. Import the code templates for Keshmesh from "coding-conventions/codetemplates.xml" into Eclipse by invoking "Window > Preferences > Java > Code Style > Code Templates > Import...". If you import the code templates of Keshmesh and select the "Generate comments" check box on the "New Java Class" wizard, Eclipse will automatically generate the license headers for new Java classes.

  1. Try to commit small chunks of code because they are easier to understand.
  2. If a commit is related to an issue, refer to the issue number in the commit message, and add the SHA of the commit into the issue as a comment.
  3. The format of the commit message should look like this:
Short summary of commit (<= 72 characters)

Leave a complete line between the short summary and this paragraph. The short summary should not have any leading or trailing whitespace. In this paragraph, you can write whatever else is needed to describe what was done and the rationale for the change. You should not wrap this paragraph and any other paragraphs that follow.

If there is an associated issue, please say something like "This commit belongs to issue #xxx" as the last line of your commit message. Having "issue #xxx" somewhere on that line is sufficient.

The format of commit messages is enforced by the script at coding-conventions/commit-msg. To enable this script, please copy coding-conventions/commit-msg into .git/hooks/commit-msg.

  1. The paths in the Git repository should not be too long.

On Windows, there is a limit (255) on the number of characters that a file can have. We exceeded that limit before in CodingSpectator and that caused problems for our developers who were using windows (see CodingSpectator's issue #182). So Nick Chen has made a script to enforce the limit on the path length. This script is based on the sample script in .git/hook/pre-commit which also uses tr to check for non-ASCII characters.

To install the pre-commit script, copy coding-conventions/pre-commit to .git/hooks/pre-commit.

Right now the script checks that the file name does not exceed 200 characters. This is a workflow showing what to do when something goes wrong:

# Will fail the check
$ git commit 
Error: Attempting to commit a file that is longer than 200 characters.

Loremipsumdolorsitamet,consecteturadipiscingelit.Sedaliquam,felisaccondimentumpretium,turpisnuncsemperturpis,egetconguearcuduisitametturpis.Mauristempusbibendumlacusutsollicitudin.Aliquameratvolutpat.Innuncmimetus
has 213 characters.

# Need to reset that file from the index
$ git reset HEAD Loremipsumdolorsitamet,consecteturadipiscingelit.Sedaliquam,felisaccondimentumpretium,turpisnuncsemperturpis,egetconguearcuduisitametturpis.Mauristempusbibendumlacusutsollicitudin.Aliquameratvolutpat.Innuncmimetus

# Rename the offensive file
$ mv Loremipsumdolorsitamet,consecteturadipiscingelit.Sedaliquam,felisaccondimentumpretium,turpisnuncsemperturpis,egetconguearcuduisitametturpis.Mauristempusbibendumlacusutsollicitudin.Aliquameratvolutpat.Innuncmimetus shortName

# Add it to the index again
$ git add shortName
Add a custom footer
Add a custom sidebar
Clone this wiki locally