Addition of persistence addon to distribution (openhab#756)

This hopefully clarifies the steps. See
openhab/openhab1-addons#5334
for practical discussions in the context of DynamoDB
addon.

Signed-off-by: Sami Salonen <ssalonen@gmail.com>

Author: ssalonen

developers/development/compatibilitylayer.md

@@ -34,12 +34,21 @@ Here is what you need to do:
 
 ## How to add a successfully tested 1.x Add-on to the distribution
 
+With bindings:
+
 1. The first step is to create a "Karaf feature" for it, in which required dependencies (i.e. to io.transport bundles) can also be declared. Such a feature can also include the required configuration, therefore you should create a file `<youraddon>.cfg` in `features/openhab-addons-external/src/main/resources/conf` with the same content as what is within `openhab.cfg`, but without the `<yourbinding>:` prefix on the lines of the parameters.
 This config file then needs to be added to `features/openhab-addons-external/pom.xml` so that the build is aware of it.
 The feature itself is then added to `features/openhab-addons/src/main/feature/feature.xml`, referencing the bundle, the config file and its dependencies (if any). The result should look [similar to this](https://github.com/openhab/openhab/pull/3988/files).
 This will automatically make the add-on a part of the distro with the next build.
 1. Note that with defining a Karaf feature, bindings are available for installation through the Paper UI in the "Extensions" menu, but they are not listed under "Configuration->Bindings" (although it is fully operational after installation). In order to have bindings listed there as well, you need to add some meta-information to the binding bundle. This information should be put into `ESH-INF/binding/binding.xml` and its content is [described here](https://www.eclipse.org/smarthome/documentation/development/bindings/xml-reference.html#xml-structure-for-binding-definitions). Do not forget to add `ESH-INF` to your `build.properties`, so that it is packaged in the bundle. See a [real life example of such meta-data here](https://github.com/openhab/openhab/blob/master/bundles/binding/org.openhab.binding.nest/ESH-INF/binding/binding.xml) - note the `service-id` element in the XML, which needs to point to the service id of your binding, which is by default `org.openhab.<bindingId>` for all 1.x bindings.
 
+With persistence addons:
+
+1. create a "Karaf feature" similar to bindings. See this [example](https://github.com/openhab/openhab1-addons/pull/5635/commits/42d1e8d29ffad75ef6a846306a71d10ee4d0f641)
+2. create config description to allow configuring the addon via Paper UI. See this [example](https://github.com/openhab/openhab1-addons/pull/5635/commits/98700634af34c52539aa877c0e4a254392baf674)
+3. ensure that persistence service is not set to `immediate`. See this [example](https://github.com/openhab/openhab1-addons/pull/5635/commits/39b47e7f2e8763ae72007d615e6675ea08cbe001)
+4. it is also good practice to declare `service.pid` and advice using it in the configuration template. See this  [example](https://github.com/openhab/openhab1-addons/pull/5635/commits/66b7f7f18a55abcba4215d490dd9239c729b3804).
+
 ## Future Plans
 
 Note that the maintenance and support of the 1.x add-ons will continue. There is absolutely no need and no rush to port them to the new 2.x APIs - especially as there are only new APIs for bindings so far, but nothing yet for actions, persistence services or other types of add-ons. Even for bindings you have to be aware that the new APIs are not yet stable and are likely to change over time. Nonetheless, if you [start a completely new binding](../development/bindings.html) for openHAB, you are encouraged to go for openHAB 2 APIs directly - especially, if your devices can be discovered and formally described. A positive side effect of implementing a binding against the new APIs is the fact that your code is potentially automatically compatible with other Eclipse-SmartHome-based systems (of which there will be more in future).