Contributing to Infinispan

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

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:

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.

Maven supports generating IDE configuration files for easy setup of a project. This is tested on Eclipse, IntelliJ IDEA and Netbeans.

Infinispan uses TeamCity for continuous integration. TeamCity polls GitHub for updates and runs whenever updates are available. You can check the status of the latest builds here .

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

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.

A contributor will only ever submit patches via GitHub’s pull request mechanism.

Contributors should always fork the upstream project on GitHub and work off a clone of this fork.

Project Admins have a very limited role. Only Project Admins are allowed to push to upstream, and Project Admins never write any code directly on the upstream repository. All Project Admins do is pull in and merge changes from contributors (even if the "contributor" happens to be themselves) into upstream, perform code reviews and either commit or reject such changes.

This approach ensures Infinispan maintains quality on the main code source tree, and allows for important code reviews to take place again ensuring quality. Further, it ensures clean and easily traceable code history and makes sure that more than one person knows about the changes being performed.

Infinispan has several main release branches. These are master (ongoing work on the current unstable release), and maintenance branches for previous minor releases (e.g., 5.0.x, 4.2.x, 4.1.x). Work should never be committed directly to any of these release branches directly; topic branches should always be used for work, and these topic branches should be merged in using the process outlined above.

Some of the biggest features of git are speed and efficiency of branching, and accuracy of merging. As a result, best practices involve making frequent use of branches. Creating several topic branches a day, even, should not be considered excessive, and working on several topic branches simultaneously again should be commonplace.

Chapter 3, Section 4 of Pro Git has a detailed discussion of topic branches. For Infinispan, it makes sense to create a topic branch and name it after the JIRA it corresponds to. (if it doesn’t correspond to a JIRA, a simple but descriptive name should be used).

It is extremely important that comments for each commit are clear and follow certain conventions. This allows for proper parsing of logs by git tools. Read this article on how to format comments for git and adhere to them. Further to the recommendations in the article, the short summary of the commit message should be in the following format:

This can optionally be followed by a detailed explanation of the commit. Why it was done, how much of it was completed, etc. You may wish to express this as a list, for example:

Make sure however to split separate concerns - especially if they are unrelated - in separate commits.

Sometimes work on your topic branch may include several commits. For example, committing a test. Then committing another test. Then perhaps committing a fix. And perhaps fixing your own fix in the next commit…​ Before issuing a pull request for this topic branch, consider cleaning up these commits. Interactive rebasing helps you squash several commits into a single commit, which is often more coherent to deal with for others merging in your work. Chapter 6, Section 4 of Pro Git has details on how to squash commits and generally, clean up a series of commits before sharing this work with others. Note that you can also easily reorder them, just change the order of lines during the interactive rebase process.

Also, it is important to make sure you don’t accidentally commit files for which no real changes have happened, but rather, whitespace has been modified. This often happens with some IDEs. git diff --check should be run before you issue such a pull request, which will check for such "noise" commits and warn you accordingly. Such files should be reverted and not be committed to the branch.

Adhering to Infinispan’s code style guidelines will help minimise "noise" commits. Project Admins are going to ask contributors to reformat their code if necessary.

If you have a clone of the upstream, you may want to update it from time to time. Running:

will often do the trick. You could then pull the specific branches you would need to update:

If you have a fork of upstream, you should probably define upstream as one of your remotes:

You should now be able to fetch and pull changes from upstream into your local repository, though you should make sure you have no uncommitted changes. (You do use topic branches, right?)

Save this script as ~/.git-completion.bash and in ~/.bash_profile, add the following on one line:

After logging out and back in again, typing git followed by TAB will give you a list of git commands, as would git c followed by TAB, etc. This even works for options, e.g. git commit -- followed by TAB. The completions are even aware of your refs, so even git checkout my_br followed by TAB will complete to git checkout my_branch!

Add the following to your ~/.gitconfig

Some git commands are pretty long to type, especially with various switches. Aliases help you to map shortcuts to more complex commands. Again, For example, add the following to ~/.gitconfig:

Git ships with gitk, a GUI that visually represents a log. If you use Mac OS X, GitX is a good alternative. Try typing gitk or gitx in a git project directory. For Linux users, there are lots of alternatives: gitk , gitg , giggle, …​ up to egit for Eclipse.

There are several options available, including KDiff3, meld and Perforce’s P4Merge which are all either open source or available for free. See this link on setting these up (section under External Merge and Diff Tools)

You can customise the editor used by git editing ~/.gitconfig. The following fires up MacVIM instead of the default vi editor:

Alternatively, you could fire up TextMate or another editors of your choice.

You can change your bash shell prompt to print the current repository’s branch name. Add the following to your ~/.bashrc

The resulting shell prompt will look like:

If you’re a zsh user, you can get even more interesting branch information thanks to this blog post , such as:

For example, the following prompt indicates that the current branch is 't_ispn775_master' and that it is behind remote:

To be able to publish releases to Maven, you need to have the following in your settings.xml file:

Infinispan currently has 2 separate Maven archetypes you can use to create a skeleton project and get started using Infinispan. This is an easy way to get started using Infinispan as the archetype generates sample code, a sample Maven pom.xml with necessary dependencies, etc.

