Skip to content

Contributing to CodingSpectator

Jump to bottom
Mohsen Vakilian edited this page Mar 29, 2014 · 40 revisions

Compiling CodingSpectator in Eclipse

  1. Install Eclipse for RCP and RAP Developers. The version of Eclipse should match the version of Eclipse that you want to build CodingSpectator for. For instance, if you want to build CodingSpectator for Eclipse Helios, install Eclipse Helios. If you want to build CodingSpectator for Eclipse Indigo, install Eclipse Indigo. Finally, if you want to install Eclipse for Eclipse Indigo SR1, install Eclipse Indigo SR1.
  2. Get the source code from git@github.com:vazexqi/CodingSpectator.git and checkout to the branch you want to contribute to.
  3. Execute the following two commands to get the git submodules:
  • git submodule init
  • git submodule update
  1. The test plug-ins depend on SWTBot. So, if you are importing the test plug-ins, you have to install SWTBot on your Eclipse. We have successfully built CodingSpectator with SWTBot 2.1.1.
  2. Import the Eclipse projects in folders submodules and plug-ins/common of the git repository into your Eclipse workspace.
  3. Import the Eclipse projects in folder plug-ins of the git repository that match the version of your running Eclipse. This folder contains multiple copies of some of the plug-ins for supporting different releases (e.g. Helios, Indigo, and Indigo SR1) of Eclipse (e.g. plug-ins/helios, plug-ins/indigo, and plug-ins/indigo-sr1). Your workspace should contain plug-ins specific to a single release of Eclipse, namely the ones for your running version of Eclipse. For instance, if you are running Eclipse Indigo SR1, import all the projects in folder plug-ins/indigo-sr1.

Coding Conventions

  1. Set the default coding style of your Eclipse workspace to JDT UI Code Style Conventions.

  2. Put the names of authors on every class.

  3. Don't commit any third party code unless we know that its license is compatible with ours.

  4. Add the following license header at the top of every file.

     /**
  * 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 CodingSpectator into your Eclipse, Eclipse will be able to automatically generate the license headers for new Java classes. Import the code templates for CodingSpectator from "coding-conventions/codetemplates.xml" into Eclipse by invoking "Window > Preferences > Java > Code Style > Code Templates > Import...". Having imported the code templates of CodingSpectator, Eclipse will automatically generate the license headers for new Java classes if you select the "Generate comments" check box on the "New Java Class" wizard.

  1. Try to commit small chunks of code just because they are easier to understand.
  2. If a commit resolves an issue, refer to the issue in the commit message. GitHub automatically lists the SHA of the commit in the issue.
  3. The first line of the commit message should fit into 72 characters. This is because most git based tool show only the first 72 characters when previewing the commit.

Modifying Eclipse Plugins

Ideally, we'd like to be able to tell all the changes that we've made to a file quickly. That is we don't want to have to diff various versions of the file in the repository. The following set of conventions ensure that we can easily see a list of files that we have changed and see the changes in each file by searching keywords such as CODINGSPECTATOR.

  1. If you add a Java file to a third-party code base, put it in a package whose name ends with .codingspectator, e.g. org.eclipse.jdt.internal.corext.refactoring.codingspectator.

  2. If you want to modify a file from a third-party code base, first reformat the file and commit it. This makes it easier for us to see our changes to the original version of the code. You can use git stash to help you in this process. Basically, you stash your changes just before you commit, reformat the files that you've changed, make the reformatting a separate commit, then apply the stash and commit your changes.

  3. Add the following lines to the end of the default header javadoc.

     /**
  *
  * .... Eclipse default javadoc
  *
  * @author <name> - <what was changed>
  */

  4. Also create a file called FilesChangedForCodingSpectator.txt (if it does not exist) at the top-level. Put the name of the file that you have modified. This makes it easier for us to track which files we have changed. The file FilesChangedForCodingSpectator.txt should have two sections and look like the following.

     Changed Files
 =============

 <List of files that we've changed, one file per line>

 Added Files
 ===========

 <List of new files that we've added, one file per line>

  5. Mark every method that you change by a comment that begins with the tag CODINGSPECTATOR, e.g. //CODINSPECTATOR: Extracted getSimpleRefactoringDescriptor from createChange If you add a task tag called CODINGSPECTATOR to the "Preferences/Java/Compiler/Task Tags" page, Eclipse will highlight and list these tags for you.

  6. If you want to mark a section of the file as the changes you've made a file, separators the look like the following.

     /////////////////
 //CODINGSPECTATOR
 /////////////////

 ///////////////////////////////////////////////
 //CODINGSPECTATOR: Added the following methods.
 ///////////////////////////////////////////////

Anything that comes after the above markers is the code that we've added to the original file.

Running the JDT Refactoring JUnit tests (Optional)

Environment Variables

Before running the tests, set the environment variable TESTING_MODE to TRUE by editing the launch configuration options.

Plug-in Version Numbers

CodingSpectator changes some of the Eclipse plugins that come with Eclipse Helios. We have picked a specific data (5/20/2010), and checked out the latest versions of the required plugins up to that date.

CodingSpectator instruments the Eclipse refactoring tool to collect detailed usage data. If you want to ensure that these instrumentation of CodingSpectator don't break the functionality of the Eclipse refactoring tool, you need to run the JDT refactoring test. If you want to run the JDT refactoring tests, you need to check out the following plug-in:

  1. org.eclipse.jdt.ui.tests.refactoring (v20100520-0800)

The following two other plug-ins are also required. You need to check them out from CVS directly since they aren't packaged as part of the Eclipse distribution). Check them out from :pserver:dev.eclipse.org:/cvsroot/eclipse. Use the username "anonymous" (no password). Click on "Versions" and select the following plug-ins and the required version number.

  1. org.eclipse.jdt.ui.tests (v20100520-0800)
  2. org.eclipse.test.performance (v20100122)
  3. org.eclipse.text.tests (v20100520-0800)

Expected Problems

After checking out all the projects specified above for the Helios release and installing the required plug-ins the only errors that you should see in the "Problems" view of your workspace is the following.

Build path specifies execution environment J2SE-1.4. There are no JREs installed in the workspace that are strictly compatible with this environment.

Git Conventions

Commit messages

We will be following a modified version of the commit conventions suggested here. Basically 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 conventions are enforced by the commit-msg script at the CodingSpectator/coding-conventions folder. To enable this, please execute the following from the command line from the root directory of your local version of CodingSpectator:

  1. $cp coding-conventions/commit-msg .git/hooks/commit-msg
  2. $chmod +x .git/hooks/commit-msg

Commit file length

On Windows, there is a limit (255) on the number of characters that a file can have. We exceeded that limit before in our tests and that cause problems for our developers who were using windows (see #182). So we have made a script to check this now. This script is pretty basic and requires bash and it basic command. It was modified from the sample script in .git/hook/pre-commit which also uses tr to check for non-ASCII characters.

This is how to install the pre-commit script:

  1. $cp coding-conventions/pre-commit .git/hooks/pre-commit
  2. $chmod +x .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
Clone this wiki locally