Adjust to addon.xml

Signed-off-by: Jan N. Klug <[email protected]>

.vuepress/docs-sidebar.js

@@ -146,6 +146,7 @@ module.exports = [
     children: [
       ['developer/', 'Overview & Introduction'],
       'developer/guidelines',
+      'developer/addons/',
       'developer/bindings/',
       'developer/module-types/',
       'developer/transformations/',

.vuepress/process_main_docs.rb

@@ -160,7 +160,7 @@ def process_main_docs(docs_source_dir)
         puts " -> #{file}"
         process_file("#{docs_source_dir}/developers", file, "docs/developer", "#{$docs_repo_root}/developer/#{file}")
     }
-    ["audio", "bindings", "ioservices", "legacy", "module-types", "osgi", "persistence", "transformations", "utils", "ide"].each { |subsection|
+    ["addons", "audio", "bindings", "ioservices", "legacy", "module-types", "osgi", "persistence", "transformations", "utils", "ide"].each { |subsection|
         Dir.glob("#{docs_source_dir}/developers/#{subsection}/*.md") { |path|
             file = File.basename(path)
             puts " -> #{subsection}/#{file}"

developers/addons/addon.md

@@ -0,0 +1,86 @@
+---
+layout: developersguide
+title: Add-on Descriptions
+---
+
+# Add-on Definitions
+
+Every add-on has to provide meta information such as add-on type, id or name.
+
+Background information: The meta information of all add-ons is accessible through the `org.openhab.core.addon.AddonInfoRegistry` service.
+
+Although add-on definitions are usually specified in a declarative way (as described in this section), they can also be provided as `org.openhab.core.addon.AddonInfo`.
+Any `AddonInfo` must be registered as service at the *OSGi* service registry.
+The full Java API for addon definitions can be found in the Java package `org.openhab.core.addon`.
+
+For the declarative way, you add your add-on information in form of an `addon.xml` file to the bundle's folder `/src/main/resources/OH-INF/addon/`.
+If the add-on consists of more than one bundle, only one `addon.xml` is allowed (in the main-bundle).
+
+## XML Structure for Add-on Definitions
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<addon:addon id="addonID"
+    xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+    xmlns:addon="https://openhab.org/schemas/addon/v1.0.0"
+    xsi:schemaLocation="https://openhab.org/schemas/addon/v1.0.0
+        https://openhab.org/schemas/addon-1.0.0.xsd">
+
+  <type>String</type>
+  <name>String</name>
+  <description>String</description>
+
+  <service-id>String</service-id>
+
+  <config-description>
+    ...
+  </config-description>
+  OR
+  <config-description-ref uri="{addon|thing-type|channel-type|any_other}:addonID:..." />
+
+</addon:addon>
+```
+
+| Property                   | Description                                                                                                                                                                                                   |           |
+|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
+| addon.id                   | An identifier for the add-on                                                                                                                                                                                  | mandatory |
+| type                       | Either `automation`, `binding`, `misc`, `persistence`, `transform`, `ui` or `voice`                                                                                                                           | mandatory |
+| name                       | A human-readable name for the add-on                                                                                                                                                                          | mandatory |
+| description                | A human-readable description for the add-on                                                                                                                                                                   | optional  |
+| author                     | In general be the organisation maintaining this add-on (e.g. openHAB), not an individual's name                                                                                                               | optional  |
+| connection                 | `local` for add-ons that only interact locally, `cloud` for add-ons that require a cloud connection, `cloudDiscovery` for add-ons that require a cloud connection for set-up                                  | optional  |
+| countries                  | List of two-letter ISO country codes that are supported (all countries if empty)                                                                                                                              | optional  |
+| service-id                 | The ID (service.pid or component.name) of the main binding service, which can be configured through OSGi configuration admin service. Should only be used in combination with a config description definition | optional  |
+| config-description         | The configuration description for the binding within the ConfigDescriptionRegistry (cf. [Configuration Description](config-xml.html))                                                                         | optional  |
+| config-description-ref     | The reference to a configuration description for the binding within the ConfigDescriptionRegistry                                                                                                             | optional  |
+| config-description-ref.uri | The URI of the configuration description for the binding within the ConfigDescriptionRegistry                                                                                                                 | mandatory |
+
+The full XML schema for add-on definitions is specified in the [Add-on XSD](https://openhab.org/schemas/addon-1.0.0.xsd) file.
+
+**Hints:**
+
+- The attribute `uri` in the section `config-description` is optional, it *should not* be specified in add-on definition files because it's an embedded configuration. If the `uri` is *not* specified, the configuration description is registered as `type:addonID`, otherwise the given `uri` is used.
+- If a configuration description is already specified somewhere else and the add-on wants to (re-)use it, a `config-description-ref` should be used instead.
+- Normally the service id must not be defined, because it is implicitly set to "type.&lt;addonId&gt;".
+  An add-on can register an OSGi service which implements the ManagedService interface and define the service.pid as e.g."binding.hue" to receive the configuration.
+
+## Example
+
+The following code gives an example for an add-on definition used in bindings.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<addon:addon id="bindingID"
+    xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+    xmlns:addon="https://openhab.org/schemas/addon/v1.0.0"
+    xsi:schemaLocation="https://openhab.org/schemas/addon/v1.0.0
+        https://openhab.org/schemas/addon-1.0.0.xsd">
+
+  <type>binding</type>
+  <name>hue Binding</name>
+  <description>The hue Binding integrates the Philips hue system. It allows to control hue bulbs.</description>
+
+  <connection>local</connection>
+
+</addon:addon>
+```

developers/addons/index.md

@@ -0,0 +1,77 @@
+---
+layout: developersguide
+title: Add-ons
+---
+
+# Developing an Add-on
+
+{:.no_toc}
+
+An add-on is an extension to openHAB that integrates external components like software services or hardware devices.
+Depending on their use-case they have different types:
+
+- `automation` for add-ons that provide scripting languages or rule templates
+- `binding` for controlling physical devices or software systems
+- `misc` for other integrations like Apple's HomeKit or the openHAB cloud
+- `persistence` for services that can be used to store and read historical data
+- `transform` for add-on that provide a way to manipulate values
+- `ui` for bundles that provide UIs or UI-additions (like widgets)
+- `voice` for add-ons that provide voice services
+
+Every add-on needs to define a `addon.xml` file.
+Find more information in the respective [Add-on XML reference](addon.html).
+
+# Include the Add-on in the Build
+
+Once you are happy with your implementation, you need to integrate it in the Maven build and add it to the official distro.
+
+- Add a new line in the [bundle pom.xml](https://github.com/openhab/openhab-addons/blob/main/bundles/pom.xml).
+- Add a new line in the [binding pom.xml](https://github.com/openhab/openhab-addons/blob/main/bom/openhab-addons/pom.xml).
+- If you have a dependency on a transport bundle (e.g. upnp, mdns or serial) or an external library,
+  make sure to add a line for this dependency in the `/src/main/feature/feature.xml` file in your add-on folder. See the other add-ons as an example.
+- Add your binding to the [CODEOWNERS](https://github.com/openhab/openhab-addons/blob/main/CODEOWNERS) file so that you get notified by GitHUB when someone adds a pull request towards your add-on.
+
+> Please make sure you add the above entries at their alphabetically correct position!
+
+Before you create a pull request on GitHub, you should now run
+
+```bash
+mvn clean install
+```
+
+from the repository root to ensure that the build works smoothly (that step takes about 30 minutes).
+
+The build includes [Tooling for static code analysis](https://github.com/openhab/static-code-analysis) that will validate your code against the openHAB Coding Guidelines and some additional best practices.
+Please fix all the priority 1 issues and all issues with priority 2 and 3 that are relevant (if you have any doubt don't hesitate to ask).
+to
+
+You can always run the above command from within your add-on's directory to speed the build up and fix and check reported errors.
+Formatting error can be fixed by
+
+```bash
+mvn spotless:apply
+```
+
+Re-run the build to confirm that the checks are passing.
+If it does, it is time to [contribute your work](../contributing.html)!
+
+# Add your add-on's logo to the openHAB website
+
+After your pull request has been merged and the next openHAB version is released, your add-on will be available in the addons search on the openHAB website with a default logo.
+
+You can upload a logo to display it on the openhab.org start page, the addon search and in the readme.
+
+These are the requirements for logos:
+
+- PNG (transparancy is preferred)
+- 512x512 pixels or smaller in one dimension, if it's not a square logo
+- Less than 30kB
+
+File size is key as the website displays hundreds of small logos on the same page.
+To shrink the file size, save your logo with Palette-Based Colors (sometimes called "Indexed-RGBA").
+Also, JPEG compression artifacts from prior conversions or halo around the logo increases file size dramatically.
+There are online converters to convert your True Color PNG logo to Palette-Based Colors. E.g. <https://compresspng.com/>.
+Or use zopflipng: `zopflipng -m --filters=0me --lossy_8bit --lossy_transparent -y logo.png logo.png`
+
+_After_ your binding's pull request has been merged, you can upload your logo by filing another pull request to the [openhab-docs/images/addons/](https://github.com/openhab/openhab-docs/tree/main/images/addons) repository.
+Your logo will be available after the next website build.