Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Skalli/Contributor Guide

< Skalli
Revision as of 06:22, 13 October 2011 by Michael.ochmann.sap.com (Talk | contribs) (Remove download instructions for CustomField)

Development IDE Configuration

Skalli has Java 5.0 as a minimum requirement. It is recommended to use latest Eclipse release, classic edition is sufficient for development, but JavaEE edition is recommended due to JSP support. As Skalli source code is hosted in git, it is recommended to use EGit plugin too.

Note: As of 2011-05-10, Indigo release 3.7M7 is working well. Install EGit 0.12.1 from included software site at "Indigo - http://download.eclipse.org/releases/indigo".

Obtaining Sources

Skalli is hosted in Git. You can browse the repository in gitweb.

You can get the source code via git commandline tool

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

or cloning a repository using EGit from URI git://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git.

Skalli egit clone.png

As we don't know if you will work with Max, Unix or Windows we recommend to read chapter EOL properties carefully.

Clone from master branch and specify remote branch as origin/master.

Now import all projects into your workspace. Import > Git > Projects from Git > Select your cloned repo > Import existing projects > Select all projects > Finish. You will import 29 projects (as of 2011-04-26).

Skalli egit import projects.png


Note: there will be compile errors, as some patches are needed for successful compilation.

EOL properties

All skalli files should use LF = Unix mode!

The git property core.autocrlf defines CRLF <-> LF conversion rules for checkout and commit of text files. You can find a good explanation of this property in the book Pro Git. See the Git Configuration chapter and search for core.autocrlf.

You can use git config --get core.autocrlf to find out your settings.

EOL recommendation for Windows Users

You can use core.autocrlf=true ore core.autocrlf=false.

Using core.autocrlf=true should ensure that source files in the local working directory use CRLF line endings and committed sources contain only LF. You should be able to work with all Window Editors. If you use Eclipse and Egit there is a known bug 301775 when committing, and you will push CRLF by mistake.

If you decide to use core.autocrlf=false, Git does not perform any CRLF <-> LF conversion at all. You have to take care that all local done changes (new files, changes) contain only LF. In Eclipse you can set the new line delimiter to Unix via Preferences > General > Workspace > New Line file line delimiter , but that might not work for all files. Eg. when creation of a new pluginPorject the .project and build.prperties still have CRLF.

EOL recommendation for MAC/LINUX 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.

Howto: Make Skalli Build in Eclipse (as of 2011-10-13)

After you cloned Skalli from Git you should see a couple of build errors. Due to the ongoing IP process for Skalli, we are not allowed to provide all necessary 3rd-party libraries as part of our source code (or in Eclipse Orbit) yet. Therefore, you need to download the missing bundles by your own and copy them into the folder org.eclipse.skalli.target/target-platform-3rdparty so that the target platform resolver can find them.

1. Download Missing 3rd-Party Libraries

The following 3rd-party libraries are needed for Skalli:

org.restlet version="2.0.0.RC4"
org.restlet.ext.servlet version="2.0.0.RC4
org.restlet.ext.xstream version="2.0.0.RC4
org.codehaus.jettison.jettison version="1.2.0"
org.apache.lucene.lucene-core version="3.0.2"
org.apache.lucene.lucene-highlighter version="3.0.2"
org.apache.lucene.lucene-queries version="3.0.2"
com.thoughtworks.xstream version="1.3.1"
org.custommonkey.xmlunit version="1.2.0"
org.xmlpull version="1.1.4.c"
com.vaadin version="6.4.0"
osgi.enterprise version="4.2.0"
org.eclipse.gemini.jpa version="1.0.0.RC1"
org.eclipse.gemini.jpa.weaving version="1.0.0.RC1"
org.eclipse.gemini.dbaccess.derby version="1.0.0.M1-incubation"

Some of them are available as OSGi bundles already and can be downloaded directly from the vendor or Maven Central, respectively:

XStream, XMLUnit and XMLPull do not provide OSGi bundles, but you can use those from SpringSource:

For Lucene there are no suitable bundles available at SpringSource (only for older releases), but you can use those attached to Bug 346411:


2. Set the Target Platform

Open org.eclipse.skalli.target/skalli-for-eclipse.target in the Eclipse target editor. Wait a moment till 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 sucessfully.

Note: The skalli-for-tycho target platform is not yet useable for a Maven build, because the references to the above bundles cannot be resolved. In order to setup a Maven build you need to create a P2 update site with these bundles. We are going to contribute the missing bundles to the Eclipse Orbit project, but that may take some time until all CQs are filed and approved.

Run Skalli in Eclipse

Skalli provides preconfigured 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 RFC66-enabled web container implementation. Required Jetty configuration files are provided in the folder jetty/etc. Log files will be stored in jetty/logs.

The Jetty working directory is expected to be in org.eclipse.skalli.target/workdir. This directory contains only a README file by default. Skalli will store project data, customization etc. in the folder workdir/storage.

Jetty will run by default on port 8080. So start a browser to URL http://localhost:8080, and you should see a login dialog to authenticate. The default user configured is "admin", password "admin". Then you are able to create projects, edit projects, search projects etc. The created projects are stored as XML files in org.eclipse.skalli.target/workdir/storage/Project.

Build

Skalli builds run on build.eclipse.org via Hudson using

Hudson


TODO: mvn build actually does not work due to missing patches and a target definition using a location of type directory.


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 seperate 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.:

Launch config.gif

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 otheres!

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 behaviour 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

Back to the top