From b47b7a0e50073c43a5de227291d92fd15223072e Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 14:57:55 -0400 Subject: [PATCH 01/16] Fixed typos and made organization suggestions (#1116) --- .../development_submitting.markdown | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/source/developers/development_submitting.markdown b/source/developers/development_submitting.markdown index 8843ef45fb4..0faeca19b0b 100644 --- a/source/developers/development_submitting.markdown +++ b/source/developers/development_submitting.markdown @@ -9,18 +9,29 @@ sharing: true footer: true --- -Improvements, fixes, and new features to Home Assistant should be submitted one feature at a time using GitHub [Pull Requests](https://help.github.com/articles/using-pull-requests). +Submit your improvements, fixes, and new features to Home Assistant one at a time, using GitHub [Pull Requests](https://help.github.com/articles/using-pull-requests). Here are the steps: - 1. From your fork, create a new branch to hold your changes + 1. From your fork, create a new branch to hold your changes: + `git checkout -b some-feature` - 2. Make the changes you want, create a [new platform](/developers/add_new_platform/), develop a [new component](/developers/creating_components/), or fix [issues](https://github.com/home-assistant/home-assistant/issues). - 3. [Test your changes](/developers/development_testing/) and check for style violations - 4. Commit the changes if all [musts](/developers/development_checklist/) are covered. + + 2. Make your changes, create a [new platform](/developers/add_new_platform/), develop a [new component](/developers/creating_components/), or fix [issues](https://github.com/home-assistant/home-assistant/issues). + + 3. [Test your changes](/developers/development_testing/) and check for style violations. + + 4. If everything looks good according to these [musts](/developers/development_checklist/), commit your changes: + `git add .` + `git commit -m "Added some-feature"` - 5. Consider to add tests to ensure that the code works. - 6. Push your committed changes back to your fork on GitHub + + * Consider adding tests to ensure that your code works. + + 5. Push your committed changes back to your fork on GitHub: + `git push origin HEAD` - 7. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request. - 8. Check for comments and suggestions on your Pull Request and keep an eye on the [CI output](https://travis-ci.org/home-assistant/home-assistant/). + + 6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request. + + 7. Check for comments and suggestions on your pull request and keep an eye on the [CI output](https://travis-ci.org/home-assistant/home-assistant/). From 805ff18761fe12d5ad09a417bf05b8003060abd3 Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 14:59:35 -0400 Subject: [PATCH 02/16] Fixed a few typos; formatted into numbered steps. (#1115) --- .../development_environment.markdown | 33 ++++++++++--------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/source/developers/development_environment.markdown b/source/developers/development_environment.markdown index 2264698c9aa..de667145236 100644 --- a/source/developers/development_environment.markdown +++ b/source/developers/development_environment.markdown @@ -9,26 +9,27 @@ sharing: true footer: true --- -You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to get setup. -Visit the [the Home Assistant repository](https://github.com/home-assistant/home-assistant) first and click fork in the top right. +You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up. -We suggest that you setup a virtual environment using [`venv`](https://docs.python.org/3.4/library/venv.html) before running the setup script. +1. Visit the [the Home Assistant repository](https://github.com/home-assistant/home-assistant) and click "fork." -```bash -$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git -$ cd home-assistant -$ git remote add upstream https://github.com/home-assistant/home-assistant.git -$ script/setup -``` -On Windows you can use `python setup.py develop` instead of the setup script. + * Consider setting up a virtual environment using [`venv`](https://docs.python.org/3.4/library/venv.html) before running the setup script. -After following these steps, running `hass` will invoke your local installation. + ```bash + $ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git + $ cd home-assistant + $ git remote add upstream https://github.com/home-assistant/home-assistant.git + $ script/setup + ``` + * On Windows, you can use `python setup.py develop` instead of the setup script. + +2. Run `hass` to invoke your local installation. ### Developing on Windows -If you are using Windows as a development platform ensure you have the correct Microsoft Visual C++ build tools installed. Please check [the Windows Compilers](https://wiki.python.org/moin/WindowsCompilers) section on the [Python website](https://www.python.org/) for details. Validation using `tox` will fail if this is not done correctly. +If you are using Windows as a development platform, make sure that you have the correct Microsoft Visual C++ build tools installed. Check the [Windows Compilers](https://wiki.python.org/moin/WindowsCompilers) section on the [Python website](https://www.python.org/) for details. Validation using `tox` will fail if this is not done correctly. -Ensure you install or upgrade the Setuptools Python package. It contains compatibility improvements and adds automatic use of compilers: -```bash -pip install --upgrade setuptools -``` +Also, make sure to install or upgrade the `Setuptools` Python package -- it contains compatibility improvements and adds automatic use of compilers: + ```bash + pip install --upgrade setuptools + ``` From 7e866593fe2800442fbb7bd0a9975ee19e3b40ac Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 15:00:53 -0400 Subject: [PATCH 03/16] Fixed typos and format inconsistencies (#1114) --- source/developers/development.markdown | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/developers/development.markdown b/source/developers/development.markdown index dd073e52c3b..a926ff185bb 100644 --- a/source/developers/development.markdown +++ b/source/developers/development.markdown @@ -9,11 +9,11 @@ sharing: true footer: true --- -Home Assistant is built from the ground up to be easily-extensible by other developers using components. It uses [Python 3](https://www.python.org/) for the backend and [Polymer (Web components)](https://www.polymer-project.org/) for the frontend. +Home Assistant is built from the ground up to be easily extensible using components. Home Assistant uses [Python 3](https://www.python.org/) for the backend and [Polymer (Web components)](https://www.polymer-project.org/) for the frontend. -Home Assistant is open-source and MIT licensed. The source can be found here: +Home Assistant is open-source and MIT-licensed. Here are links to the source:: - - [home-assistant](https://github.com/home-assistant/home-assistant) - Python server backend - - [home-assistant-js](https://github.com/home-assistant/home-assistant-js) - JavaScript backend powering the client - - [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer) - Polymer UI + - [home-assistant](https://github.com/home-assistant/home-assistant): Python server backend. + - [home-assistant-js](https://github.com/home-assistant/home-assistant-js): JavaScript backend that powers the client. + - [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer): Polymer UI. From fdf851e5bb5ef115926e26490a9dbb194fb3a58f Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 15:01:39 -0400 Subject: [PATCH 04/16] Fixed typos/minor grammar errors (#1113) Also made a couple suggestions to improve voice/friendliness --- .../architecture_components.markdown | 26 +++++++++---------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/source/developers/architecture_components.markdown b/source/developers/architecture_components.markdown index c6612fb2964..d3ae5dc5f6c 100644 --- a/source/developers/architecture_components.markdown +++ b/source/developers/architecture_components.markdown @@ -9,30 +9,28 @@ sharing: true footer: true --- -Home Assistant can be extended by **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for or trigger events, offer services and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components]({{site_root}}/components/). +Home Assistant can be extended with **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for or trigger events, offer services, and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components]({{site_root}}/components/).

Diagram showing interaction between components and the Home Assistant core. -Diagram showing interaction between components and the Home Assistant core. +Diagram showing interaction between components and the Home Assistant core

-We can differentiate between two different types of components within Home Assistant. +There are two types of components within Home Assistant: components that interact with an Internet-of-Things domain, and components that respond to events that happen within Home Assistant. Read on to learn about each type! -#### {% linkable_title Components that interact with an Internet of Things domain %} +#### {% linkable_title Components that interact with an Internet-of-Things domain %} -These components will track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices. +These components track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The components also register services in the Service Registry to expose control of the devices. -For example, one of the built-in components is the [`switch` component](/components/switch/). This component is responsible for interaction with different types of switches. +For example, the built-in [`switch` component](/components/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform, and a light component might interact with the Hue or LiFX platform. -A platform provides support for a particular kind/brand of device. For example, a switch could use a WeMo or Orvibo platform, and a light component might interact with the Hue or LiFX platform. - -If you are planning to add support for a new platform, please check out the [add new platform section](/developers/add_new_platform/). +If you want to add support for a new platform, check out the [add new platform section](/developers/add_new_platform/). #### {% linkable_title Components that respond to events that happen within Home Assistant %} These components provide small pieces of home automation logic or services that do common tasks within your house. -For example the [`device_sun_light_trigger` component](/components/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines: +For example, the [`device_sun_light_trigger` component](/components/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this: ```plain In the event that device 'Paulus Nexus 5' changes to the 'Home' state: @@ -52,17 +50,17 @@ For example the [`device_sun_light_trigger` component](/components/device_sun_li Turn on the lights ``` -An extended example of a home automation component can be found [here](https://github.com/home-assistant/home-assistant/blob/master/config/custom_components/example.py). +Look [here](https://github.com/home-assistant/home-assistant/blob/master/config/custom_components/example.py) for an extended example of a home automation component. ### {% linkable_title The full picture %} -When we put all the different pieces of Home Assistant together we see that we match pretty close to the initial sketched home automation overview. The smart home AI is not implemented yet and therefore omitted from the following picture. +When we put all the different pieces of Home Assistant together, it's a close match for the initial home automation overview sketch. The smart home AI is not implemented yet, so it's not included in this picture.

- Overview of the full Home Assistant architecture with a couple of loaded components and platforms. + Overview of the full Home Assistant architecture with a couple of loaded components and platforms

-The platform logic for components uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community. +The platform logic for components uses third-party Python libraries to communicate with the devices so we can leverage the great device libraries in the Python community. From 897aad07f56edadd892db253935345e2cacde152 Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 15:02:27 -0400 Subject: [PATCH 05/16] Fixed a couple typos and format inconsistencies (#1112) --- source/developers/architecture.markdown | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/source/developers/architecture.markdown b/source/developers/architecture.markdown index 5bebf0a0d30..70912917a7c 100644 --- a/source/developers/architecture.markdown +++ b/source/developers/architecture.markdown @@ -9,7 +9,9 @@ sharing: true footer: true --- -Before we dive into the Home Assistant architecture, it is important to get a clear overview of the home automation landscape as a whole. This will allow us to show how the different parts of Home Assistant fit in the picture. For a more lengthy discussion about what each part in this overview is responsible for, check out our blog. A tl;dr version of the blog: +Before we dive into the Home Assistant architecture, let's get a clear overview of the home automation landscape as a whole. This way, we can show how the different parts of Home Assistant fit into the picture. + +For more information about each part in this overview, check out our blog. Here's the tl;dr version of the blog: * Home Control is responsible for collecting information and controlling devices. * Home Automation triggers commands based on user configurations. @@ -20,15 +22,15 @@ Before we dive into the Home Assistant architecture, it is important to get a cl Home Automation landscape - Overview of the home automation landscape. + Overview of the home automation landscape

-The Home Assistant core is responsible for Home Control. It has four parts to make this possible: +The Home Assistant core is responsible for Home Control. Home Assistant has four parts to make this possible: - * The **Event Bus** facilitates the firing and listening of events. This is the beating heart of Home Assistant. - * The **State Machine** keeps track of the states of things. It fires a `state_changed` event when a state has been changed. - * The **Service Registry** listens on the event bus for `call_service` events and allows other code to register services. - * The **Timer** will send a `time_changed` event every 1 second on the event bus. + * **Event Bus**: facilitates the firing and listening of events--the beating heart of Home Assistant. + * **State Machine**: keeps track of the states of things and fires a `state_changed` event when a state has been changed. + * **Service Registry**: listens on the event bus for `call_service` events and allows other code to register services. + * **Timer**: sends a `time_changed` event every 1 second on the event bus.

From 6876d7b76474b57338bca2ecc04597aee31be920 Mon Sep 17 00:00:00 2001 From: Carlo Costanzo Date: Tue, 4 Oct 2016 16:02:02 -0400 Subject: [PATCH 06/16] Update RPI user names (#1117) Make a note for users to note the different user names used in the different installation types. --- source/getting-started/installation-raspberry-pi.markdown | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/getting-started/installation-raspberry-pi.markdown b/source/getting-started/installation-raspberry-pi.markdown index 5b42f7233e4..fadd27addc6 100644 --- a/source/getting-started/installation-raspberry-pi.markdown +++ b/source/getting-started/installation-raspberry-pi.markdown @@ -13,8 +13,12 @@ footer: true There's currently three documented ways to install Home Assistant on a Raspberry Pi. - [Manual installation](/getting-started/installation-raspberry-pi/#Manual-Installation). Following this guide doing each step manually. This is highly recommended as a first installation since you get a good overview of the installation. - - [Hassbian image](/getting-started/installation-raspberry-pi-image). Basic installation with the same settings as following the manual installation guide. Some additional software is preinstalled to make installation quicker and easier. - - [All-in-One Installer](/getting-started/installation-raspberry-pi-all-in-one/). Fabric based installation script that installs and compiles many of the things an advanced Home Assistant install is likely to need. + - [Hassbian image](/getting-started/installation-raspberry-pi-image). Basic installation with the same settings as following the manual installation guide. Some additional software is preinstalled to make installation quicker and easier. Installation uses `homeassistant` user. + - [All-in-One Installer](/getting-started/installation-raspberry-pi-all-in-one/). Fabric based installation script that installs and compiles many of the things an advanced Home Assistant install is likely to need. Installation uses `hass` user. + +

+ Since each installation type uses a different user for Home Assistant, be sure to note and use the correct username for the `adduser` commands listed below for camera and GPIO extensions. +

### {% linkable_title Manual Installation %} From a5530c0d29fc4dfb4747d7ec38208acf7a42d21a Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 16:02:42 -0400 Subject: [PATCH 07/16] Fixed the numbering (#1118) my previous edits separated it into 2 lists that each started with 1. This should be fixed now! --- source/developers/development_submitting.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/developers/development_submitting.markdown b/source/developers/development_submitting.markdown index 0faeca19b0b..d72120f75ec 100644 --- a/source/developers/development_submitting.markdown +++ b/source/developers/development_submitting.markdown @@ -13,7 +13,7 @@ Submit your improvements, fixes, and new features to Home Assistant one at a tim 1. From your fork, create a new branch to hold your changes: - `git checkout -b some-feature` + `git checkout -b some-feature` 2. Make your changes, create a [new platform](/developers/add_new_platform/), develop a [new component](/developers/creating_components/), or fix [issues](https://github.com/home-assistant/home-assistant/issues). @@ -25,7 +25,7 @@ Submit your improvements, fixes, and new features to Home Assistant one at a tim `git commit -m "Added some-feature"` - * Consider adding tests to ensure that your code works. + * Consider adding tests to ensure that your code works. 5. Push your committed changes back to your fork on GitHub: From 3d6e64e2179dcf65b7e4dad6acaadb52f92b2753 Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 16:03:20 -0400 Subject: [PATCH 08/16] Revised item phrasing; consistency (#1119) --- source/developers/development_checklist.markdown | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/source/developers/development_checklist.markdown b/source/developers/development_checklist.markdown index ac2638454ac..9982ffaa24e 100644 --- a/source/developers/development_checklist.markdown +++ b/source/developers/development_checklist.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "Checklist" -description: "Overview of the requirements for an improvment for Home Assistant." +title: "Development Checklist" +description: "Overview of the requirements for an improvement for Home Assistant." date: 2016-07-01 20:00 sidebar: true comments: false @@ -10,10 +10,11 @@ footer: true --- -After you finish your work: +Before you commit any changes, check your work against these requirements: - - Check that all dependencies are included via the `REQUIREMENTS` variable in your platform/component and only imported inside functions that use them. - - Add any new dependencies to `requirements_all.txt` if needed. Use `script/gen_requirements_all.py`. - - Update the `.coveragerc` file to exclude your platform if there are no tests available or your new code uses a 3rd party library for communication with the device/service/sensor. - - Provide some documentation for [home-assistant.io](https://home-assistant.io/). It's OK to just add a docstring with configuration details (sample entry for `configuration.yaml` file and alike) to the file header as a start. Visit the [website documentation](/developers/website/) for further information on contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.github.io). +- All dependencies are included via the `REQUIREMENTS` variable in your platform or component and only imported inside functions that use them +- New dependencies are added to `requirements_all.txt` (if applicable), using `script/gen_requirements_all.py` +- The `.coveragerc` file is updated to exclude your platform if there are no tests available or your new code uses a third-party library for communication with the device, service, or sensor +- Documentation is developed for [home-assistant.io](https://home-assistant.io/) + * It's OK to start with adding a docstring with configuration details (for example, sample entry for `configuration.yaml` file) to the file header. Visit the [website documentation](/developers/website/) for more information about contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.github.io). From a592f97e018445589310ef3f69ec2a655b5da10c Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 16:04:18 -0400 Subject: [PATCH 09/16] Fixed typos/grammar/format (#1120) --- .../developers/development_testing.markdown | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/source/developers/development_testing.markdown b/source/developers/development_testing.markdown index 068e9ebc672..71a636977b0 100644 --- a/source/developers/development_testing.markdown +++ b/source/developers/development_testing.markdown @@ -9,31 +9,31 @@ sharing: true footer: true --- -Home Assistant enforces strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) compliance on all code submitted. Every Pull Request is automatically tested with [Coveralls](https://coveralls.io/github/home-assistant/home-assistant) and [Travis CI](https://travis-ci.org/home-assistant/home-assistant) after it is created. +Home Assistant enforces strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) compliance on all code submitted. We automatically test every pull request with [Coveralls](https://coveralls.io/github/home-assistant/home-assistant) and [Travis CI](https://travis-ci.org/home-assistant/home-assistant). ### {% linkable_title Local testing %} -It's highly recommended to run `tox` before you create your Pull Request to avoid annoying fixes. Local testing requires `tox` to be installed. +**Important:** Run tox before you create your pull request to avoid annoying fixes. Local testing requires installing tox. ```bash $ pip3 install tox ``` -Start the test of your code with `tox`. +Start your code test with `tox`. ```bash $ tox ``` -This will run unit tests against python 3.4 and 3.5 (if both are available locally), as well as run a set of tests which validate `pep8` and `pylint` style of the code. +This will run unit tests against Python 3.4 and 3.5 (if both are available locally), as well as tests that validate `pep8` and `pylint` style. #### {% linkable_title Testing Tips %} -You can optionally run tests on only one tox target using the `-e` option to select an environment. For instance `tox -e lint` will run the linters only, `tox -e py34` will run unit tests only on python 3.4. +You can run tests on only one tox target -- just use `-e` to select an environment. For example, `tox -e lint` runs the linters only, and `tox -e py34` runs unit tests only on Python 3.4. -Tox uses virtual environments under the hood to create isolated testing environments. The Tox virtual environments will get out date when requirements change causing test errors. Run `tox -r` to create new Tox virtual environments. +tox uses virtual environments under the hood to create isolated testing environments. The tox virtual environments will get out-of-date when requirements change, causing test errors. Run `tox -r` to create new tox virtual environments. -During development on a specific file, it can speed up your workflow to just run tests and linting related to the file that you're working on. To run individual files: +During development on a specific file, speed up your workflow by running tests and linting only for the file that you're working on. To run individual files: ```bash $ flake8 homeassistant/core.py @@ -41,24 +41,23 @@ $ pylint homeassistant/core.py $ py.test tests/test_core.py ``` -You also run linting tests against all changed files, as reported by `git diff upstream/dev --name-only` using the `lint` script: +You can also run linting tests against all changed files, as reported by `git diff upstream/dev --name-only`, using the `lint` script: ```bash home-assistant$ script/lint --changed ``` -### {% linkable_title Prevent Linter Errors %} +### {% linkable_title Preventing Linter Errors %} -You can save yourself the hassle of extra commits just to fix style errors by enabling the flake8 git commit hook. It will check your code when you attempt to commit to the repository. It will block the commit if there are any style issues, giving you a chance to fix it. +Save yourself the hassle of extra commits just to fix style errors by enabling the Flake8 git commit hook. Flake8 will check your code when you try to commit to the repository and block the commit if there are any style errors, which gives you a chance to fix them! ```bash $ pip3 install flake8 flake8-docstrings $ flake8 --install-hook=git ``` -The flake8-docstrings extension will check docstrings according to [PEP257](https://www.python.org/dev/peps/pep-0257/) when running flake8. +The `flake8-docstrings` extension will check docstrings according to [PEP257](https://www.python.org/dev/peps/pep-0257/) when running Flake8. ### {% linkable_title 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`. Example of an unavoidable PyLint warning is if you do not use the passed in datetime if you're listening for time change. - +If you can't avoid a PyLint warning, add a comment to disable the PyLint check for that line with `# pylint: disable=YOUR-ERROR-NAME`. An example of an unavoidable PyLint warning is not using the passed-in datetime if you're listening for a time change. From 7b5efaa7a14072545710f949471e5bb7ced53ba5 Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 16:20:20 -0400 Subject: [PATCH 10/16] Fixed typos (#1122) --- .../developers/development_catching_up.markdown | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/source/developers/development_catching_up.markdown b/source/developers/development_catching_up.markdown index cbcd959615a..7bfc8064805 100644 --- a/source/developers/development_catching_up.markdown +++ b/source/developers/development_catching_up.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -If you're taking a while developing your feature and would like to catch up with what's in the current Home Assistant `dev` branch, you can use `git rebase` to do so. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant and then replay all of your commits on top. +If it's taking a while to develop your feature, and you want to catch up with what's in the current Home Assistant `dev` branch, you can use `git rebase`. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant, and replay all of your commits on top. ```bash # Run this from your feature branch @@ -17,19 +17,18 @@ $ git fetch upstream dev # to pull the latest changes into a local dev branch $ git rebase upstream/dev # to put those changes into your feature branch before your changes ``` -If rebase detects conflicts, you can repeat the following process until all changes have been resolved: +If rebase detects conflicts, repeat this process until all changes have been resolved: -1. `git status` will show you the file with the conflict. -2. Edit the file and resolving the lines between `<<<< | >>>>` -3. Add the modified file `git add ` or `git add .` -4. Continue rebase `git rebase --continue` -5. Repeat until you've resolved all conflicts. +1. `git status` shows you the file with the conflict; edit the file and resolve the lines between `<<<< | >>>>` +3. Add the modified file: `git add ` or `git add .` +4. Continue rebase: `git rebase --continue` +5. Repeat until you've resolved all conflicts -There is other workflows that is covered in detail in the [Github documentation](https://help.github.com/articles/fork-a-repo/). Add an additional `remote` after you clone your fork. +Other workflows are covered in detail in the [Github documentation](https://help.github.com/articles/fork-a-repo/). Add an additional `remote` after you clone your fork. ```bash $ git remote add upstream https://github.com/home-assistant/home-assistant.git ``` -and then simply `git pull --rebase upstream dev`. +Then, `git pull --rebase upstream dev`. From 93b097fd9cef9766be3c0e22885f1f4042e5ce75 Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 16:39:18 -0400 Subject: [PATCH 11/16] Fixed typos and format inconsistencies (#1123) Please check these sentences: "We test the configuration to ensure that users have a great experience and minimize notifications if something is wrong with a platform or component setup before Home Assistant runs." "If a sensor has a pre-defined list of available options, test to make sure the configuration entry matches the list." I wasn't sure if I got the intent correct, and in the second one I wasn't sure what you meant by "it" --- .../development_validation.markdown | 34 +++++++++---------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/source/developers/development_validation.markdown b/source/developers/development_validation.markdown index 50d0a675df4..93a1438f283 100644 --- a/source/developers/development_validation.markdown +++ b/source/developers/development_validation.markdown @@ -9,11 +9,11 @@ sharing: true footer: true --- -The `configuration.yaml` file contains the configuration options for components and platforms. To ensure that the given configuration provided by the user is valid we use [voluptuous](https://pypi.python.org/pypi/voluptuous) to check it. Certain entries are optional or could be required for the setup of a platform or a component. Others must be of a definied type or out of an already defined list. +The `configuration.yaml` file contains the configuration options for components and platforms. We use [voluptuous](https://pypi.python.org/pypi/voluptuous) to make sure that the configuration provided by the user is valid. Some entries are optional or could be required to set up a platform or a component. Others must be a defined type or from an already-defined list. -The goal of testing the configuration is to assure that users have a great experience due to notifications if something is wrong with a platform or component setup before Home Assistant is running. +We test the configuration to ensure that users have a great experience and minimize notifications if something is wrong with a platform or component setup before Home Assistant runs. -Beside the [voluptuous](https://pypi.python.org/pypi/voluptuous) default types are a bunch of custom types available. To get a full overview take a look at the [config_validation.py](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/config_validation.py) helper. +Besides [voluptuous](https://pypi.python.org/pypi/voluptuous) default types, many custom types are available. For an overview, take a look at the [config_validation.py](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/config_validation.py) helper. - Types: `string`, `byte`, and `boolean` - Entity ID: `entity_id` and `entity_ids` @@ -21,21 +21,21 @@ Beside the [voluptuous](https://pypi.python.org/pypi/voluptuous) default types a - Time: `time`, `time_zone` - Misc: `template`, `slug`, `temperature_unit`, `latitude`, `longitude`, `isfile`, `sun_event`, `ensure_list`, `port`, `url`, and `icon` -To validate plaforms using [MQTT](/components/mqtt/) there are `valid_subscribe_topic` and `valid_publish_topic` present. +To validate plaforms using [MQTT](/components/mqtt/), `valid_subscribe_topic` and `valid_publish_topic` are available. Some things to keep in mind: -- Use the constants which are definded in `const.py`. -- Import `PLATFORM_SCHEMA` from parent component and extend it. -- Preferred order is `required` first, then `optional`. +- Use the constants defined in `const.py` +- Import `PLATFORM_SCHEMA` from the parent component and extend it +- Preferred order is `required` first and `optional` second ### {% linkable_title Snippets %} -This section contains a couple of snippets for the validation we use. +This section contains snippets for the validation we use. -### {% linkable_title Default name %} +#### {% linkable_title Default name %} -It's common to set a default for a sensor if the user is not providing a name to use. +It's common to set a default for a sensor if the user doesn't provide a name to use. ```python DEFAULT_NAME = 'Sensor name' @@ -45,9 +45,9 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string, ``` -### {% linkable_title Limit the values %} +#### {% linkable_title Limit the values %} -In certain cases you want to limit the user's input to a couple of options. +You might want to limit the user's input to a couple of options. ```python DEFAULT_METHOD = 'GET' @@ -57,9 +57,9 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ vol.Optional(CONF_METHOD, default=DEFAULT_METHOD): vol.In(['POST', 'GET']), ``` -### {% linkable_title Port %} +#### {% linkable_title Port %} -As all port numbers are coming out of the range 1 till 65535. +All port numbers are from a range of 1 to 65535. ```python DEFAULT_PORT = 993 @@ -69,9 +69,9 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port, ``` -### {% linkable_title Lists %} +#### {% linkable_title Lists %} -If a sensor has a pre-defined list of available options it should be tested if the configuration entry matches it. +If a sensor has a pre-defined list of available options, test to make sure the configuration entry matches the list. ```python SENSOR_TYPES = { @@ -84,5 +84,3 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ vol.Optional(CONF_MONITORED_VARIABLES, default=[]): vol.All(ensure_list, [vol.In(SENSOR_TYPES)]), ``` - - From f97e42314a5bf2b4fc3e49922a4b93af29f596aa Mon Sep 17 00:00:00 2001 From: Hillary Fraley Date: Tue, 4 Oct 2016 16:40:29 -0400 Subject: [PATCH 12/16] Found numbering problem in this one too - fixed (#1124) --- .../development_environment.markdown | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/developers/development_environment.markdown b/source/developers/development_environment.markdown index de667145236..3e44e9f7f39 100644 --- a/source/developers/development_environment.markdown +++ b/source/developers/development_environment.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "Setup Development Environment" -description: "Setup your environment to start developing for Home Assistant." +title: "Set up Development Environment" +description: "Set up your environment to start developing for Home Assistant." date: 2014-12-21 13:32 sidebar: true comments: false @@ -13,15 +13,15 @@ You'll need to set up a development environment if you want to develop a new fea 1. Visit the [the Home Assistant repository](https://github.com/home-assistant/home-assistant) and click "fork." - * Consider setting up a virtual environment using [`venv`](https://docs.python.org/3.4/library/venv.html) before running the setup script. + * Consider setting up a virtual environment using [`venv`](https://docs.python.org/3.4/library/venv.html) before running the setup script. - ```bash - $ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git - $ cd home-assistant - $ git remote add upstream https://github.com/home-assistant/home-assistant.git - $ script/setup - ``` - * On Windows, you can use `python setup.py develop` instead of the setup script. + ```bash + $ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git + $ cd home-assistant + $ git remote add upstream https://github.com/home-assistant/home-assistant.git + $ script/setup + ``` + * On Windows, you can use `python setup.py develop` instead of the setup script. 2. Run `hass` to invoke your local installation. From be92f2cf2218a46fc7e0a6d66468551d559ca3f2 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 4 Oct 2016 23:29:35 +0200 Subject: [PATCH 13/16] Add more details --- source/_components/notify.telegram.markdown | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/source/_components/notify.telegram.markdown b/source/_components/notify.telegram.markdown index 4044f9ff3f1..bb906db264c 100644 --- a/source/_components/notify.telegram.markdown +++ b/source/_components/notify.telegram.markdown @@ -20,7 +20,7 @@ The requirements are: - You need a [Telegram bot](https://core.telegram.org/bots). Please follow those [instructions](https://core.telegram.org/bots#botfather) to create one and get the token for your bot. Keep in mind that bots are not allowed to contact users. You need to make the first contact with your user. Meaning that you need to send a message to the bot from your user. - The `chat_id` of an user. -The quickest way to retrieve your `chat_id` is visiting [https://api.telegram.org/botYOUR_API_TOKEN/getUpdates](https://api.telegram.org/botYOUR_API_TOKEN/getUpdates). +The quickest way to retrieve your `chat_id` is visiting [https://api.telegram.org/botYOUR_API_TOKEN/getUpdates](https://api.telegram.org/botYOUR_API_TOKEN/getUpdates) or to use `$ curl -X GET https://api.telegram.org/botYOUR_API_TOKEN/getUpdates`. Replace `YOUR_API_TOKEN` with your actual token. The result set will include your chat ID as `id` in the `from` section: @@ -29,13 +29,14 @@ The result set will include your chat ID as `id` in the `from` section: "message":{"message_id":27,"from":{"id":123456789,"first_name":"YOUR_FIRST_NAME YOUR_NICK_NAME","last_name":"YOUR_LAST_NAME","username":"YOUR_NICK_NAME"},"chat":{"id":123456789,"first_name":"YOUR_FIRST_NAME YOUR_NICK_NAME","last_name":"YOUR_LAST_NAME","username":"YOUR_NICK_NAME","type":"private"},"date":1678292650,"text":"test"}}]} ``` -Another way to get your chat ID directly is described below: +Another way to get your chat ID directly is described below. Start your Python interpreter from the command-line: ```python -import telegram -bot = telegram.Bot(token='YOUR_API_TOKEN') -chat_id = bot.getUpdates()[-1].message.chat_id -print(chat_id) +$ python3 +>>> import telegram +>>> bot = telegram.Bot(token='YOUR_API_TOKEN') +>>> chat_id = bot.getUpdates()[-1].message.chat_id +>>> print(chat_id) 123456789 ``` From e7e50695f92d76b8a65bf6e3915eaa0ac86246ec Mon Sep 17 00:00:00 2001 From: Jerold Albertson Date: Tue, 4 Oct 2016 15:59:08 -0600 Subject: [PATCH 14/16] Fixed a small type. :) (#1125) notifiy -> notify --- source/_cookbook/python_component_simple_alarm.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_cookbook/python_component_simple_alarm.markdown b/source/_cookbook/python_component_simple_alarm.markdown index e014a695f02..33f0d79132a 100644 --- a/source/_cookbook/python_component_simple_alarm.markdown +++ b/source/_cookbook/python_component_simple_alarm.markdown @@ -10,7 +10,7 @@ footer: true ha_category: Automation in Python Examples --- -This example component will detect intruders. It does so by checking if lights are being turned on while there is no one at home. When this happens it will turn the lights red, flash them for 30 seconds and send a message via [the notifiy component](/components/notify/). It will also flash a specific light when a known person comes home. +This example component will detect intruders. It does so by checking if lights are being turned on while there is no one at home. When this happens it will turn the lights red, flash them for 30 seconds and send a message via [the notify component](/components/notify/). It will also flash a specific light when a known person comes home. This component depends on the components [device_tracker](/components/device_tracker/) and [light](/components/light/) being setup. From ec85730925fdcd744fb738a5bf7fddd6fd6dc397 Mon Sep 17 00:00:00 2001 From: Jerold Albertson Date: Tue, 4 Oct 2016 15:59:56 -0600 Subject: [PATCH 15/16] Fixed a small type. :) (#1126) whem -> when --- source/_cookbook/python_component_simple_alarm.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_cookbook/python_component_simple_alarm.markdown b/source/_cookbook/python_component_simple_alarm.markdown index 33f0d79132a..2ac645b46c3 100644 --- a/source/_cookbook/python_component_simple_alarm.markdown +++ b/source/_cookbook/python_component_simple_alarm.markdown @@ -43,11 +43,11 @@ DOMAIN = "simple_alarm" DEPENDENCIES = ['group', 'device_tracker', 'light'] -# Attribute to tell which light has to flash whem a known person comes home +# Attribute to tell which light has to flash when a known person comes home # If omitted will flash all. CONF_KNOWN_LIGHT = "known_light" -# Attribute to tell which light has to flash whem an unknown person comes home +# Attribute to tell which light has to flash when an unknown person comes home # If omitted will flash all. CONF_UNKNOWN_LIGHT = "unknown_light" From d1e73df608e114145e2979f32a183c15bbbc3a62 Mon Sep 17 00:00:00 2001 From: Jerold Albertson Date: Tue, 4 Oct 2016 16:04:36 -0600 Subject: [PATCH 16/16] Fixed a small type. :) (#1127) Grammar: Notifications send through -> Send notifications through --- source/_cookbook/automation_sun.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_cookbook/automation_sun.markdown b/source/_cookbook/automation_sun.markdown index d673599b9bb..25edee45576 100644 --- a/source/_cookbook/automation_sun.markdown +++ b/source/_cookbook/automation_sun.markdown @@ -46,7 +46,7 @@ automation: #### {% linkable_title Send sun rise/sun set notifications %} -Notifications send through [PushBullet](/components/notify.pushbullet/) when the sun state is changed. +Send notifications through [PushBullet](/components/notify.pushbullet/) when the sun state is changed. ```yaml automation: