[Development] Incorporate findings from code reviews (#322)

Signed-off-by: Kai Kreuzer <kai@openhab.org>

developers/contributing/contributing.md

@@ -44,8 +44,8 @@ else is working on the same thing.
 
 ### Create Issues...
 
-Any significant improvement should be documented as [a GitHub
-issue](https://github.com/openhab/openhab-distro/issues?labels=enhancement&page=1&state=open) before anybody
+Any significant improvement should be documented as a GitHub
+issue in the [appropriate repository](#the-repositories) before anybody
 starts working on it.
 
 ### ...but Check for Existing Issues First!
@@ -98,20 +98,14 @@ same commit so that a revert would remove all traces of the feature or fix.
 Commits that fix or close an issue should include a reference like `Closes #XXX`
 or `Fixes #XXX`, which will automatically close the issue when merged.
 
-Add your name to the AUTHORS file, but make sure the list is sorted and your
-name and email address match your git configuration. The AUTHORS file is
-regenerated occasionally from the git commit history, so a mismatch may result
-in your changes being overwritten.
-
 ### Merge Approval
 
-openHAB maintainers use LGTM (Looks Good To Me) in comments on the code review
-to indicate acceptance.
+openHAB maintainers use the [Github review feature](https://help.github.com/articles/about-pull-request-reviews/) to indicate acceptance.
 
-A change requires LGTMs from an absolute majority of the maintainers of each
-component affected. For example, if a change affects `docs/` and `distributions/`, it
-needs an absolute majority from the maintainers of `docs/` AND, separately, an
-absolute majority of the maintainers of `addons/`.
+A change requires approval from an absolute majority of the maintainers of each
+component affected. For example, if a change affects `addons/` and `features/`, it
+needs an absolute majority from the maintainers of `addons/` AND, separately, an
+absolute majority of the maintainers of `features/`.
 
 ### Sign your Work
 
@@ -166,6 +160,12 @@ then you just add a line to every git commit message:
 
 using your real name (sorry, no pseudonyms or anonymous contributions.)
 
+If your commit contains code from others as well, please ensure that they certify the DCO as well and add them with an "Also-By" line to your commit message:
+
+    Also-by: Ted Nerd <ted.nerd@email.com> (github: github_handle_ted)
+    Also-by: Sue Walker <sue.walker@email.com> (github: github_handle_sue)
+    Signed-off-by: Joe Smith <joe.smith@email.com> (github: github_handle_joe)
+
 #### Small Patch Exception
 
 There are several exceptions to the signing requirement. Currently these are:

developers/development/bindings.md

@@ -5,13 +5,13 @@ title: Developing bindings
 
 {% include base.html %}
 
-# Developing a New Binding for openHAB 2
+# Developing a Binding for openHAB 2
 
 This page describes the necessary steps in order to implement a new binding for openHAB 2.
 
 _Note:_ Please note that in contrast to openHAB 1.x, openHAB 2 is based on the [Eclipse SmartHome](http://eclipse.org/smarthome/) project. So the APIs and concepts have changed, so please read this documentation carefully, if you are coming from openHAB 1.x development.
 
-For information about code style and naming conventions, please see the [guidelines of Eclipse SmartHome](https://www.eclipse.org/smarthome/documentation/development/guidelines.html).
+For information about code style and naming conventions, please see the [coding guidelines](guidelines).
 
 ## Choosing a Namespace
 
@@ -28,10 +28,17 @@ For the Eclipse SmartHome namespace: Choose the option "Eclipse SmartHome Extens
 
 Now switch in Eclipse and choose `File->Import->General->Existing Projects into Workspace`, enter the folder of the newly created skeleton as the root directory and press "Finish".
 
-This should give you an easy starting point for your developments. To learn about the internal structure and the concepts of a binding, please see the [Eclipse tutorial on binding development](https://www.eclipse.org/smarthome/documentation/development/bindings/how-to.html).
-
 _Note:_ Here you can find a [screencast of the binding skeleton creation](http://youtu.be/30nhm0yIcvA).
 
+## Implement the Binding
+
+The skeleton should give you an easy starting point for your developments.
+To learn about the internal structure and the concepts of a binding, please see the [Eclipse tutorial on binding development](https://www.eclipse.org/smarthome/documentation/development/bindings/how-to.html).
+
+Please especially note our [coding guidelines](guidelines), which must be respected for having pull requests approved.
+If you have any special dependencies of your code, please check the [library recommendations](https://www.eclipse.org/smarthome/documentation/development/bindings/dependencies.html) at Eclipse SmartHome.
+This will ensure that everyone uses the same libraries for e.g. JSON and XML processing or for HTTP and websocket communication.
+
 ## Setup and Run the Binding
 
 To setup the binding you need to configure at least one *Thing* and link an *Item* to it. In your workspace in `demo-resources/src/main/resources/things`, you can define and configure *Things* in file with a `*.things` extensions. The following file defines a thing for the Yahoo Weather binding:
@@ -52,3 +59,17 @@ Number Berlin_Humidity          "Humidity in Berlin [%d %%]"        { channel="y
 The syntax for a channel link is `{ channel = "<binding-id>:<thing-type-id>:<thing-id>:<channel-id>" }`.
 
 If you start the openHAB runtime including the binding now (make sure that your binding is checked in the launch configuration dialog!), the code inside your `ThingHandler` implementation is executed.
+
+## Include the Binding in the Build and the Distro
+
+Once you are happy with your implementation, you need to integrate it in the Maven build and add it to the official distro.
+For the Maven build, please add a new line in the [binding pom.xml](https://github.com/openhab/openhab2-addons/blob/master/addons/binding/pom.xml) at the alphabetically correct position.
+To have the binding being picked up by the distro, you furthermore need to add it to the [feature.xml](https://github.com/openhab/openhab2-addons/blob/master/features/openhab-addons/src/main/feature/feature.xml), again at the alphabetically correct position. If you have a dependency on some transport bundle (e.g. upnp, mdns or serial), make sure to add a line for this dependency as well (see the other bindings as an example).
+
+Before you create a pull request on Github, you should  now run
+
+```
+mvn clean install
+```
+
+from the repository root to ensure that the build works smoothly. If it does, it is time to [contribute your work](../contributing/contributing)!

developers/development/guidelines.md

@@ -7,8 +7,9 @@ title: Coding Guidelines
 
 # Coding Guidelines
 
-The following guidelines apply to all code of the Eclipse SmartHome project. They must be followed to ensure a consistent code base for easy readability and maintainability.
-Exceptions can certainly be made, but they should be discussed and approved by a project committer upfront.
+The following guidelines apply to all (Java) code of the openHAB project.
+They must be followed to ensure a consistent code base for easy readability and maintainability.
+Exceptions can certainly be made, but they should be discussed and approved by a project maintainer upfront.
 
 Note that this list also serves as a checklist for code reviews on pull requests. To speed up the contribution process, we therefore advice to go through this checklist yourself before creating a pull request.
 
@@ -28,7 +29,7 @@ Note that this list also serves as a checklist for code reviews on pull requests
 ## B. OSGi Bundles
 
 7. Every bundle must contain a Maven pom.xml with a version and artifact name that is in sync with the manifest entry. The pom.xml must reference the correct parent pom (which is usually in the parent folder).
-1. Every bundle must contain an [about.html](https://eclipse.org/legal/epl/about.php) file, providing license information. If there is a third-party software in the bundle, its licence information must be added to the bundle's about.html file. You can look at and use these two examples: [about.html without 3rd party licence information](https://github.com/openhab/openhab2-addons/blob/master/addons/ui/org.openhab.ui.cometvisu.php/about.html) and [about.html with 3rd party licence information](https://github.com/openhab/openhab2-addons/blob/master/addons/binding/org.openhab.binding.avmfritz/about.html). The date in the about.html files must be changed to the current.
+1. Every bundle must contain an about.html file, providing license information. If there is a third-party software in the bundle, its licence information must be added to the bundle's about.html file. You can look at and use these two examples: [about.html without 3rd party licence information](https://github.com/openhab/openhab2-addons/blob/master/addons/ui/org.openhab.ui.cometvisu.php/about.html) and [about.html with 3rd party licence information](https://github.com/openhab/openhab2-addons/blob/master/addons/binding/org.openhab.binding.avmfritz/about.html). The date in the about.html files must be changed to the current.
 1. Every bundle must contain a build.properties file, which lists all resources that should end up in the binary under `bin.includes`.
 1. The manifest must not contain any "Require-Bundle" entries. Instead, "Import-Package" must be used.
 1. The manifest must not export any internal package.