= How to contribute?
// URIs
:uri-repo: https://github.com/ehcache/ehcache3
:uri-wiki: {uri-repo}/wiki
:uri-issues: {uri-repo}/issues
:uri-fork: {uri-repo}/fork
:uri-waffle: https://waffle.io/ehcache/ehcache3
:uri-dev-ml: https://groups.google.com/forum/#!forum/ehcache-dev
:uri-users-ml: https://groups.google.com/forum/#!forum/ehcache-users

== Reporting issues

 . Before opening an issue, drop us an email on the {uri-users-ml}[user mailing list] so we can chat about the problem first.
 . Based on the discussion and findings in the mail thread, you will be asked to provide all the relevant information to open an {uri-issues}[issue] in case you found a genuine bug.

== Fixing issues

On paper (or on this screen), it's pretty straight forward:

 . Join the {uri-dev-ml}[developer mailing list] and say hello! Or join us on irc #ehcache on freenode
 . Check the {uri-issues}[issues] and verify what you want isn't yet planned or could even already being worked on by someone;
   We're also using a board on {uri-waffle}[waffle.io], where work for the current milestone is prioritized;
 . If the task exists already and isn't assigned: drop us an email on the {uri-dev-ml}[developer mailing list] about it
   and we'll make sure we help you getting started and we'll assign the task/issue to you;
 . If we're talking about a larger task or feature, {uri-dev-ml}[drop us a message] first, and we'll see how to tackle it;
 . {uri-fork}[Fork] the project to your own repository and get started (you probably want to work on a dedicated branch);
 . Rebase your fork and do a pull request. We'll use that to code review it
   (see {uri-wiki}/dev.git[git usage page] as well as the {uri-wiki}/dev.guidelines[developer guidelines])
 . Be rich and famous!

Now, the doing the work part might be a little more challenging, and we don't provide any guarantees as to becoming rich... but you'll be famous to us!

== Contributor agreement

Please review the http://www.ehcache.org/community/contribute.html[contribute page] on the Ehcache website
and pay attention to requests on your pull requests.

== Code layout

The core code of Ehcache is split in three modules:

 . the {uri-wiki}/module.api[API module], which contains mainly interfaces. They are the core API to Ehcache (e.g. +Cache+, +CacheManager+) that users depend on. It also contains the entry points in terms of SPI (e.g. +Service+, +Store+, +AuthoritativeTier+ & +CachingTier+), that are used by other modules that in turn provide their implementations;
 . the {uri-wiki}/module.core[Core module], that is composed of the plumbery that wires the API used by users with the SPI implementations present in packaged modules; and
 . the {uri-wiki}/module.impl[Implementation module], containing the default implementation of +Cache+ and +CacheManager+, as well as implementations of core SPIs, such as +HeapResource+ that lets you create on-heap +Cache+ and +CachingTier+ instances.

= Fundamental concepts

== Modular approach

=== Services

A `CacheManager` manages `Cache` instances, but also `Service` instances that can be used by either `Cache` or other `Service` instances.
An example of `Service` being the `org.ehcache.core.spi.store.Store.Provider`, it's the `Service` the `CacheManager` will use to create the `Store` instance underlying your `Cache`.

`Service` instances are created using Java's https://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html[`java.util.ServiceLoader` service-provider loading facility].
It is used to locate all `org.ehcache.core.spi.service.ServiceFactory` implementations on the classpath.
These are in turn used to create `Service` instances. Each `CacheManager` uses its own `org.ehcache.core.spi.ServiceLocator` facility to locate `Service` instances, which it then in turn life cycles.

`Service` instances are configured by their own respective `ServiceConfiguration` at `Service.start()` invocation time.
`CacheManager` and its `Service` instances can then use these services.
In the case of the `org.ehcache.core.spi.store.Store.Provider` instance, it is being used by the `CacheManager` to create a `Store` to back a `Cache`.
Being a direct dependency of `Ehcache`, that `Service` interface is part of the core SPI.
It defines a `createStore()` method that will be invoked by the `CacheManager` at `Cache` creation time.
The `Store.Provider` implementation can introspect not only the `Store.Configuration` passed, but also all `ServiceConfiguration` instances associated with the `Cache` being created in order to decide what `Store` should be created.

== Configuration

`org.ehcache.config.CacheConfiguration`, `org.ehcache.spi.service.ServiceConfiguration`, `org.ehcache.xml.XmlConfiguration`

NOTE: For more information on how the configuration is parsed, resolved and services are then bootstrapped,
      please read the {uri-wiki}/design.bootstrapping#configuration[Bootstrapping design doc].