You don’t need to have any experience with or knowledge of Maven’s Archetypes to use this!  Just follow the simple steps below.

A single test can be executed using the test property. The value is the short name (not the fully qualified package name) of the test. For example:

Alternatively, if there is more than one test with a given classname in your test suite, you could provide the path to the test.

Patterns are also supported:

Also, you can always pass your own Log4j configuration file via -Dlog4.configuration with your own logging settings.

It is sometimes desirable to install the Infinispan package in your local repository without performing a full test run. To do this, simply use the skipTests property:

Note that you should never use -Dmaven.test.skip=true since modules' test classes depend on other module test classes, and this will cause compilation errors.

If you want to execute tests relying on TestNG’s @Parameters from an IDE (such as Eclipse or IntelliJ IDEA), please read this blog entry .

When you run tests, you can get TRACE logging via using the traceTests profile

ecuting this will generate a GZIP file called trace-infinispan.log.gz. This file is not fully closed, so to extract the log file, execute:

When you run tests, you can enable code coverage recorder for calculating and analysing the Infinispan code coverage. You can do this using coverage and jacocoReport profiles. As a code coverage evaluation tool, the JaCoCo is used.

Please note, that -Dmaven.test.failure.ignore=true is used for generating JaCoCo code coverage report, even if there are test failures.

Executing this will generate jacoco.exec file in each module’s target/ directory. These are the JaCoCo execution data files, which contain full data about the specific module’s coverage.

As soon as the coverage execution command is finished, you will need to generate the JaCoCo report, which will merge the generated jacoco.exec files as well as will create the code coverage report.

For having the report in place, run the following command from your Infinispan home directory:

The jacoco-html/ directory will be generated in Infinispan Home directory, which will contain the code coverage report.

The following test groups are used by Infinispan.

Every test (except those not intended to be run by continuous integration) should at least be in the functional or unit groups, since these are the default test groups executed by Maven, and are run when preparing a release.

Sometimes you want to run a test using settings other than the defaults (such as UDP for jgroups group tests or the EmbeddedTransactionManager for transaction group tests). This can be achieved by referring to the Maven POM file to figure out which system properties are passed in to the test when doing something different. For example to run a jgroups group test in your IDE using TCP instead of the default UDP, set -Dinfinispan.test.jgroups.protocol=tcp. Or, to use JBoss JTA (Arjuna TM) instead of the EmbeddedTransactionManager in a transaction group test, set -Dinfinispan.test.jta.tm=jbosstm. Please refer to the POM file for more properties and permutations.

There are a number of constraints and best practices that need to be followed in order to ensure correctness and keep the execution time to a minimum. If you follow these guidelines you will find your tests are more reliable:

AsciiDoctor has some excellent resources on authoring documentation effectively, including:

You will want to install the entire AsciiDoctor toolchain on your computer.

In order to see the result of your editing, from the infinispan’s root dir (embedded):

A soft limit of 80 characters is recommended. At the end of each sentence, go to the next line. Consider going to the next line for each new clause, in particular if the sentence would go beyond 80 characters. But do not obsess: if a multi-clause sentence is below 80 characters, don’t split it to limit the verticality of the document. For long links, tend to go to the next line.

The 80 characters limit is used because GitHub diffs are around 90 chars long.

For more information, read this blog post

If you intend your file to be included in another file (aggregated), such as the technique used in the User Guide, then you must end the file with two blank lines.

As far as possible, use OmniGraffle for diagrams. Please store diagram sources if possible as well, XML files in src/main/omnigraffle. Export the omnigraffle files as png with a dot per inch of 72. This will create a file of the right size for the web.

Binary images should be stored under documentation/src/main/asciidoc/${your_document}/images

Naturally, while editing the docs, you don’t want to have to build the entire docs to see your changes. A good way to do this is to set up live previews as described here.

Official documentation - a User Guide, Getting Started Guide, FAQs, guides to contributing, extending and upgrading Infinispan - live in Infinispan’s source code repository on GitHub.

Additional documentation - such as for cache stores, Hot Rod clients and modules that live outside of Infinispan’s core repository - live alongside the code in their respective repositories following a similar structure.

In addition, Infinispan maintains a wiki for design documents and the like, on this site.

Each book has its own structure. Longer books such as the User Guide and the Getting Started Guide may have a table of contents, while shorter books like the guide to extending or upgrading Infinispan may skip this.

If you are describing the use of a GUI, or showing results of some operation, images embedded in the page can bring the documentation to life for the reader. Images can be included via the image::[] directive.

See this section for details on where to store your images.

CodeRay is used for image highlighting. Visit the CodeRay site for a list of supported languages. Highlighting code is as simple as:

If you are writing about a feature that has existed from Infinispan 5.0 onwards, there is no need to specify a version that the feature existed from. However, if you are writing about a new feature, use a TIP callout to specify the version it applies to. Also, only specify a MINOR version rather than a detailed version.

Why is this bad? A number of reasons.

How should this be written?

Please stay away from colloquialisms at all cost. This impacts the professionalism and readability of the documentation. The examples below probably need no explanation.