Deprecation

This document is DEPRECATED.

Please consider any information here as out of date. DO NOT use this document.

Instead, refer to http://infinispan.org/documentation.

Please update your bookmarks accordingly.

Skip to end of metadata
Go to start of metadata
In this chapter we quickly walk through the basics on contributing; future chapters go into more depth.

Pre-requisites

Java 1.6 Infinispan is baselined on Java 6.0, and is built and tested using Sun Java 6.0.
Maven 3 The Infinispan build uses Maven, and we recommend using Maven 3.
Git (optional) The Infinispan sources are stored in Git. If you don't wish to install Git, you can download source bundles

Issue Management - JIRA

Infinispan uses JIRA for issue management, hosted on issues.jboss.org. You can log in using your normal jboss.org username and password.

If you need to create a new issue then follow these steps.

  1. Choose between
    • Feature Request if you want to request an enhancement or new feature for Infinispan
    • Bug if you have discovered an issue
    • Task if you wish to request a documentation, sample or process (e.g. build system) enhancement or issue
  2. Then enter a Summary, describing briefly the problem - please try to be descriptive!
  3. You should not set Priority.
  4. Now, enter the version you are reporting an issue against in the Affects Version field, and leave the Fix Version field blank.
  5. In the Environment text area, describe in as much detail as possible your environment (e.g. Java runtime and version, operating system, any network topology which is relevant).
  6. In the Description field enter a detailed description of your problem or request.
  7. If the issue has been discussed on the forums or the mailing list, enter a reference in the Forum Reference field
  8. Finally, hit Create

Versioning Guidelines

Only Infinispan contributors should set the Fix Version field.

When setting the Fix Version field for bugs and issues in JIRA, the following guidelines apply:

Version numbers are defined as MAJOR.MINOR.MICRO.MODIFIER. For example, 4.1.0.BETA1 would be:

MAJOR 4
MINOR 1
MICRO 0
MODIFIER BETA1

If the issue relates to a Task or Feature Request, please ensure that the .FINAL version is included in the Fixed In field. For example, a new feature should contain 4.1.0.BETA1, 4.1.0.FINAL if it is new for 4.1.0 and was first made public in BETA1. For example, see ISPN-299.

If the issue relates to a bug which affected a previous FINAL version, then the Fixed In field should also contain the .FINAL version which contains the fix, in addition to any ALPHA, BETA or CR release. For example, see ISPN-546.
If the issue pertains to a bug in the current release, then the .FINAL version should not be in the Fixed In field. For example, a bug found in 4.1.0.ALPHA2 (but not in 4.1.0.ALPHA1) should be marked as fixed in 4.1.0.ALPHA3, but not in 4.1.0.FINAL. For example, see ISPN-416.

Source control - Git

Infinispan uses git, hosted on GitHub, for version control. You can find the upstream git repository at https://github.com/infinispan. To clone the repository:

or to clone your fork:

For more information, read the Git chapter.

Setting up your IDE

Maven supports generating IDE configuration files for easy setup of a project. Tested are Eclipse, IntelliJ IDEA and Netbeans.

Before we import the project, we need to clone the project as described above.

Eclipse

  1. Install the m2eclipse plugin if you have not already installed it. Eclipse is including it since version "Indigo" 3.7, for older versions follow instructions at http://eclipse.org/m2e/.
  2. Import the Infinispan maven project. Select File -> Import in your eclipse workbench. Select the Existing Maven Project importer.
  3. Select the root directory of your Infinispan checkout.
  4. Select Infinispan modules that you want to import.
  5. Finally, from Infinispan 5.0 onwards, annotation processing is used to allow log messages to be internationalized. This processing can be done directly from Eclipse as part of compilation but it requires some set up:
    1. Open the properties for infinispan-core and locate Annotation Processing
    2. Tick Enable project specific settings
    3. Enter target/generated-sources/annotations as the Generated source directory

Code Formatting. From the menu Window->Preferences-> select Java -> Code Style -> Formatter. Import formatter.xml
Code template. From the menu Window->Preferences-> select Java -> Code Style ->  Code Templates. Import codetemplates.xml

As some modules use Scala, it's worth installing the Scala tools.

IntelliJ IDEA

