=  The Basics
In this chapter we quickly walk through the basics on contributing; future chapters go into more depth.

== Pre-requisites
|=============
| Java 21   | {brandname} is built with Java 21 and requires Java {jdkminversion} for runtime (we build with OpenJDK)
| Maven {mavenminversion} | The {brandname} build uses Maven, and you should be using at least Maven {mavenminversion}
| Git       | The {brandname} source code is stored in Git.
|=============

== Java compatibility

{brandname} can run with Java {jdkminversion} or greater.

== Issue Management

{brandname} uses GitHub for issue management, hosted on link:https://github.com/infinispan/infinispan/issues[Infinispan Issues].

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

. Choose between
  * _Feature Request/Enhancement_ if you want to request an enhancement or new feature for {brandname}
  * _Bug Report_ if you have discovered an issue
. Provide the details requested in the issue forms. Please provide as much information as possible so that we can help you
. If the issue has been discussed on link:https://infinispan.zulipchat.com[Zulip] or the link:https://github.com/infinispan/infinispan/discussions[Discussions], please provide a link to the specific conversation.

== Version control
{brandname} uses link:http://git-scm.com[git], hosted on link:http://github.com[GitHub], for version control.
You can find the upstream git repository at link:https://github.com/infinispan[]. To clone the repository:

----
$ git clone git@github.com:infinispan/infinispan.git
----

or to clone your fork:

----
$ git clone git@github.com:YOUR_GITHB_USERNAME/infinispan.git
----

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

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

. Import the {brandname} maven project. Select File -> Import in your eclipse workbench. Select the Existing Maven Project importer.
+
image::import_maven1.png[]

. Select the root directory of your {brandname} checkout.
+
image::import_maven2.png[]

. Select {brandname} modules that you want to import.

. Finally, from {brandname} 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:

..  Open the properties for infinispan-core and locate Annotation Processing

..  Tick Enable project specific settings

..  Enter `target/generated-sources/annotations` as the `Generated source` directory
+
image::ann_proc_eclipse.png[]

. Code Formatting. From the menu Window -> Preferences -> Java -> Code Style -> Formatter. Import link:https://raw.github.com/infinispan/infinispan/main/ide-settings/eclipse/formatter.xml[formatter.xml]

. Code templates. From the menu Window -> Preferences -> Java -> Code Style -> Code Templates. Import link:https://raw.github.com/infinispan/infinispan/main/ide-settings/eclipse/codetemplates.xml[codetemplates.xml]

==== IntelliJ IDEA
===== Importing

When you start link:http://www.jetbrains.com/idea/[IntelliJ IDEA], you will be greeted by a screen as shown below:

image::idea-12-import.jpg[]

If you have already obtained a copy of the {brandname} sources via Github (see _'Source Control'_), then follow: _Import Project -> /directory/to/downloaded/sources_ .
IntelliJ will automatically make use of Maven to import the project since it will detect a `pom.xml` file in the base directory.

If you have not obtained the sources already, you can use the Git integration in IntelliJ IDEA 12. Click on _Check out from Version Control -> Github_.
After entering your Github credentials, you will then be prompted to enter the git repository URL along with the location that you want to check out the source code to.

image::idea-12-git.png[]

===== Compiler settings

From {brandname} 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.

image::idea-12-annotations.png[]

TIP: There can sometimes be issues with the generated logging classes on rebuild (particularly when you switch Git branches).
If these issues do crop up then simply run `mvn clean install -DskipTests` on the command line to clear them out.

TIP: If you are running a multi-core environment (e.g. quad-core or above) then you can follow the instructions on making use of parallelized compilation in IntelliJ 12. Information on how to do this can be found link:http://blogs.jetbrains.com/idea/2012/12/intellij-idea-12-compiler-twice-as-fast/[here] .

===== Code Style
Download the code style JAR file from link:https://github.com/infinispan/infinispan/blob/main/ide-settings/intellij/IntelliJ_IDEA_Code_Style.jar?raw=true[here] and import this into IntelliJ IDEA.

== Builds
{brandname} uses link:http://maven.apache.org/[Maven] for builds. Make sure you have Maven {mavenminversion} installed, and properly configured.

=== Continuous Integration
{brandname} uses link:http://www.jetbrains.com/teamcity[TeamCity] for continuous integration.
TeamCity polls GitHub for updates and runs whenever updates are available.
You can check the status of the latest builds link:http://ci.infinispan.org/overview.html[here] .

== Testing
{brandname} uses link:http://testng.org/doc/index.html[TestNG] for unit and functional tests, and all {brandname} tests are run in parallel.
For more information see the chapter on the test suite; this chapter gives advice on writing tests which can safely execute in parallel.

== Communicating with other {brandname} contributors
{brandname} contributors use a mix of technologies to communicate.
Visit link:http://infinispan.org/community/[this page] to learn more.

== Style Requirements
{brandname} uses the link:http://en.wikipedia.org/wiki/Indent_style#K.26R_style[K&amp;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 link:http://en.wikipedia.org/wiki/Newline[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 link:https://github.com/infinispan/infinispan/blob/main/ide-settings/[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.

=== Check-in comments

Please ensure any commit comments use link:#check_in_comments[this format] if related to an issue.
If your comment does not follow this format, your commit may not be merged into upstream.

== Logging
{brandname} follows the JBoss logging standards, which can be found link:https://community.jboss.org/wiki/LoggingStandards[here] .

From {brandname} 5.0 onwards, {brandname} uses JBoss Logging to abstract over the logging backend.
{brandname} supports localization of log message for categories of INFO or above as explained in link:https://docs.jboss.org/process-guide/en/html/logging.html[the JBoss Logging guidelines] .
As a developer, this means that for each INFO, WARN, ERROR and 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:

[source,java]
----

@LogMessage(level = INFO)
@Message(value = "An informative message: %s - %s", id = 600)
void fiveTransactionsHaveCompleted(String param1, String param2);

----


And then, instead of calling `log.info(...)`, you call the method, for example `log.fiveTransactionsHaveCompleted(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:


[source,java]
----

@LogMessage(level = ERROR)
@Message(value = "An error message: %s", id = 600)
void anErrorMessage(String param1, @Cause IllegalStateException e);

----


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:

[options="header"]
|===============
|Module name|Id range
|core|1 - 900
|commons|901-2000
|[unused, was tree]|2001 - 3000
|[unused, was 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
|[unused, was jdbm cache store]|9001 - 10000
|remote cache store|10001 - 11000
|server memcached|11001 - 12000
|server rest|12001 - 13000
|server resp|13001 - 14000
|query|14001 - 15000, 28501 - 29000
|server router|15001 - 16000
|clustered locks|16001 - 17000
|cdi integration|17001 - 18000
|hbase cache store|18001 - 19000
|jcache|19001 - 20000
|[unused, was cli client]|20001 - 21000
|mongodb cache store|21001 - 22000
|rest cache store|22001 - 23000
|rocksdb cache store|23001 - 24000
|couchbase cache store|24001 - 25000
|redis cache store|25001 - 26000
|[unused, was extended statistics]|25001 - 26000
|[unused, was directory provider]|26001 - 27000
|tasks|27001 - 27500
|scripting|27501 - 28000
|remote query server|28001 - 28500
|soft-index file store|29001 - 29500
|clustered counter|29501 - 30000
|anchored keys|30001-30500
|insights|32001 - 32500
|server|80000-81000
|===============

NOTE: When editing the above table, remember to update the README-i18n.txt file in the project sources!

NOTE: You will need to enable annotation processing in order to be able to compile {brandname} and have the logger implementation generated.
