From 4dcdca1bd59a7a643c02d214b59f51944a2c39f6 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 11 Nov 2014 22:51:08 -0800 Subject: [PATCH] Updated CONTRIBUTING documentation --- CONTRIBUTING.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46d4ad48c4d..f30ebf040d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,13 +2,22 @@ You've probably came here beacuse you noticed that your favorite device is not supported and want to add it. -First step is to decide under which component the device has to reside. Each component is responsible for a specific domain within Home Assistant. An example is the switch component, which is responsible for interaction with different types of switches. +First step is to decide under which component the device has to reside. Each component is responsible for a specific domain within Home Assistant. An example is the switch component, which is responsible for interaction with different types of switches. The switch component consists of the following files: -If a component exists, your job is easy. Have a look at how the component works with other platforms and it should be easy to figure out how to add yours. If you cannot find a suitable component, you'll have to add it yourself. +**homeassistant/components/switch/\_\_init\_\_.py**
+Contains the Switch component code. -Communication between Home Assistant and devices should happen via third-party libraries that implement the device API. This will make sure the components stay as small as possible. +**homeassistant/components/switch/wemo.py**
+Contains the code to interact with WeMo switches. Called if type=wemo in switch config. -After you finish adding your device: +**homeassistant/components/switch/tellstick.py** +Contains the code to interact with Tellstick switches. Called if type=tellstick in switch config. + +If a component exists, your job is easy. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add.If you cannot find a suitable component, you'll have to add it yourself. When writing a component try to structure it after the Switch component to maximize reusability. + +Communication between Home Assistant and devices should happen via third-party libraries that implement the device API. This will make sure the platform support code stays as small as possible. + +After you finish adding support for your device: - update the supported devices in README.md. - add any new dependencies to requirements.txt. @@ -20,7 +29,7 @@ If you've added a component: - update the demo component with two states that it provides - Add your component to home-assistant.conf.example -If you have made changes to the frontend: +Since you've updated domain-icon.html, you've made changes to the frontend: - run `build_frontend`. This will build a new version of the frontend. Make sure you add the changed files `frontend.py` and `frontend.html` to the commit. @@ -38,10 +47,10 @@ These attributes are defined in [homeassistant.components](https://github.com/ba ## Working on the frontend -The frontend is composed of Polymer web-components and compiled into the file frontend.html. During development you do not want to work with the compiled version but with the seperate files. To have Home Assistant serve the seperate files, set development=1 for the http-component in your config. +The frontend is composed of Polymer web-components and compiled into the file `frontend.html`. During development you do not want to work with the compiled version but with the seperate files. To have Home Assistant serve the seperate files, set `development=1` for the http-component in your config. -When you are done with development and ready to commit your changes, run `build_frontend`, set development=0 in your config and validate that everything still works. +When you are done with development and ready to commit your changes, run `build_frontend`, set `development=0` in your config and validate that everything still works. ## Notes on PyLint and PEP8 validation -In case a PyLint warning cannot be avoided, add a comment to disable the PyLint check for that line. This can be done using the format `# pylint: disable=YOUR-ERROR-NAME`. A reason of an unavoidable PyLint warning is if you do not use the passed in datetime if you're listening for time change. +In case a PyLint warning cannot be avoided, add a comment to disable the PyLint check for that line. This can be done using the format `# pylint: disable=YOUR-ERROR-NAME`. Example of an unavoidable PyLint warning is if you do not use the passed in datetime if you're listening for time change.