From a341b7248be65e74fa6255011aaec85f0eeee606 Mon Sep 17 00:00:00 2001
From: Paulus Schoutsen <paulus@paulusschoutsen.nl>
Date: Sun, 15 Jan 2017 15:27:02 -0800
Subject: [PATCH] Add initial code review check lists

---
 .../asides/developers_navigation.html         |  2 +
 .../developers/code_review_component.markdown | 40 +++++++++++
 .../developers/code_review_platform.markdown  | 67 +++++++++++++++++++
 3 files changed, 109 insertions(+)
 create mode 100644 source/developers/code_review_component.markdown
 create mode 100644 source/developers/code_review_platform.markdown

diff --git a/source/_includes/asides/developers_navigation.html b/source/_includes/asides/developers_navigation.html
index 9ec9e38ca0e..5fdc0d9adfc 100644
--- a/source/_includes/asides/developers_navigation.html
+++ b/source/_includes/asides/developers_navigation.html
@@ -25,6 +25,7 @@
       <li>
         {% active_link /developers/add_new_platform/ Support a new device (as a platform) %}
         <ul>
+          <li>{% active_link /developers/code_review_platform/ Checklist creating a platform %}</li>
           <li>{% active_link /developers/platform_example_sensor/ Example sensor platform  %}</li>
           <li>{% active_link /developers/platform_example_light/ Example light platform %}</li>
         </ul>
@@ -32,6 +33,7 @@
       <li>
         {% active_link /developers/creating_components/ Adding a new component %}
         <ul>
+          <li>{% active_link /developers/code_review_component/ Checklist creating a component %}</li>
           <li>{% active_link /developers/component_loading/ Loading components %}</li>
           <li>{% active_link /developers/component_deps_and_reqs/ Requirements & Dependencies %}</li>
           <li>{% active_link /developers/component_initialization/ Initialization %}</li>
diff --git a/source/developers/code_review_component.markdown b/source/developers/code_review_component.markdown
new file mode 100644
index 00000000000..9e2d5ffb594
--- /dev/null
+++ b/source/developers/code_review_component.markdown
@@ -0,0 +1,40 @@
+---
+layout: page
+title: "Checklist for creating a component"
+description: "A list of things to pay attention to when code reviewing a component."
+date: 2017-01-15 14:09 -0800
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+A checklist of things to do when you're adding a new component.
+
+### {% linkable_title Requirements %}
+
+ 1. Requirement version pinned: `REQUIREMENTS = ['phue==0.8.1']`
+ 2. If requirement hosted on GitHub:
+     - Point at a zip archive of a release tag or commit SHA.
+     - Add version found in zip-archive as hash to url.
+
+```python
+REQUIREMENTS = [
+    'http://github.com/technicalpickles/python-nest'
+    '/archive/e6c9d56a8df455d4d7746389811f2c1387e8cb33.zip'
+    '#python-nest==3.0.3']
+```
+
+### {% linkable_title Configuration %}
+
+ 1. Volutpuous schema present for config validation
+ 2. Default parameters specified in voluptuous schema, not in `setup_platform(…)`
+ 3. Schema using as many generic config keys as possible from `homeassistant.const`
+ 4. If having platforms, have a `PLATFORM_SCHEMA`, otherwise `CONFIG_SCHEMA`.
+ 5. If `PLATFORM_SCHEMA`, import base from `homeassistant.helpers.config_validation`
+
+
+### {% linkable_title Component/platform communication %}
+
+ 1. If you need to share global data with platforms, use the dictionary `hass.data`.
+ 2. If the component fetches data that causes related platform entities to update,
diff --git a/source/developers/code_review_platform.markdown b/source/developers/code_review_platform.markdown
new file mode 100644
index 00000000000..a50fdf91a79
--- /dev/null
+++ b/source/developers/code_review_platform.markdown
@@ -0,0 +1,67 @@
+---
+layout: page
+title: "Checklist for creating a platform"
+description: "A list of things to pay attention to when code reviewing a platform."
+date: 2017-01-15 14:09 -0800
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+A checklist of things to do when you're adding a new platform.
+
+### {% linkable_title 1. Requirements %}
+
+ 1. Requirement version pinned: `REQUIREMENTS = ['phue==0.8.1']`
+ 2. If requirement hosted on GitHub:
+     - Point at a zip archive of a release tag or commit SHA.
+     - Add version found in zip-archive as hash to url.
+
+```python
+REQUIREMENTS = [
+    'http://github.com/technicalpickles/python-nest'
+    '/archive/e6c9d56a8df455d4d7746389811f2c1387e8cb33.zip'
+    '#python-nest==3.0.3']
+```
+
+### {% linkable_title 2. Dependencies %}
+
+ 1. If you depend on a component for the connection, add it to your dependencies: `DEPENDENCIES = ['nest']`
+
+### {% linkable_title 3. Configuration %}
+
+ 1. Volutpuous schema present for config validation
+ 2. Voluptuous schema extends schema from component<br>(e.g. `light.hue.PLATFORM_SCHEMA` extends `light.PLATFORM_SCHEMA`)
+ 3. Default parameters specified in voluptuous schema, not in `setup_platform(…)`
+ 4. Schema using as many generic config keys as possible from `homeassistant.const`
+
+```python
+import voluptuous as vol
+
+from homeassistant.const import CONF_FILENAME, CONF_HOST
+from homeassistant.components.light import PLATFORM_SCHEMA
+import homeassistant.helpers.config_validation as cv
+
+CONF_ALLOW_UNREACHABLE = 'allow_unreachable'
+DEFAULT_UNREACHABLE = False
+
+PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
+    vol.Required(CONF_HOST): cv.string,
+    vol.Optional(CONF_ALLOW_UNREACHABLE,
+                 default=DEFAULT_UNREACHABLE): cv.boolean,
+    vol.Optional(CONF_FILENAME): cv.string,
+})
+```
+
+### {% linkable_title 4. Setup Platform %}
+
+ 1. Test if passed in info (user/pass/host etc.) works.
+ 2. Group your calls to `add_devices` if possible.
+ 3. If platform adds extra services, format should be `<component>.<platform>_<service name>`.
+
+### {% linkable_title 5. Entity %}
+
+ 1. Extend entity from component, e.g. `class HueLight(Light)`
+ 2. Do not call `update()` in constructor, use `add_devices(devices, True)` instead.
+ 3. Do not do any I/O inside properties. Cache values inside `update()` instead.