Revision as of 12:39, 6 December 2011

Development IDE Configuration

Skalli has Java 5 as a minimum requirement. It is recommended to use the latest Eclipse release. The classic edition is sufficient for developing Skalli, but we recommend the JavaEE edition due to its JSP support. As Skalli source code is hosted in Git, it is recommended to install and use the EGit plugin (shipped with Eclipse since release 3.7/Indigo), too.

Obtaining Sources

Skalli is hosted in Git. You can browse the repository in gitweb, or retrieve the source code with

git clone git://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git

Of course, you might use the Git client shipped with Eclipse ("EGit") for that, too. If Git's own protocol is blocked by your firewall, use HTTP protocol instead:

git clone http://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git

Note, in Skalli we use Unix line delimiters (LF) by default. If you are working on Windows and want to contribute, please read the following section about our line delimiter conventions carefully before cloning the Skalli repository.

Import all projects into your workspace: Import > Git > Projects from Git. Select your cloned repository and continue with Next > Import Existing Projects. Select all projects and start the import with Finish. All Skalli projects are plain bundle projects and have checked in .project and .classpath files.

Line Delimiter Conventions

All Skalli files should use LF as line delimiters (Unix style), since merging files with mixed line delimiters in Git can be a real nightmare!

With the Git property core.autocrlf one can define, which line delimiter conversions Git should apply when checking out or commiting text files. Sounds great in theory, but works not so well in practise. At least if you are using Windows, and especially Egit on Windows.

For a detailed explanation of core.autocrlf compare the book Pro Git, chapter Git Configuration, or check the Git man pages. Note, you can always use git config --get core.autocrlf to find out your settings.

Recommendations for Windows Users

We strongly recommend to set core.autocrlf=false for the time being if you use EGit: core.autocrlf simply is not supported yet by EGit, so that you inevitably will end up with CRLF line delimiters in your commits all the time. The situation is slightly better if you are using a Git shell, but keep reading!

Using core.autocrlf=false, unfortunately, is not fail safe either! First of all, ensure that your Eclipse is configured to use Unix line delimiters (see Preferences > General > Workspace > New text file line delimiter). This will ensure LF line delimiters for most of your text files, e.g. for Java source files, but not for all of them. For example, when creating a new plugin project, the PDE editor insists on creating the .project and build.properties files with CRLF line delimiters. In such a case, please manually convert the line delimiters with File > Convert Line Delimiters To to Unix style before committing.

Please take care that all contributed changes contain only LF line delimiters!

Recommendations for MAC/UNIX Users

Use core.autocrlf=input. This should ensure that source files in the local working directory use native line endings and that committed sources contain only LF.

Building Skalli in Eclipse

After you cloned Skalli from the Git repository and imported all projects you should see a couple of build errors. This is normal, since third-party dependencies will not be resolved unless you specify a target platform.

Open org.eclipse.skalli.target/skalli.target with the Eclipse target editor. Wait a moment until all locations are resolved. Since the target platform contains some bundles from the Eclipse distribution and a complete Jetty runtime, it may take some time.

Click the link "Set as Target Platform" in the upper right corner of the editor. This will rebuild all projects in the workspace. Now all Skalli bundles should compile successfully. If not, try a clean build: Project > Clean....

Running Skalli in Eclipse

Skalli provides pre-configured launch configurations in the bundle org.eclipse.skalli.target:

• skalli.launch this is the launch configuration you want to use in most cases.
• skalli-nobootdelegation.launch is configured with osgi.compatibility.bootdelegation=false to detect missing imports statements for javax.* packages. Equinox and other OSGi containers behave slightly different in the handling of javax.* packages (see Equinox Box Delegation). Note, however that due to a bug in org.apache.taglibs.standard.glassfish Jetty cannot compile our JSP pages with this option set. You have to either patch org.apache.taglibs.standard.glassfish (adding the missing imports javax.xml.parsers, org.xml.sax and org.xml.sax.helpers to the bundle's manifest), or wait for glassfish to fix the problem.

Both launch configurations are using Equinox as OSGi container and Jetty as web container implementation. Required Jetty configuration files are provided in the folder org.eclipse.skalli.target/jetty/etc. Log files will be stored in jetty/logs.

The Jetty working directory is expected to be in org.eclipse.skalli.target/workdir. Skalli stores project data, customization information etc. in subdirectories of workdir/storage. By default, you will find some example projects in workdir/storage/Project.

http://localhost:8080 should present the Skalli login screen. The default user configured is "admin", password "admin". This user has administrative rights and is able to edit all projects and configure the instance. Click on All Projects to get an overview about the example projects provided with the source code.

Building Skalli with Maven/Tycho

Skalli can be built with Maven/Tycho release 3.0.3 or above. Dependency resolution is based on the same target definition as for the PDE-based build in Eclipse. Simply run mvn clean install on the root directory of the Skalli project tree.

Currently Skalli exports the following features:

org.eclipse.skalli.feature
org.eclipse.skalli.orbit.feature
org.eclipse.skalli.source.feature
org.eclipse.skalli.testing.feature

Only the first two are required at runtime. The corresponding P2 update site can be found in org.eclipse.skalli.site/target/site after a successful Maven build. Finally, org.eclipse.skalli.product provides a ready-to-run Skalli installation (running on Equinox/Jetty).

We maintain an integration build at Eclipse, where the latest build artifacts can be downloaded from.

Run Tests

TODO: explain how to run tests in Eclipse, using Maven. Meanwhile use:

$ mvn clean install 

Run Gerrit Tests

From Command Line

Gerrit module is extracted into a separate profile and thus is not a part of the reactor build. To run the tests you need to specify the profile:

$ mvn clean install -P gerrit

But before you need to update the POM file in org.eclipse.skalli.gerrit.test project, namely you need to replace the placeholders for the connection parameters in build > plugins > plugin > configuration:

 <systemProperties>
     <testHost><!-- enter your host --></testHost>
     <testAdminAccount><!-- enter your account --></testAdminAccount>
     <testPort><!-- enter the port --></testPort>
     <testPrivatekeyFile><!-- enter the url of the private key file --></testPrivatekeyFile>
     <testPassphrase><!-- enter the passphrase --></testPassphrase>
 </systemProperties>

Within Eclipse

To run Gerrit tests within Eclipse use /org.eclipse.skalli.gerrit.test/org.eclipse.skalli.gerrit.test.launch. Again, you need to modify it first by adding the connection parameters as VM arguments, e.g.:

Contributing Patches

Contributors a welcome to provide patches according to the Eclipse Committer Due Diligence Guidelines. In short: Create an issue on bugs.eclipse.org, create a patch (please use git format-patch whenever possible because that makes it easier for us to integrate patches), and attach it to the bug entry. Make sure to follow the guidelines set forth below.

General Guidelines

• Make small commits, as small as reasonable. This makes them easy to review.
• Each commit should have a commit message (see details below) that explains very clearly what the commit sets out to achieve.
• The scope of a commit should be clear and easy to understand for others. Do not put different features/bug fixes/ideas into one and the same commit!
• Split larger features into multiple commits if that makes them easier to understand. Create an issue in bugs.eclipse.org/skalli to track the parts.
• Provide tests for your new features/bug fixes.
• Format your source code according to the formatting standards of the project prior to committing or providing a patch. All bundles come with project-specific formatter settings. Apply them!
• Use Unix Line Endings (LF). Do not use Windows line endings (CRLF) or others!

Commit Message Guidelines

• The commit message header should fit on one line and should start with an uppercase letter
• The commit message have newline characters after every 60-70 characters.
• If a Gerrit Change-Id is available (for example when re-submitting to the same change), it should be added in the format below
• If there is an associated bug number in Bugzilla about it, it should come right before Gerrit's Change-Id entry (if available) or towards the end.
• A "Signed-off-by" should be added to the end of the commit message (see example below).
• The first sentence should be a clear and concise description about the change.
• Enter a newline before providing a more detailed description about the change.

Fix the commit dialog to respect the workbench's selection

Originally, the commit dialog would automatically check off all
files in the dialog. This behavior contradicts a user's expectation
because their selection in the workbench is completely ignored. The
code has been corrected to only preselect what the user has actually
selected.

Bug: 12345
Change-Id: I71ac4844ab9d2f848352eba9252090c586b4146a
Signed-off-by: Your Name <your.email@example.org>

Website

The Skalli website is located in a CVS repository on the Eclipse Foundation's servers.

• File > Import > CVS > Projects from CVS
• Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/org.eclipse
• Use module skalli (from www)
• Finish