IntelliJ's built-in Maven support is the best way to go. From IntelliJ 9 onwards, this is a robust and reliable mechanism to import a project from Maven.

  1. Create a new project in IntelliJ

  1. And choose to import the project from an external model

  1. When asked, point the wizard to the directory created when you cloned the repository
  2. Make sure that the check-boxes for "Search for projects recursively" and "Create module groups for multi-module Maven projects" are checked.
  3. Just follow through the rest of the steps in the wizard and you're good to go.
  4. Finally, from Infinispan 5.0 onwards, annotation processing is used to allow log messages to be internationalized. This processing can be done directly from IntelliJ as part of compilation but it requires some set up:
  • Go to "Preferences/Compiler/Annotation Processor" and click on Enable annotation processing
  • Add an annotation processor with "Processor FQN Name" as org.jboss.logging.LoggingToolsProcessor
  • In "Processed Modules", add all modules except the root and the parent modules.

IntelliJ has built in Scala support, just make sure the Scala module is installed.

IntelliJ related code style jar is at idea-code-style.jar

Build - Maven

Infinispan uses Maven for builds. Make sure you have Maven 3 installed, and properly configured. For more information, read the Maven chapter.

Continuous Integration - Jenkins on Cloudbees

Infinispan uses Jenkins on Cloudbees for continuous integration. Jenkins polls GitHub for updates and runs whenever updates are available. For more information view the project site.

Testing - TestNG

Infinispan uses TestNG for unit and functional tests, and all Infinispan tests are run in parallel. For more information see the Test Suite chapter; this chapter gives advice on writing tests which can safely execute in parallel.

Communicating with other Infinispan contributors

Infinispan contributors use a mix of mailings lists and IRC to communicate ideas and designs, with more detailed designs often making their way into wiki pages.

Style Requirements

Infinispan uses the K&R code style for all Java source files, with two exceptions:

  • use 3 spaces instead of a tab character for indentations.
  • braces start on the same line for class, interface and method declarations as well as code blocks.

In addition, sure all new line characters used must be LF (UNIX style line feeds). Most good IDEs allow you to set this, regardless of operating system used.

All patches or code committed must adhere to this style. Code style settings which can be imported into IntelliJ IDEA and Eclipse are committed in the project sources, in ide-settings.

Spelling

Ensure correct spelling in code, comments, Javadocs, etc. (use American English spelling). It is recommended that you use a spellchecker plugin for your IDE.

License header

All source files must have up-to-date license headers as described in Copyright Ownership and Licenses. Never remove existing headers or copyrights.

Check-in comments

Please ensure any commit comments use this format if related to a task or issue in JIRA. This helps JIRA pick out these checkins and display them on the issue, making it very useful for back/forward porting fixes. If your comment does not follow this format, your commit may not be merged into upstream.

Configuration

Infinispan offers both programmatic configuration and XML configuration. For more information read the Configuration chapter.

Logging

From Infinispan 5.0 onwards, Infinispan uses JBoss Logging to abstract over the logging backend. Infinispan supports localization of log message for categories of INFO or above as explained in the JBoss Logging guidelines. As a developer, this means that for each INFO, WARN, ERROR, FATAL message your code emits, you need to modify the Log class in your module and add an explicit method for it with the right annotations. For example:

And then, instead of calling log.info(...), you call the method, for example log.anInformativeMessage(param1, param2). If what you're trying to log is an error or similar message and you want an exception to be logged as cause, simply use @Cause annotation, example:

The last thing to figure out is which id to give to the message. Each module that logs something in production code that could be internationalized has been given an id range, and so the messages should use an available id in the range for the module where the log call resides. Here are the id range assignments per module:

Module name Id range
core 1 - 1000
tree 1001 - 2000
bdbje cache store 2001 - 3000
cassandra cache store 3001 - 4000
hotrod client 4001 - 5000
server core 5001 - 6000
server hotrod 6001 - 7000
cloud cache store 7001 - 8000
jdbc cache store 8001 - 9000
jdbm cache store 9001 - 10000
remote cache store 10001 - 11000
server memcached 11001 - 12000
server rest 12001 - 13000
server websocket 13001 - 14000
query 14001 - 15000
lucene directory 15001 - 16000
rhq plugin 16001 - 17000
cdi integration 17001 - 18000
You will need to enable annotation processing in order to be able to compile Infinispan and have the logger implementation generated.
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.