<commit_before>= Developer guidelines

:toc:

These are some things to consider when you add code to Ehcache, but certainly when you review a PR!

== General guidelines

Whenever you start working on an issue, you probably want to consider some, if not all, of the items below:

=== API changes

If you need to change the public API (this includes additions), you probably want to start with that first. An easy way to go about that, is to add or modify `GettingStarted` documentation to concretely expose how the API would be affected. You can do this on your branch, as a first commit, and already share it for review with a larger audience, e.g. on the mailing list or through a preliminary pull request.

=== Design 

Whether API is modified or not, you'll want to consider how you plan to go about implementing it all. There are a couple of specificities of the Ehcache internals that would need to be accounted for:

 . *`Service` additions or modifications*: this is mainly about http://en.wikipedia.org/wiki/Inversion_of_control[IoC] and http://en.wikipedia.org/wiki/Liskov_substitution_principle[LSP], we want subsystems of your feature to be both injected and abstracted away behind an interface. This allows the actual implementation to be easily replaced with another. We also try to reuse existing `Service` definitions as much as possible. So don't hesitate to slightly tweak an existing one, rather than introducing a new one.
 . *Lifecycle*: You'll want to assess how Ehcache's life cycling may affect your change (if at all). If anything requires any special life cycling (e.g. `PersistentCacheManager` services), you will have to account for this.
 . *Failure*: Most things eventually do go wrong. Whether it's IO, some user provided implementation throwing, the actual `Store` being unaccessible... things just go wrong. Ehcache tries to never do any harm to the user's application. As such your change should account for failure scenarios and possibly delegate to the `ResilienceStrategy` to enable users to deal with such scenarios sensibly.

=== Last touches

Once your change is implemented (see coding guidelines below), you will want to make sure that:

 . You added adequate (but not excessive) logging;
 . Configuration is complete: 
 .. XML configuration was added, but that should never drive the actual configuration concerns;
 .. XML Templating is correctly supported.

== Coding guidelines

=== Commit comment

* Make sure the issue the commit relates is referenced in the commit comment.
** If your commit closes an issue, think about using the [GitHub options](https://help.github.com/articles/closing-issues-via-commit-messages/) for automatically closing the issue when the commit reaches master.
* For your commit comment, you are strongly encouraged to follow the recommendations found [here}(http://chris.beams.io/posts/git-commit/#seven-rules)
** Feel free also to use emoji - current ones used are based on [the following](https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages)

=== Formatting

See what's there for now... Ping us on the https://groups.google.com/forum/#!forum/ehcache-dev[developer mailing list]. We'll export settings for majors IDEs here asap.

=== Unit testing

All changes need to come with appropriate test coverage.

==== Adding code

All this new code you add should have test coverage.

==== Breaking existing tests

Should you break an existing test, take great care before touching the test code to "fix it". While it could definitively be that the test is wrong, it may be correct as well. Always assume the latter is true first. If in doubt, again, ping us on the https://groups.google.com/forum/#!forum/ehcache-dev[developer mailing list].

Changing an existing test for it to pass, because of you recent changes, should really be the last resort. Other than for compilation obviously, or adding mocks and the like.

==== SPI tests

We have an SPI module that covers testing functionality that needs to be provided by a given SPI, e.g. `org.ehcache.spi.cache.Store`.

WARNING: work in progress

=== Logging

We use `slf4j` for all our logging here...

==== Log levels

What level should be used for logging should be dependent on whether you log for the user's benefit (e.g. lifecycle), debugging purposes (a standard `Cache.get(K): V` path). But we don't log `WARN` or `ERROR`.

===== At `INFO` level

We log things about lifecycle:

 * Bootstrapping `CacheManager`,
 * Adding, removing `Cache` to CacheManager
 * ...

Basically everything that would be informational to the end-user.

===== Level `DEBUG` and below

Helps us trace stuff, when some weird scenario is being debugged.

 * Delegating to `CacheLoader`,
 * Delegating to `ResilienceStrategy`,
 * `Store` internals...

===== Levels `WARN` & `ERROR`

Nothing really, if that level is required, we would rather want to throw!

=== Javadoc

==== Public types

Needs to be fully Javadoc'ed

==== Internal concrete classes

Require at least class-level Javadoc. But we value clear method, arguments and variable names above all here.<commit_msg>Fix links formatting<commit_after>= Developer guidelines

:toc:

These are some things to consider when you add code to Ehcache, but certainly when you review a PR!

== General guidelines

Whenever you start working on an issue, you probably want to consider some, if not all, of the items below:

=== API changes

If you need to change the public API (this includes additions), you probably want to start with that first. An easy way to go about that, is to add or modify `GettingStarted` documentation to concretely expose how the API would be affected. You can do this on your branch, as a first commit, and already share it for review with a larger audience, e.g. on the mailing list or through a preliminary pull request.

=== Design 

Whether API is modified or not, you'll want to consider how you plan to go about implementing it all. There are a couple of specificities of the Ehcache internals that would need to be accounted for:

 . *`Service` additions or modifications*: this is mainly about http://en.wikipedia.org/wiki/Inversion_of_control[IoC] and http://en.wikipedia.org/wiki/Liskov_substitution_principle[LSP], we want subsystems of your feature to be both injected and abstracted away behind an interface. This allows the actual implementation to be easily replaced with another. We also try to reuse existing `Service` definitions as much as possible. So don't hesitate to slightly tweak an existing one, rather than introducing a new one.
 . *Lifecycle*: You'll want to assess how Ehcache's life cycling may affect your change (if at all). If anything requires any special life cycling (e.g. `PersistentCacheManager` services), you will have to account for this.
 . *Failure*: Most things eventually do go wrong. Whether it's IO, some user provided implementation throwing, the actual `Store` being unaccessible... things just go wrong. Ehcache tries to never do any harm to the user's application. As such your change should account for failure scenarios and possibly delegate to the `ResilienceStrategy` to enable users to deal with such scenarios sensibly.

=== Last touches

Once your change is implemented (see coding guidelines below), you will want to make sure that:

 . You added adequate (but not excessive) logging;
 . Configuration is complete: 
 .. XML configuration was added, but that should never drive the actual configuration concerns;
 .. XML Templating is correctly supported.

== Coding guidelines

=== Commit comment

* Make sure the issue the commit relates is referenced in the commit comment.
** If your commit closes an issue, think about using the https://help.github.com/articles/closing-issues-via-commit-messages/[GitHub options] for automatically closing the issue when the commit reaches master.
* For your commit comment, you are strongly encouraged to follow the recommendations found http://chris.beams.io/posts/git-commit/#seven-rules[here]
** Feel free also to use emoji - current ones used are based on https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages[the following]

=== Formatting

See what's there for now... Ping us on the https://groups.google.com/forum/#!forum/ehcache-dev[developer mailing list]. We'll export settings for majors IDEs here asap.

=== Unit testing

All changes need to come with appropriate test coverage.

==== Adding code

All this new code you add should have test coverage.

==== Breaking existing tests

Should you break an existing test, take great care before touching the test code to "fix it". While it could definitively be that the test is wrong, it may be correct as well. Always assume the latter is true first. If in doubt, again, ping us on the https://groups.google.com/forum/#!forum/ehcache-dev[developer mailing list].

Changing an existing test for it to pass, because of you recent changes, should really be the last resort. Other than for compilation obviously, or adding mocks and the like.

==== SPI tests

We have an SPI module that covers testing functionality that needs to be provided by a given SPI, e.g. `org.ehcache.spi.cache.Store`.

WARNING: work in progress

=== Logging

We use `slf4j` for all our logging here...

==== Log levels

What level should be used for logging should be dependent on whether you log for the user's benefit (e.g. lifecycle), debugging purposes (a standard `Cache.get(K): V` path). But we don't log `WARN` or `ERROR`.

===== At `INFO` level

We log things about lifecycle:

 * Bootstrapping `CacheManager`,
 * Adding, removing `Cache` to CacheManager
 * ...

Basically everything that would be informational to the end-user.

===== Level `DEBUG` and below

Helps us trace stuff, when some weird scenario is being debugged.

 * Delegating to `CacheLoader`,
 * Delegating to `ResilienceStrategy`,
 * `Store` internals...

===== Levels `WARN` & `ERROR`

Nothing really, if that level is required, we would rather want to throw!

=== Javadoc

==== Public types

Needs to be fully Javadoc'ed

==== Internal concrete classes

Require at least class-level Javadoc. But we value clear method, arguments and variable names above all here.
{'fraction_non_alphanumeric': 0.07336929867582148, 'fraction_numerical': 0.00019617459538989702, 'mean_word_length': 4.363492898474487, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2190515', 'n_tokens_mistral': 2641, 'n_tokens_neox': 2498, 'n_words': 1437}