Manually merge branch 'master' into final

There shouldn't be conflicts reported in the
merge-docs-v3 docs after this.

Signed-off-by: Yannick Schaus <github@schaus.net>

.vuepress/add_placeholders.rb

@@ -3,23 +3,25 @@
 def add_placeholder_pages()
     puts ">>> Adding placeholder pages for preview"
     [
-        "docs/concepts",
         "docs/configuration/iconsets/classic",
         "docs/configuration/ui/habmin",
         "docs/configuration/ui/habot",
         "docs/configuration/ui/basic",
-        "docs/configuration/ui/basic",
         "docs/configuration/ui/classic",
         "docs/ecosystem/alexa",
         "docs/ecosystem/google-assistant",
         "docs/ecosystem/ifttt",
-        "docs/ecosystem/ifttt",
         "docs/ecosystem/mycroft",
-        "addons/integrations/homekit"
-    ].each { |dir|
-        puts " -> #{dir}/"
-        FileUtils.mkdir_p(dir)
-        File.open("#{dir}/readme.md", "w+") { |f|
+        "addons/integrations/homekit",
+        "docs/apps/android.md"
+    ].each { |path|
+        puts " -> #{path}"
+        page = path
+        if (!(path =~ /\.md/)) then
+            FileUtils.mkdir_p(path)
+            page = path + "/readme.md"
+        end
+        File.open(page, "w+") { |f|
             f.puts "# This content is unavailable"
             f.puts ""
             f.puts "This content is migrated from another repository, and is not included in this preview."

.vuepress/config.js

@@ -11,7 +11,7 @@ const HighlightRules = require('./highlight-rules')
 const base = process.env.OH_DOCS_VERSION ? `/v${process.env.OH_DOCS_VERSION}/` : '/'
 
 module.exports = {
-  title: 'Documentation Preview',
+  title: 'v3 Documentation Preview',
   description: 'This is a preview of the main parts of the documentation, found in the openhab/openhab-docs repository',
   dest: 'vuepress',
   host: 'localhost',

.vuepress/docs-sidebar.js

@@ -86,7 +86,7 @@ module.exports = [
       'configuration/rules-ng',
       'configuration/eclipseiotmarket',
       ['configuration/restdocs', 'REST API'],
-      'apps/android',
+      ['apps/android', 'Android App'],
       'apps/ios',
       'apps/windows',
       ['ecosystem/alexa/', 'Amazon Alexa'],

README.md

@@ -1,19 +1,15 @@
-# openHAB 2.x Documentation Project
-
-![](https://img.shields.io/badge/markdown_errors-0-orange.svg)
-[![](https://img.shields.io/badge/linkchecker_errors-89-red.svg)](https://htmlpreview.github.io/?https://github.com/openhab/openhab-docs/blob/gh-pages/invalidlinks.html)
-[![](https://img.shields.io/badge/linkchecker_warnings-421-yellow.svg)](https://htmlpreview.github.io/?https://github.com/openhab/openhab-docs/blob/gh-pages/invalidlinks.html)
+# openHAB 3.x Documentation Project
 
 ## Introduction
 
-This repository contains the documentation for openHAB.
+This repository contains the documentation for openHAB 3.x.
 
-The result is available at [https://www.openhab.org/docs/](https://www.openhab.org/docs/) and [https://www.openhab.org/addons/](https://www.openhab.org/addons/).
+The result is available at [https://next.openhab.org/docs/](https://www.openhab.org/docs/) and [https://next.openhab.org/addons/](https://www.openhab.org/addons/).
 
 ## How it works
 
 In this repo you can find and improve all *general* documentation contents.
-In fact that is all you can see in the `master` branch.
+In fact that is all you can see in the `2.5.x` branch.
 There are also other *read-only* branches, which hold external content like the *add-ons* and *concepts* documentation.
 We will read about them later.
 
@@ -22,7 +18,7 @@ We will read about them later.
 Correct, this is done in the original repository of the add-on.
 You may want to know how to find the right file in all of those repos?
 This is fairly easy: 
-on most of the documentation pages on https://www.openhab.org/, 
+on most of the documentation pages on https://next.openhab.org/, 
 you will find the following link at the bottom, which will point you directly to the file you want to improve.
 
 ![Contribution link to a specific page](./images/contribution_link.png)
@@ -48,17 +44,22 @@ You can read a bit more below about our external ressources and how we get them.
 
 ### Automatically Generated Parts
 
-Those parts include __all__ add-on documentation files, no matter if they are from the `openhab-core` repo, the
-`openhab1-addons` repo, the `openhab-addons` repo or any special binding repo like *habmin*, *zwave* or the *alexa skill*.
+Those parts include __all__ add-on documentation files, no matter if they are from the `openhab-core` repo, the `openhab-addons` repo or any special binding repo like *habmin*, *zwave* or the *alexa skill*.
 
 We are keeping all those files at their original location, because it simply doesn't make sense to keep them here.
 Imagine you want to do an improvement of the zwave binding and have to update the readme file in a completely different place.
 That's twice the effort and also we would have to coordinate two Pull Requests.
 So we are saving time for everyone by keeping those files at their original location along with the code.
 
+::: tip UNDER REVIEW
+
+The process below is subject to changes until the openHAB 3.x website become the production one.
+
+:::
+
 ### How the documentation build works
 
-We have set up our [build server](https://ci.openhab.org/view/Documentation/) to do the magic automatically.
+We have set up our [build server](https://ci.openhab.org/view/Documentation%20(3.x)/) to do the magic automatically.
 There are several triggers (mostly time based), which will then *gather the external contents* and move them to our [final](https://github.com/openhab/openhab-docs/tree/final) branch.
 You can find this migrated external content in the *final* branch under:
 

developers/buildsystem.md

@@ -19,10 +19,8 @@ This section talks about some common buildsystem related topics and also some qu
 
 ## Adding Dependencies
 
-Generally all dependencies should be OSGi-bundles and available on JCenter.
-
-** External dependency **
-In most cases they should be referenced in the project POM with scope `provided`:
+Generally all dependencies should be available on JCenter.
+In most cases they should be referenced in the project POM with scope `compile`:
 
 ```
   <dependencies>
@@ -30,45 +28,39 @@ In most cases they should be referenced in the project POM with scope `provided`
       <groupId>foo.bar</groupId>
       <artifactId>baz</artifactId>
       <version>1.0.0</version>
-      <scope>provided</scope>
+      <scope>compile</scope>
     </dependency>
   </dependencies>
 ```
 
+These dependencies are embedded in the resulting bundle automatically.
+
+There are two exceptions:
+
+1) Dependencies to other openHAB bundles (e.g. `org.openhab.addons.bundles/org.openhab.binding.bluetooth/2.5.0-SNAPSHOT` or `org.openhab.addons.bundles/org.openhab.transform.map/2.5.0-SNAPSHOT`).
+2) Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`).
+
+Dependencies on other openHAB bundles should have the scope `provided`.
 To ensure that they are available at runtime they also need to be added to the `feature.xml`:
 
 ```
-  <bundle dependency="true">mvn:foo.bar/baz/1.0.0</bundle>
+  <bundle dependency="true">mvn:org.openhab.addons.bundles/org.openhab.binding.bluetooth/2.5.0-SNAPSHOT</bundle>
 ```
 
-If the bundle is not an OSGi-bundle, you need to wrap it and provide proper names
-
-```
-  <feature prerequisite="true">wrap</feature>
-  <bundle dependency="true">wrap:mvn:foo.bar/baz/1.0.0$Bundle-Name=Foobar%20Baz%20Library&amp;Bundle-SymbolicName=foo.bar.baz&amp;Bundle-Version=1.0.0</bundle>
-```
-
-** Internal dependency **
-
-In two cases libraries can be added to the `/lib` directory:
-1. The bundle is not available for download
-2. The bundle is not an OSGi bundle but needs to be used for integration tests.
-Unlike Karaf, BND is not able to wrap bundles on its own.
-In this case the binding works as wrapper.
-You need add the library and export all needed packages manually.
-
-The build system automatically picks up all JAR files in `/lib` and embeds them in the new bundle.
-In this case they must not be added to the feature.
-
-If the bundles manifest is not properly exporting all needed packages, you can import them manually by adding 
+Bundles that are used in more than one binding should use the same version that is already present.
+You need to exclude those bundles from embedding by adding an exclusion to the `pom.xml`:
 
 ```
   <properties>
-    <bnd.importpackage>foo.bar.*,foo.baz.*</bnd.importpackage>
+    <dep.noembedding>netty-common</dep.noembedding>
   </properties>
 ```
 
-to the POM.
+It is also necessary to add them to the `feature.xml`(see above).
+If the version that is used in other openHAB bundles is incompatible with your library, check if you can use a different version of your library.
+In case this is not possible, please ask if an exception can be made and a different version can be bundled within your binding.
+Technically you just need to omit the exclusion-statement above.
+If you only depend on shared bundles you can also omit the exclusion statement and add a `noEmbedDependencies.profile` file in the root directory of your binding.
 
 If the imported packages need to be exposed to other bundles (e.g. case 2 above), this has to be done manually by adding
 
@@ -81,4 +73,40 @@ If the imported packages need to be exposed to other bundles (e.g. case 2 above)
 to the POM.
 If `version="1.0.0"` is not set, the packages are exported with the same version as the main bundle.
 Optional parameters available for importing/exporting packages (e.g. `foo.bar.*;resolution:="optional"`) are available, too.
-Packages can be excluded from import/export by prepending `!` in front of the name (e.g. `<bnd.importpackage>!foo.bar.*</bnd.importpackage>' would prevent all packages starting with foo.bar from being imported). 
+Packages can be excluded from import/export by prepending `!` in front of the name (e.g. `<bnd.importpackage>!foo.bar.*</bnd.importpackage>` would prevent all packages starting with foo.bar from being imported).
+
+## Karaf Feature
+
+Each bundle needs a `feature.xml` which is used for the bundle-installation in openHAB.
+A "fits-most-cases" `feature.xml` is automatically generated.
+
+In some cases additional entries need to be added.
+
+### Shared Dependencies (JNA, Netty, etc.)
+
+Bundles that are shared by different openHAB bundles are excluded from embedding.
+The need to be added to the feature to make them available at runtime.
+Two cases need to be treated differently:
+
+1. Bundles that have a core feature are referenced by the feature (e.g. `<feature>openhab-runtime-jna</feature>` or `<feature>openhab-transport-upnp</feature>`).
+2. Bundles that do not have a core feature are added directly (e.g. `<bundle dependency="true">mvn:commons-codec/commons-codec/1.10</bundle>`).
+
+### Multi-Bundle Features / Sub-Bundles
+
+In some cases a binding consists of several bundles (e.g. `mqtt`).
+The `feature.xml` of the sub-bundle (e.g. `mqtt.homie`) needs to add all bundles from the parent-bundle to make sure that the feature verification suceeds:
+
+```
+<feature>openhab-transport-mqtt</feature>
+<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.mqtt/${project.version}</bundle>
+```
+
+To  make sure that all sub-bundles are installed together with the main-bundle, the `feature.xml` of the bundles needs to be excluded from the aggregation.
+Therefore an exclusion needs to be added to `features/openhab-addons/pom.xml` (starting from l. 47):
+
+```
+<exclude name="**/org.openhab.binding.mqtt*/**/feature.xml"/>
+```
+
+An "aggregated" feature then needs to be created in `features/openhab-addons/src/main/resources/footer.xml`.
+The feature is named like the base-bundle and lists all sub-bundles.