diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index f1447b2176..8dab9e13a5 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -18,11 +18,14 @@ 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; + . 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]) + . 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! @@ -46,14 +49,23 @@ The core code of Ehcache is split in three modules: === 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`. +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.internal.service.ServiceLocator` facility to locate `Service` instances, which it then in turn life cycles. +`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.internal.service.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 (note: currently it only creates `OnHeapStore`, as this is the only topology supported... more to come). +`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+ +`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]. +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].