Merge branch 'master' into next
This commit is contained in:
Fabian Affolter
commit
60bb3f4e20
47 changed files with 577 additions and 153 deletions
22
source/developers/component_states.markdown
Normal file
22
source/developers/component_states.markdown
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Handling states"
|
||||
description: "Instructions how to handle states with your component."
|
||||
date: 2016-07-01 20:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
It is the responsibility of the component to maintain the states of the devices in your domain. Each device should be a single state and, if possible, a group should be provided that tracks the combined state of the devices.
|
||||
|
||||
A state can have several attributes that will help the frontend in displaying your state:
|
||||
|
||||
- `friendly_name`: this name will be used as the name of the device
|
||||
- `entity_picture`: this picture will be shown instead of the domain icon
|
||||
- `unit_of_measurement`: this will be appended to the state in the interface
|
||||
- `hidden`: This is a suggestion to the frontend on if the state should be hidden
|
||||
|
||||
These attributes are defined in [homeassistant.helpers.entity](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py#L180).
|
||||
|
||||
21
source/developers/component_visibility.markdown
Normal file
21
source/developers/component_visibility.markdown
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Handling visibility"
|
||||
description: "Instructions how to handle visibility with your component."
|
||||
date: 2016-07-01 20:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Generally, when creating a new entity for Home Assistant you will want it to be a class that inherits the [homeassistant.helpers.entity.Entity](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py) class. If this is done, visibility will be handled for you.
|
||||
You can set a suggestion for your entity's visibility by setting the `hidden` property by doing something similar to the following.
|
||||
|
||||
```python
|
||||
self.hidden = True
|
||||
```
|
||||
|
||||
This will SUGGEST that the active frontend hides the entity. This requires that the active frontend support hidden cards (the default frontend does) and that the value of hidden be included in your attributes dictionary (see above). The Entity abstract class will take care of this for you.
|
||||
|
||||
Remember: The suggestion set by your component's code will always be overwritten by user settings in the configuration.yaml file. This is why you may set hidden to be False, but the property may remain True (or vice-versa).
|
||||
|
|
@ -24,12 +24,14 @@ This page contains a list of people who have contributed in one way or another t
|
|||
- [Alexander Fortin](https://github.com/shaftoe)
|
||||
- [Alex Harvey](https://github.com/infamy)
|
||||
- [Allan Glen](https://github.com/allanglen)
|
||||
- [AlucardZero](https://github.com/AlucardZero)
|
||||
- [amorsillo](https://github.com/fignuts)
|
||||
- [Andrew](https://github.com/aoakeson)
|
||||
- [Andrew LeCody](https://github.com/aceat64)
|
||||
- [Andy Loughran](https://github.com/andylockran)
|
||||
- [andythigpen](https://github.com/andythigpen)
|
||||
- [Antonio Párraga Navarro](https://github.com/aparraga)
|
||||
- [Ardetus](https://github.com/Ardetus)
|
||||
- [Ardi Mehist](https://github.com/omgapuppy)
|
||||
- [arsaboo](https://github.com/arsaboo/)
|
||||
- [Arthur Leonard Andersen](https://github.com/leoc)
|
||||
|
|
@ -48,7 +50,7 @@ This page contains a list of people who have contributed in one way or another t
|
|||
- [coteyr](https://github.com/coteyr/)
|
||||
- [Dale Higgs](https://github.com/dale3h)
|
||||
- [Dan Cinnamon](https://github.com/Cinntax)
|
||||
- [Daniel](https://github.com/danielperna84)
|
||||
- [Daniel Perna](https://github.com/danielperna84)
|
||||
- [Daniel Iversen](https://github.com/danielhiversen)
|
||||
- [Daniel J. Kemp](https://github.com/danieljkemp/)
|
||||
- [Daniel Matuschek](https://github.com/usul27)
|
||||
|
|
@ -119,10 +121,9 @@ This page contains a list of people who have contributed in one way or another t
|
|||
- [Martin Hjelmare](https://github.com/MartinHjelmare)
|
||||
- [Matteo Lampugnani](https://github.com/t30)
|
||||
- [Matthew Treinish](https://github.com/mtreinish/)
|
||||
- [Michael Arnauts](https://github.com/michaelarnauts)
|
||||
- [Michael Auchter](https://github.com/auchter)
|
||||
- [Michaël Arnauts](https://github.com/michaelarnauts)
|
||||
- [Michael Gilbert](https://github.com/Zyell)
|
||||
- [Michael Kuty](https://github.com/michaelkuty)
|
||||
- [Michael Kutý](https://github.com/michaelkuty)
|
||||
- [Micha LaQua](https://github.com/milaq)
|
||||
- [miniconfig](https://github.com/miniconfig)
|
||||
- [molobrakos](https://github.com/molobrakos)
|
||||
|
|
|
|||
19
source/developers/development.markdown
Normal file
19
source/developers/development.markdown
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Starting with Development"
|
||||
description: "Everything to get you started developing for Home Assistant."
|
||||
date: 2014-12-21 13:32
|
||||
sidebar: true
|
||||
comments: false
|
||||
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 open-source and MIT licensed. The source can be found here:
|
||||
|
||||
- [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
|
||||
|
||||
35
source/developers/development_catching_up.markdown
Normal file
35
source/developers/development_catching_up.markdown
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Catching up with Reality"
|
||||
description: "Update your fork with the latest commit."
|
||||
date: 2016-07-01 20:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
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.
|
||||
|
||||
```bash
|
||||
# Run this from your feature branch
|
||||
$ 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:
|
||||
|
||||
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 <file>` 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.
|
||||
|
||||
```bash
|
||||
$ git remote add upstream https://github.com/home-assistant/home-assistant.git
|
||||
```
|
||||
|
||||
and then simply `git pull --rebase upstream dev`.
|
||||
|
||||
19
source/developers/development_checklist.markdown
Normal file
19
source/developers/development_checklist.markdown
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Checklist"
|
||||
description: "Overview of the requirements for an improvment for Home Assistant."
|
||||
date: 2016-07-01 20:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
|
||||
After you finish your work:
|
||||
|
||||
- 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.io).
|
||||
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Setup Development"
|
||||
description: "Everything to get you started developing for Home Assistant."
|
||||
title: "Setup Development Environment"
|
||||
description: "Setup your environment to start developing for Home Assistant."
|
||||
date: 2014-12-21 13:32
|
||||
sidebar: true
|
||||
comments: false
|
||||
|
|
@ -9,16 +9,6 @@ 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 open-source and MIT licensed. The source can be found here:
|
||||
|
||||
- [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
|
||||
|
||||
### {% linkable_title Starting development %}
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -34,66 +24,3 @@ On Windows you can use `python setup.py develop` instead of the setup script.
|
|||
|
||||
After following these steps, running `hass` will invoke your local installation.
|
||||
|
||||
### {% linkable_title Testing your work %}
|
||||
|
||||
Testing your work requires `tox` to be installed:
|
||||
|
||||
```bash
|
||||
$ pip3 install tox
|
||||
```
|
||||
|
||||
### {% linkable_title Prevent Linter Errors %}
|
||||
|
||||
Home Assistant enforces strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) compliance on all code submitted. 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 repo. It will block the commit if there are any style issues, giving you a chance to fix it.
|
||||
|
||||
```bash
|
||||
$ pip install flake8 flake8-docstrings
|
||||
$ flake8 --install-hook
|
||||
```
|
||||
|
||||
The flake8-docstrings extension will check docstrings according to [PEP257](https://www.python.org/dev/peps/pep-0257/) when running flake8.
|
||||
|
||||
### {% linkable_title Submitting improvements %}
|
||||
|
||||
Improvements to Home Assistant should be submitted one feature at a time using GitHub [pull requests](https://help.github.com/articles/using-pull-requests).
|
||||
|
||||
1. From your fork, create a new branch to hold your changes
|
||||
`git checkout -b some-feature`
|
||||
2. Make the changes you want
|
||||
3. Test your changes and check for style violations
|
||||
`tox`
|
||||
4. Commit the changes
|
||||
`git add .`
|
||||
`git commit -m "Added some-feature"`
|
||||
5. Push your committed changes back to your fork on GitHub
|
||||
`git push origin HEAD`
|
||||
6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request.
|
||||
|
||||
### {% linkable_title Catching up with Reality %}
|
||||
|
||||
If you're taking a while developing your feature request 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.
|
||||
|
||||
```bash
|
||||
# Run this from your feature branch
|
||||
$ 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:
|
||||
|
||||
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 <file>` or `git add .`
|
||||
4. Continue rebase `git rebase --continue`
|
||||
5. Repeat until you've resolved all conflicts.
|
||||
|
||||
### {% linkable_title Further reading %}
|
||||
|
||||
- [Home Assistant Architecture](/developers/architecture/)
|
||||
- [Frontend development](/developers/frontend/)
|
||||
- [Creating a custom component](/developers/creating_components/)
|
||||
- [Adding support for a new platform](/developers/add_new_platform/)
|
||||
- [Rest API](/developers/api/)
|
||||
- [Server-sent events](/developers/server_sent_events/)
|
||||
- [Website](/developers/website/)
|
||||
- [Home Assitant on Github - CONTRIBUTING.md](https://github.com/home-assistant/home-assistant/blob/dev/CONTRIBUTING.md)
|
||||
|
|
|
|||
26
source/developers/development_submitting.markdown
Normal file
26
source/developers/development_submitting.markdown
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Submit your work"
|
||||
description: "Submit your work as Pull Request for Home Assistant."
|
||||
date: 2016-07-01 20:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
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).
|
||||
|
||||
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.
|
||||
`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
|
||||
`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/).
|
||||
|
||||
48
source/developers/development_testing.markdown
Normal file
48
source/developers/development_testing.markdown
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Testing your code"
|
||||
description: "Make sure that your code passes the checks"
|
||||
date: 2016-07-01 20:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
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.
|
||||
|
||||
### {% linkable_title Local testing %}
|
||||
|
||||
It's highly recommanded to run `tox` before you create your Pull Request to avoid annoying fixes. Local testing requires `tox` to be installed.
|
||||
|
||||
```bash
|
||||
$ pip3 install tox
|
||||
```
|
||||
|
||||
Start the test of your code 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.
|
||||
|
||||
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.
|
||||
|
||||
### {% linkable_title Prevent 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.
|
||||
|
||||
```bash
|
||||
$ pip3 install flake8 flake8-docstrings
|
||||
$ flake8 --install-hook
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -29,6 +29,8 @@ http:
|
|||
development: 1
|
||||
```
|
||||
|
||||
As everything is compiled into the file `frontend.html` you do not want to work with the compiled version but with the seperate files during development.
|
||||
|
||||
Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend repository is not cloned by default. You can setup the frontend development environment by running:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
37
source/developers/releasing.markdown
Normal file
37
source/developers/releasing.markdown
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Releasing"
|
||||
description: "Steps involved to publish a new Home Assistant release."
|
||||
date: 2016-07-13 17:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
This page describes the steps for publishing a new Home Assistant release.
|
||||
|
||||
### {% linkable_title GitHub %}
|
||||
|
||||
1. Create a pull request from `dev` to `master` with the upcoming release number as title.
|
||||
2. Merge `master` into `dev` to make the PR mergable. PR message contains intro, highlighting major changes, and an overview of all changes tagging each author.
|
||||
3. Merge pull request.
|
||||
4. Go to [releases](https://github.com/home-assistant/home-assistant/releases) and tag a new release on the `master` branch. Tag name and title name are version number. Release description is text from PR.
|
||||
|
||||
### {% linkable_title Website %}
|
||||
|
||||
1. Create a blog post and base it on the PR text. Add images, additional text, links, etc. if it adds value. Tag each platform/component in message to documentation.
|
||||
2. Create missing documentation as stumbs.
|
||||
3. Update the link on the frontpage (`source/index.html`) to link to the new release blog post and version number.
|
||||
4. Merge blog post and updated frontpage to `master` (`git merge next`).
|
||||
5. Change to `next` and merge with `master` (`git checkout next && git merge master`) to keep in sync.
|
||||
|
||||
### {% linkable_title Python Package Index %}
|
||||
|
||||
Checkout `master` branch and run `script/release` to publish the new release on [Python Package Index](https://pypi.python.org)
|
||||
|
||||
### {% linkable_title Social media %}
|
||||
|
||||
1. Create a [tweet](https://twitter.com/home_assistant) announcing blog post linking to release notes.
|
||||
2. Publish a link to the tweet/release blog post for the [Google+ Community](https://plus.google.com/b/110560654828510104551/communities/106562234893511202708).
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue